rfc:php_namespace_policy

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
rfc:php_namespace_policy [2020/06/24 00:24] – Formatting crellrfc:php_namespace_policy [2020/08/10 13:41] (current) – crell
Line 3: Line 3:
   * Date: 2020-04-15    * Date: 2020-04-15 
   * Author: Mark Randall (marandall@php.net), Larry Garfield (larry@garfieldtech.com)   * Author: Mark Randall (marandall@php.net), Larry Garfield (larry@garfieldtech.com)
-  * Status: Under Discussion+  * Status: Declined
   * First Published at: https://wiki.php.net/rfc/php_namespace_policy   * First Published at: https://wiki.php.net/rfc/php_namespace_policy
  
Line 13: Line 13:
  
   * Formally reserve the \PHP namespace for use by PHP-SRC.  It has been quasi-soft-reserved since namespaces were added, but never used because we couldn't agree on when or how to do so.  So, let's do so.   * Formally reserve the \PHP namespace for use by PHP-SRC.  It has been quasi-soft-reserved since namespaces were added, but never used because we couldn't agree on when or how to do so.  So, let's do so.
 +
 +  * Formally reserve the \Ext namespace for use by extensions, either PECL or in core.
  
   * Establish heuristics regarding when and how namespaced classes should be used.  In practice there cannot be precise rules in advance for every case, but by offering a common heuristic we hope to eliminate //most// purely subjective debate in the future.   * Establish heuristics regarding when and how namespaced classes should be used.  In practice there cannot be precise rules in advance for every case, but by offering a common heuristic we hope to eliminate //most// purely subjective debate in the future.
Line 21: Line 23:
 This RFC does NOT propose moving any existing code into the \PHP namespace at this time.  That may be done by future RFCs if desired, under their own votes.  This is a "policy document" only. This RFC does NOT propose moving any existing code into the \PHP namespace at this time.  That may be done by future RFCs if desired, under their own votes.  This is a "policy document" only.
  
-===== Namespace Policy =====+===== Definitions =====
  
 +  * **Vendor namespace**: The top-level namespace in a symbol name.  For example, in \Foo\Bar\Baz, "Foo" is the vendor.
 +
 +  * **Component namespace**: The second level namespace in a symbol name.  For example, in \Foo\Bar\Baz, "Bar" is the component namespace.
 +
 +  * **Class**: For the purpose of this document, "class" means any autoloadable class-like symbol definition.  At this time that means classes, interfaces, and traits.  Future data structure definitions (Enums, typedefs, etc.) MAY be namespaced if they are made autoloadable.  This is to make it easier to write polyfills for new functionality in the future.
 +
 +===== Namespace Policy =====
  
-  - The \PHP namespace is reserved for use by classes provided by PHP-SRC itself.  While userland code that makes use of that namespace will technically run, any impact on such code by future RFCs will not be considered a backward compatibility break. +  - The \PHP vendor namespace is reserved for use by classes provided by PHP-SRC itself.  While userland code that makes use of that namespace will technically run, any impact on such code by future RFCs will not be considered a backward compatibility break. 
-  - Any namespaced code provided by PHP-SRC will use a sub-namespace of \PHP.  That is, no PHP\Foo class may be defined, but a PHP\Foo\Bar class may be.  The sub-namespace is referred to as a "component namespace" for the rest of this document.  Component namespaces should be singular.  That is, \PHP\Attribute\, not \PHP\Attributes\. +  - The \Ext vendor namespace is reserved for use by classes provided by a PHP extension, either bundled with PHP or hosted with PECL.  While userland code that makes use of that namespace will technically run, any impact on such code by future RFCs will not be considered a backward compatibility break. 
-  - A component namespace is "claimed" by the RFC that first uses it. Once claimed, that component namespace may only be used only by that RFC or future RFCs that extend that one in a natural way.  For example, once it's established that \PHP\Attribute\ is the namespace for attributes, additional attribute classes may be defined there but no non-attribute-related classes may be.+  - Any namespaced code provided by PHP-SRC will use a distinct component namespace.  That is, no PHP\Foo class may be defined, but a PHP\Foo\Bar class may be. 
 +  - Component or sub-component namespaces MUST use CamelCase naming conventions. 
 +  - Only classes and other autoloadable symbols (as specified above) may be namespaced.  Constants should be associated to a class within the namespace as appropriate.
   - Component namespaces MAY use sub-components (eg, \PHP\Foo\Bar\), but that SHOULD be discouraged unless there is clear and convincing evidence that it would aid in readability or code organization.   - Component namespaces MAY use sub-components (eg, \PHP\Foo\Bar\), but that SHOULD be discouraged unless there is clear and convincing evidence that it would aid in readability or code organization.
-  - If a feature is removed from PHP-SRC (either to PECL or dropped entirely) its previously claimed component namespace remains reserved.  It MAY be released by a subsequent RFC, following the standard RFC procedure, at least one minor version after the feature is removed.  That delay is to minimize backward compatibility impact and allow userland code to migrate if appropriate. 
-  - Only autoloadable symbols may be namespaced.  At this time that means classes, interfaces, and traits.  Constants should be associated to a class within the namespace as appropriate.  Future data structure definitions (Enums, typedefs, etc.) MAY be namespaced if they are made autoloadable.  This is to make it easier to write polyfills for new functionality in the future. 
   - Classes or other symbols in a component namespace SHOULD NOT repeat the component namespace, unless the class name is extremely generic and easily misunderstood without context.  This requires case-by-case evaluation but the default is to not repeat the namespace without strong justification.   - Classes or other symbols in a component namespace SHOULD NOT repeat the component namespace, unless the class name is extremely generic and easily misunderstood without context.  This requires case-by-case evaluation but the default is to not repeat the namespace without strong justification.
 +
 +===== Namespace index =====
 +
 +A page will be established on the PHP Wiki (this site) to index all explicitly specified component namespaces for both \PHP and \Ext.
 +
 +For \PHP, classes may be added or removed only via RFC.  That may be an RFC to add a feature that uses the namespace or it may be an RFC to rename an existing class to conform to this RFC.
 +
 +A \PHP component namespace is "claimed" by the RFC that first uses it. Once claimed, that component namespace may only be used only by that RFC or future RFCs that extend that one in a natural way.  For example, once it's established that \PHP\Attribute\ is the namespace for attributes, additional attribute classes may be defined there but no non-attribute-related classes may be.  Once the RFC is approved, the namespace should be added to the index.
 +
 +An \Ext component namespace is "claimed" in one of three ways:
 +
 +  - An RFC that creates or migrates a bundled extension.
 +  - A PECL module author may post to the Internals maliing list stating an intent to "claim" an \Ext component namespace for a package.  If there is no negative response within a week, the author may update the index accordingly.  If there is, the author may post an RFC with vote to claim the component.
 +  - PECL module may automatically claim a namespace based on its package name.  For example, a "yoursql" database driver in PECL would implicitly claim the \Ext\YourSQL namespace.
 +  - In case of conflict, an RFC-claimed component name has priority over an explicitly-claimed component name over an implicitly-claimed component name.
  
 ===== Guidelines for namespace usage ===== ===== Guidelines for namespace usage =====
Line 46: Line 70:
   * **Guideline**: A namespace specific to the parent.  Eg, \PHP\Iterator\, \PHP\Attribute\.  As new instances are added they would be added to that component namespace.   * **Guideline**: A namespace specific to the parent.  Eg, \PHP\Iterator\, \PHP\Attribute\.  As new instances are added they would be added to that component namespace.
  
-Classes that provide useful general functionality but do not impact engine behavior +Classes that are part of an extension, disableable or not. 
-  * **Examples**: SPL's collection classes, SPL's file classes, DOM, DateTime et al +  * **Examples**: SimpleXMLElement, SoapClient, Sodium, DOM, SPL 
-  * **Guideline**: A namespace specific to the use case.  Eg, \PHP\DOM\, \PHP\DateTime\, \PHP\SPL\Collections\.  (SPL is a case where sub-components MAY be useful.) +  * **Guideline**: An extension namespace specific to the use case.  Eg, \Ext\Sodium.
- +
-Classes that are part of a disable-able extension +
-  * **Examples**: SimpleXMLElement, SoapClient, Sodium +
-  * **Guideline**: A namespace specific to the use case.  Eg, \PHP\Sodium.+
  
 Cases where it is expected that the number of closely related classes is or is likely to become large Cases where it is expected that the number of closely related classes is or is likely to become large
Line 63: Line 83:
 ===== Upgrade path for existing classes ===== ===== Upgrade path for existing classes =====
  
-This RFC makes no change to existing classes, regardless of where they are defined.  Future RFCs may be proposed to migrate existing classes to a component namespace within \PHP, and put to a vote on their own merits.  Such RFCs must:+This RFC makes no change to existing classes, regardless of where they are defined.  Future RFCs may be proposed to migrate existing classes to a component namespace within \PHP or \Ext as appropriate, and put to a vote on their own merits.  Such RFCs must:
  
 1. Clearly specify what classes or interfaces will migrate to a component namespace, including whether or not their name will be changing in the process. 1. Clearly specify what classes or interfaces will migrate to a component namespace, including whether or not their name will be changing in the process.
Line 71: Line 91:
  
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
-PHP 8.0+PHP 8.0 (doesn't really have an impact until 8.1, however)
  
 ===== Vote ===== ===== Vote =====
-Yes / No  
  
-"Should PHP adopt these guidelines for future RFC authors to guide when and how to use the \PHP namespace for userland-accessible classes and similar?"+Voting opened 2020-07-26 and closes 2020-08-09. 
 + 
 +Yes / No vote, requiring 2/3 to pass. 
 + 
 +"Should PHP adopt these guidelines for future RFC authors to guide when and how to use the \PHP and \Ext namespaces for userland-accessible classes and similar?" 
 + 
 + 
 +<doodle title="Adopt this policy for future symbols defined by php-src and extension code?" auth="crell" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle>
  
 ===== Prior Art ==== ===== Prior Art ====
 https://wiki.php.net/rfc/namespaces-in-core (withdrawn) https://wiki.php.net/rfc/namespaces-in-core (withdrawn)
  
rfc/php_namespace_policy.1592958289.txt.gz · Last modified: 2020/06/24 00:24 by crell

Page Tools