rfc:php_namespace_policy

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
rfc:php_namespace_policy [2020/05/22 20:48]
marandall
rfc:php_namespace_policy [2020/08/10 13:41] (current)
crell
Line 2: Line 2:
   * Version: 1   * Version: 1
   * Date: 2020-04-15 ​   * Date: 2020-04-15 ​
-  * Author: Mark Randallmarandall@php.net +  * 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
  
 ===== Proposal ===== ===== Proposal =====
-In light of the ever-increasing number of userland-accessible classes being provided by the PHP-SRC, and the ever-increasing amount of symbols within the root namespace, this RFC proposes that internals withdraws its policy of placing everything within the root namespace, and instead adopts the policy of taking ownership of the \php namespace and everything beneath it, for the purposes of offering a way for current and future RFC authors to properly namespace any new classes which they add. 
  
-By design this RFC does NOT propose moving anything existing into the \PHP namespace at this time, nor does it REQUIRE ​future ​development uses itonly that the policy is set that it is the preferred mechanism ​for future development where suitable to do so+PHP-SRC provides an ever-increasing number of userland-accessible classes. ​ The recent addition of Attributes is very likely to result in even more in the future.  Every new global classhowever, creates a potential namespace collision with existing user-space code and thus a potential ​for backward compatibility breaks.
  
-===== Namespace Claims =====+This RFC proposes to:
  
-This RFC would establish ​the protocol ​for a registryupon which internals and core extension authors can, as part of their RFC, petition voters for a child namespace with which to place their additionssubject to the vote being passed. Laying claim to a child namespace of \PHP would be part of the main feature vote+  * Formally reserve ​the \PHP namespace ​for use by PHP-SRC. ​ It has been quasi-soft-reserved since namespaces were addedbut never used because we couldn'​t agree on when or how to do so.  Solet's do so.
  
-Realistically this would be no different than the current mechanism of submitting a technical RFC that had class names included ​in it.+  * Formally reserve ​the \Ext namespace for use by extensions, either PECL or in core.
  
-Requests to add additional namespaces for purposes such as aliasing existing ​classes ​as a means of migration, would be performed ​by a standard 2/3rds vote, multiple such classes may be included ​in a single vote if the community feels it appropriate+  * 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 ​common heuristic we hope to eliminate ​//most// purely subjective debate ​in the future.
  
-Once approved, a namespace that is a child of \PHP will remain exclusively for the originally assigned purpose, even if the associated code is moved out of core, unless a 2/3rds vote is held to withdraw that namespace, at which point it could be re-used, but this seems extremely unlikely ​to be used.+  * Propose guidelines for how existing ​PHP-SRC-provided classes MAY be migrated ​to namespaces in the future by other RFCs.
  
-===== Namespace Structure ===== 
  
-The top-level ​\PHP namespace ​itself would be exclusively used as a container for other namespacesand itself would not contain any classes.+This RFC does NOT propose moving any existing code into the \PHP namespace ​at this time.  That may be done by future RFCs if desiredunder their own votes. ​ This is a "​policy document"​ only.
  
-The \PHP\Engine namespace would be reserved for namespaces and classes which directly interface with the operation of the engine, e.g. future annotations relating to the operation of JIT.+===== Definitions =====
  
-There should be no restriction upon depthalthough common sense should be used+  * **Vendor namespace**:​ The top-level namespace in a symbol name.  For examplein \Foo\Bar\Baz,​ "​Foo"​ is the vendor.
  
-Root: +  * **Component namespace**The second level namespace in a symbol name.  For example, in \Foo\Bar\Baz, "​Bar"​ is the component namespace.
-  \PHP (must be empty except for other namespaces) +
-  * \PHP\Engine (reserved for things effecting ​the engine itself such as annotations or ErrorLevel::​WARNING) ​+
  
 +  * **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.
  
-===== Mandatory Implementation Details ​=====+===== Namespace Policy ​=====
  
-This RFC proposes ​that the contents ​of the \PHP namespace ​**are exclusively class-like (class, ​interface, trait) ​or namespaces** and that constantsstandalone functions ​and any other data is strictly prohibited. This would be because support for function type autoloading seems unlikely ​to emerge and using classes provides better opportunity for autoloaded polyfills+  - 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. 
 +  - 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. 
 +  ​Any namespaced code provided by PHP-SRC will use a distinct component namespace. ​ That is, no PHP\Foo ​class may be definedbut 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. 
 +  - 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.
  
-Constants MUST be declared as class constants ​(or enumsas is currently demonstrated ​by ZipArchiveFunctions MUST be declared ​as static member functions.  ​+===== Namespace index ===== 
 + 
 +A page will be established on the PHP Wiki (this siteto 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 itOnce 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 ===== 
 + 
 +The following heuristics are intended to guide the review of future RFCs by providing a consistent pattern for naming. ​ They are by nature not hard and precise rules, but future RFCs SHOULD follow them as closely as possible. 
 + 
 +Examples of existing classes or components listed below are for explanatory and demonstration purposes only.  ​This RFC does not propose to rename them here.  Future RFCs may do so if desired, following the process outlined below. 
 + 
 +Classes or interfaces that impact the type system in ways that affect runtime behavior 
 +  * **Examples**:​ Traversable,​ Iterable, Countable, ArrayAccess,​ WeakReference,​ Attribute 
 +  * **Guideline**:​ These interfaces should remain global 
 + 
 +Classes or interfaces that extend a type the previous group 
 +  * **Examples**:​ The various *Iterator classes, specific Attribute instances 
 +  * **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 are part of an extension, disableable or not. 
 +  * **Examples**:​ SimpleXMLElement,​ SoapClient, Sodium, DOM, SPL 
 +  * **Guideline**:​ An extension namespace specific to the use case.  Eg, \Ext\Sodium. 
 + 
 +Cases where it is expected that the number of closely related classes is or is likely to become large 
 +  * **Examples**:​ DOM, Attributes, core Exceptions 
 +  * **Guideline**:​ A namespace specific to the use case. 
 + 
 +Cases not covered above: 
 +  * Global, unless a good argument is made to the contrary. 
 + 
 +===== 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 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. 
 +2. Include an alias, subclass, or other backward compatibility shim to ensure existing userland code remains working without change. 
 + 
 +Removal of the older, un-namespaced symbols must happen in a separate RFC, and MUST happen no earlier than one full release cycle after that introduction of the namespaced symbol. ​ That is, a rename introduced in PHP 8.2 is not eligible to have its old name removed until at least 10.0.
  
 ===== 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 RFC authors ​be permitted ​to utilise a sub-namespace of \PHP to contain their features' ​userland accessible classes, traits, interfaces etc" ​+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.1590180483.txt.gz · Last modified: 2020/05/22 20:48 by marandall