rfc:php_namespace_policy
Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
rfc:php_namespace_policy [2020/06/23 16:39] marandall |
rfc:php_namespace_policy [2020/07/26 16:02] crell |
||
---|---|---|---|
Line 2: | Line 2: | ||
* Version: 1 | * Version: 1 | ||
* Date: 2020-04-15 | * Date: 2020-04-15 | ||
- | * Author: Mark Randall, marandall@php.net | + | * Author: Mark Randall |
* Status: Under Discussion | * Status: Under Discussion | ||
* First Published at: https:// | * First Published at: https:// | ||
===== 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 | + | PHP-SRC provides an ever-increasing number of userland-accessible classes. |
- | ===== Namespace Claims ===== | + | This RFC proposes to: |
- | Upon a successful RFC claiming a namespace, that namespace would be exclusively reserved | + | * 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' |
- | Realistically this would be no different than the current mechanism of submitting a technical RFC that had class names included | + | * Formally reserve |
- | Requests to add additional namespaces for purposes such as aliasing existing | + | * Establish heuristics regarding when and how namespaced |
+ | * 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 | + | This RFC does NOT propose moving any existing code into the \PHP namespace |
- | 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 depth, although common sense should be used. | + | * **Vendor namespace**: |
- | Root: | + | * **Component namespace**: The second level namespace in a symbol name. For example, in \Foo\Bar\Baz, " |
- | * \PHP (must be empty except for other namespaces) | + | |
- | * \PHP\Engine (reserved for things effecting | + | |
+ | * **Class**: For the purpose of this document, " | ||
- | ===== Guidelines for Usage ===== | + | ===== Namespace Policy |
- | Classes | + | - The \PHP vendor namespace is reserved for use by classes provided by PHP-SRC itself. |
- | | + | |
- | | + | |
- | | + | |
- | | + | |
- | | + | |
+ | | ||
- | Classes that extend engine-level behaviours or provide special-casing: | + | ===== Namespace index ===== |
- | * Specialised Iterators | + | |
- | * Attributes Depreciated / JIT etc | + | |
- | * High-Performance Tokenization | + | |
- | Classes providing core functionality that would not be considered specific to an extension: **NAMESPACE** | + | A page will be established on the PHP Wiki (this site) to index all explicitly specified component namespaces for both \PHP and \Ext. |
- | * SPL (and its successor) | + | |
- | * Collections / Future Generics Implementations of Collections | + | |
- | ===== Mandatory Implementation Details ===== | + | 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. |
- | This RFC proposes that the contents of the \PHP namespace | + | A \PHP component |
- | Constants MUST be declared as class constants (or enums) as is currently demonstrated | + | An \Ext component namespace is " |
+ | |||
+ | - An RFC that creates | ||
+ | - A PECL module author may post to the Internals maliing list stating an intent to " | ||
+ | - PECL module may automatically claim a namespace based on its package name. For example, a " | ||
+ | - 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**: | ||
+ | * **Guideline**: | ||
+ | |||
+ | Classes or interfaces that extend a type the previous group | ||
+ | * **Examples**: | ||
+ | * **Guideline**: | ||
+ | |||
+ | Classes that are part of an extension, disableable or not. | ||
+ | * **Examples**: | ||
+ | * **Guideline**: | ||
+ | |||
+ | Cases where it is expected that the number of closely related classes is or is likely to become large | ||
+ | * **Examples**: | ||
+ | * **Guideline**: | ||
+ | |||
+ | 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. | ||
+ | |||
+ | 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. | ||
===== Proposed PHP Version(s) ===== | ===== Proposed PHP Version(s) ===== | ||
- | PHP 8.0 | + | PHP 8.0 (doesn' |
===== Vote ===== | ===== Vote ===== | ||
- | Yes / No | ||
- | " | + | Voting opened 2020-07-26 and closes 2020-08-09. |
+ | |||
+ | Yes / No vote, requiring 2/3 to pass. | ||
+ | |||
+ | " | ||
+ | |||
+ | |||
+ | <doodle title=" | ||
+ | * Yes | ||
+ | * No | ||
+ | </ | ||
===== Prior Art ==== | ===== Prior Art ==== | ||
https:// | https:// | ||
rfc/php_namespace_policy.txt · Last modified: 2020/08/10 13:41 by crell