rfc:php_namespace_policy

This is an old revision of the document!


PHP RFC: PHP Namespace Policy

Proposal

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 class, however, creates a potential namespace collision with existing user-space code and thus a potential for backward compatibility breaks.

This RFC proposes to:

  • 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.
  • 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.
  • Propose guidelines for how existing PHP-SRC-provided classes MAY be migrated to namespaces in the future by other RFCs.

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

  1. 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.
  2. 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\.
  3. 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.
  4. 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.
  5. Component or sub-component namespaces MUST use CamelCase naming conventions.
  6. 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.
  7. 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.
  8. 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.

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 provide useful general functionality but do not impact engine behavior

  • Examples: SPL's collection classes, SPL's file classes, DOM, DateTime et al
  • 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.)

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

  • 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, 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)

PHP 8.0

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?”

Prior Art

rfc/php_namespace_policy.1593040040.txt.gz · Last modified: 2020/06/24 23:07 by crell