rfc:php-namespace-in-core

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
Last revision Both sides next revision
rfc:php-namespace-in-core [2020/03/25 18:42]
brzuchal
rfc:php-namespace-in-core [2020/05/22 06:10]
brzuchal open voting
Line 1: Line 1:
 ====== PHP RFC: PHP Namespace in core ====== ====== PHP RFC: PHP Namespace in core ======
-  * Version: ​0.9+  * Version: ​1.2.0
   * Date: 2020-03-25   * Date: 2020-03-25
-  * Author: Michał Brzuchalski <​brzuchal@php.net>​ +  * Author: Michał Brzuchalski <​brzuchal@php.net>,​ George Peter Banyard <girgias@php.net>​ 
-  * Status: ​Draft+  * Status: ​Voting
   * First Published at: http://​wiki.php.net/​rfc/​php-namespace-in-core   * First Published at: http://​wiki.php.net/​rfc/​php-namespace-in-core
  
 ===== Introduction ===== ===== Introduction =====
-Introduce ​PHP namespace to core symbols which cannot be unbundled ​and are strictly ​language/​parser/​interpreter ​related as a way to fix some mistakes, clean up global ​namespace ​and to avoid collisions with user-defined symbols.+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.
  
-Introduction ​of PHP namespace ​also as a way for gradual migration over renamed and marked as deprecated symbols reducing breaking changes.+This paves the way to reduce the usage of the global ​namespace as "​PHP"'​s namespace.
  
-There is no concrete proposal on how to structure the namespaces and the only agreement ​is that core classes which are tightly coupled ​with the core can start using `PHPnamespace for type prefixes.+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.
  
-===== Proposal ​===== +===== Features which could benefit from the PHP namespace ​=====
-This RFC proposes to introduce PHP namespace for internal symbols by utilizing the reserved PHP namespace as the root for the symbols that are tightly coupled with PHP interpreter.+
  
-==== New symbols tightly coupled to the core ==== +  * The recently accepted [[rfc:​token_as_object|PHP RFC: Object-based token_get_all() alternative]] uses the <​php>​\PhpToken</​php>​ class but under this proposal ​it could be <​php>​\PHP\PhpToken</​php>​ 
-We can either have `PhpToken` and `PhpAttribute` classes of which the second one is a future RFC proposal+  * The currently under discussion [[rfc:​attributes_v2|PHP RFC: Attributes v2]] could use the ''​\PHP''​ namespace for engine/​internal related attributes.
-But with the PHP namespace, those names can be clean like `PHP\Token` and `PHP\Attribute`.+
  
-That kind of symbols ​belongs only to the core. Therefore ​they will newer be unbundled and moved to PECL.+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.
  
-In hypothetically new RFC for small refactor like was done for [[https://​wiki.php.net/​rfc/​token_as_object|Object-based token_get_all() alternative]] +==== A small concrete example ==== 
-for eg. `debug_backtrace()` which currently ​produces an array of arrays ​and introduction of a sort of `Framewould be proposed for object-based alternative then `PHPnamespace ​is the natural owner of for eg. `PHP\Frame` without that we may cause some BC breaks ​in userland ​which is not likely to happen with `PHP` namespace ​prefix.+Currently <php>debug_backtrace()</​php> ​produces an array of arrays. An object oriented API could introduce the <php>Frame</​php>​ 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.
  
-==== Renaming to fix some mistakes ​==== +===== Proposal ===== 
-Currently we do have `ReflectionType` and `ReflectionNamedType` but their purpose isn't exactly ​to present a type. +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.
- +
-From type perspective,​ a class is a type. Therefore `ReflectionClass` not extending `ReflectionType` could be questionable. +
-Current `ReflectionType` functions as a type constraint in general therefore renaming it to `ReflectionTypeConstraint` could be a good way to resolve those issues and concerns. +
- +
-This RFC is not about renaming those classes but presents some mistakes taken in the past which cannot be changed between ​the PHP releases without a huge BC break. +
- +
-What this RFC opens is a way to make some cleanups and in this specific example opens a way to alias `ReflectionType` as a `PHP\ReflectionTypeConstraint` (technically in the opposite direction) so then `PHP\ReflectionType` can be used as a top reflector for all kind of types which can be introduced in a future, like enums generics etc. +
-Those kind of changes are not BC breaking changes allows to mark old classes as deprecated for a long period and use new class names in the meantime.+
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
-No incompatible changes+No backwards ​incompatible changes ​as only new classes/​symbols would be introduces under the ''​\PHP''​ namespace.
  
-===== Proposed PHP Version(s) ===== +===== Proposed PHP Version ===== 
-Next PHP 8.x.+PHP 8.0.
  
-===== RFC Impact ​===== +===== Concerns about inconsistent use ===== 
-==== To SAPIs ==== +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.
-None.+
  
-==== To Existing Extensions ==== +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.
-None.+
  
-==== To Opcache ​==== +===== Future scope ===== 
-None.+Providing new core APIs building on new features introduces in PHP, such as:
  
-==== New Constants ==== +  * I/O API using exceptions instead of warnings in case of failure 
-None.+  * 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 ===== ===== Proposed Voting Choices =====
-As this is a language change, ​a 2/3 majority ​is required.+The vote is a straight Yes/No vote requiring ​a 2/3 majority ​to accept the RFC.
  
-The vote is a straight ​Yes/No vote for accepting the RFC.+===== Vote ===== 
 +Voting started on 2020-05-22 and will end on 2020-06-04 at 6:00 UTC. 
 +<doodle title="​Accept PHP namespace in core RFC?" auth="​brzuchal"​ voteType="​single"​ closed="​false">​ 
 +   ​* ​Yes 
 +   ​* ​No 
 +</​doodle>​
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
 This RFC doesn'​t provide any changes. 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 <php> SplQueue extends SplDoublyLinkedList</​php>​ meaning <​php>​SplQueue</​php>​ inherits the <​php>​push()</​php>​ and <​php>​pop()</​php>​ methods from <​php>​SplDoublyLinkedList</​php>​.
 +
 +Therefore, if a user decides to use these methods instead of the designated <​php>​enqueue()</​php>​ and <​php>​dequeue()</​php>​ 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.
rfc/php-namespace-in-core.txt · Last modified: 2020/06/04 11:51 by brzuchal