PHP RFC: PHP Namespace in core
- Version: 1.2.0
- Date: 2020-03-25
- Author: Michał Brzuchalski brzuchal@php.net, George Peter Banyard girgias@php.net
- Status: Declined
- First Published at: http://wiki.php.net/rfc/php-namespace-in-core
Introduction
The PHP project has reserved the right to use the \PHP namespace but has never acted upon starting to use it. We therefore propose that core symbols which cannot be unbundled such as those related to the language/parser/interpreter must use \PHP namespace.
This paves the way to reduce the usage of the global namespace as “PHP”'s namespace.
This is not a concrete proposal on how to structure the namespace or a proposal on re-aliasing classes to use the \PHP namespace. This is only an agreement that core classes or newly introduced symbols which are tightly coupled to the PHP engine must start using the \PHP namespace, e.g. for type prefixes.
Features which could benefit from the PHP namespace
- The recently accepted PHP RFC: Object-based token_get_all() alternative uses the
\PhpTokenclass but under this proposal it could be\PHP\PhpToken - The currently under discussion PHP RFC: Attributes v2 could use the
\PHPnamespace for engine/internal related attributes.
As these sort of symbols are tied to the engine there is no risk that they will get unbundled from PHP core and moved to PECL. We note this as we are aware that if a non core extension would use the \PHP namespace and gets unbundled and moved to PECL we would find ourselves in a situation where symbols under the \PHP namespace are not always available in PHP.
A small concrete example
Currently debug_backtrace() produces an array of arrays. An object oriented API could introduce the Frame class to hold details about each frame in the backtrace. As this would be an internal API using the \PHP namespace signals clear ownership and possibly limit the BC breaks for users which don't use the namespace feature of PHP.
Proposal
New features or symbols which are tightly coupled to the internals/engine of the PHP interpreter must use the \PHP namespace starting from PHP 8.
Backward Incompatible Changes
No backwards incompatible changes as only new classes/symbols would be introduces under the \PHP namespace.
Proposed PHP Version
PHP 8.0.
Concerns about inconsistent use
Various symbols which are widely used are located in the global namespace, classes such as Closure or Generator and interfaces such as Countable, ArrayAccess, and many others.
Although some of these fall into the category of being tightly tied to the engine and would land in the \PHP namespace under this proposal if newly introduced. We consider the long term advantage of using the namespace and the benefits it can provide as a an acceptable trade-off.
Future scope
Providing new core APIs building on new features introduces in PHP, such as:
- I/O API using exceptions instead of warnings in case of failure
- New data structures to replace SPL data structures, see Appendix for reasons why
Or revamping current ones:
* Reflection, see Appendix for a use case
Proposed Voting Choices
The vote is a straight Yes/No vote requiring a 2/3 majority to accept the RFC.
Vote
Voting started on 2020-05-22 and will end on 2020-06-04 at 6:00 UTC.
Patches and Tests
This RFC doesn't provide any changes.
Changelog
1.0.0: Initial version
1.1.0: New features must use the PHP engine, before this was merely a suggestion
1.2.0: Major rewrite, addressing concerns about inconsistent usage
Appendix
SPL Data Structures
An infamous example is that SplQueue extends SplDoublyLinkedList meaning SplQueue inherits the push() and pop() methods from SplDoublyLinkedList.
Therefore, if a user decides to use these methods instead of the designated enqueue() and dequeue() methods the behaviour obtained is the one of a stack instead of a queue.
Reflection
Currently within the Reflection extension we have the following classes ReflectionType and ReflectionNamedType however their purpose isn't exactly to present a type.
From PHP's type system perspective, a class is a type. Therefore, ReflectionClass not extending from ReflectionType could be seen as questionable. Thus the ReflectionType class acts more as a type constraint and renaming it to ReflectionTypeConstraint may be a good way to clarify it's concern.
Thus, in a revamped Reflection extension one could imagine a more accurate PHP\ReflectionTypeConstraint to represent the current ReflectionType and introduce a new top reflector PHP\ReflectionType for all types current, and future. E.g Enums, Generics, etc.