This is an old revision of the document!

PHP RFC: PHP Namespace Policy


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 it, only that the policy is set that it is the preferred mechanism for future development where suitable to do so.

Namespace Claims

Upon a successful RFC claiming a namespace, that namespace would be exclusively reserved for that RFC (and its future development or iterations). If for some reason a feature was removed or moved to something like PECL, a 2/3rds vote could withdraw the namespace and make it available for re-use, although this would seem to be extremely unlikely.

Realistically this would be no different than the current mechanism of submitting a technical RFC that had class names included in it.

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.

Namespace Structure

The top-level \PHP namespace itself would be exclusively used as a container for other namespaces, and itself would not contain any classes.

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.

There should be no restriction upon depth, although common sense should be used.


  • \PHP (must be empty except for other namespaces)
  • \PHP\Engine (reserved for things effecting the engine itself such as annotations or ErrorLevel::WARNING)

Guidelines for Usage

Classes that provide engine-level behaviour, such as base types: GLOBAL

  • Traversable / Iterable
  • Countable
  • ArrayAccess
  • Attribute
  • WeakReference

Classes that extend engine-level behaviours or provide special-casing: NAMESPACE

  • FilterIterator
  • Attributes Depreciated / JIT etc
  • High-Performance Tokenization

Classes providing core functionality that would not be considered specific to an extension: NAMESPACE

  • SPL (and its successor)
  • Collections / Future Generics Implementations of Collections

Mandatory Implementation Details

This RFC proposes that the contents of the \PHP namespace are exclusively class-like (class, interface, trait) or namespaces and that constants, standalone 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.

Constants MUST be declared as class constants (or enums) as is currently demonstrated by ZipArchive. Functions MUST be declared as static member functions.

Proposed PHP Version(s)

PHP 8.0


Yes / No

“Should RFC authors be permitted to utilise a sub-namespace of \PHP to contain their features' userland accessible classes, traits, interfaces etc”

Prior Art

rfc/php_namespace_policy.1592930125.txt.gz · Last modified: 2020/06/23 16:35 by marandall