rfc:attribute_amendments

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
rfc:attribute_amendments [2020/05/20 17:15] – beberleirfc:attribute_amendments [2020/06/29 09:07] (current) – Update patch URL beberlei
Line 1: Line 1:
 ====== PHP RFC: Attribute Amendments ====== ====== PHP RFC: Attribute Amendments ======
  
-  * Version: 1.0+  * Version: 1.2
   * Date: 2020-05-11   * Date: 2020-05-11
   * Author: Benjamin Eberlei (beberlei@php.net), Martin Schröder   * Author: Benjamin Eberlei (beberlei@php.net), Martin Schröder
-  * Status: Under Discussion+  * Status: Implemented 
 +  * Target: 8.0
   * First Published at: http://wiki.php.net/rfc/attribute_amendments   * First Published at: http://wiki.php.net/rfc/attribute_amendments
 +  * Patch: https://github.com/php/php-src/pull/5751
  
 ===== Introduction ===== ===== Introduction =====
Line 12: Line 14:
  
 ===== Rename PhpAttribute class to Attribute ===== ===== Rename PhpAttribute class to Attribute =====
 +
 +<nowiki>Important Context: Since the acceptence of Attributes, the PhpCompilerAttribute and PhpAttribute classes were unified to be only PhpAttribute. This was needed because the previous approach of disallowing the use of <<PhpCompilerAttribute>> in userland would break "stub" generation that static analysis and IDEs rely on to fill their type database of internal functions/classes. Without it there was no functionality left in PhpCompilerAttribute to preserve.</nowiki>
  
 The original RFC introduced a //PhpAttribute// class to be added to new The original RFC introduced a //PhpAttribute// class to be added to new
 userland attributes. This name was inspired by //PhpToken// and to potentially userland attributes. This name was inspired by //PhpToken// and to potentially
 avoid breaking existing userland codebases with a class called //Attribute//. avoid breaking existing userland codebases with a class called //Attribute//.
-However the //Php// prefix in this case makes little sense for the attribute class.+However the //Php// prefix makes no sense for the attribute class compared to //PhpToken//.
  
 In absence of a namespace policy, the global namespace is PHPs namespace. The In absence of a namespace policy, the global namespace is PHPs namespace. The
-documentation states as much. +documentation states as much and the vote on https://wiki.php.net/rfc/php-namespace-in-core confirmed this.
- +
-We propose to rename //PhpAttribute// to //Attribute//.+
  
-This will cause problems with applications using //Attribute// class in their code. This is a little more critical than for example the new PHP 8 function //str_contains//, which most likely was implemented the same way as the new function, whereas an userland //Attribute// class could do anything. No commonly used PHP libraries are using an unnamespaced Attribute class, but there was at least one mention of an open source application in the previous discussion, and I expect closed source code to have this problem as well.+Therefore we propose to rename //PhpAttribute// to be just //Attribute// and in addition 
 +recommend that all internal/compiler attributes should be placed under the global namespace as well.
  
-Should [[https://wiki.php.net/rfc/php-namespace-in-core|PHP Namespace]] in core get accepted before 8.0, then the class will be moved to //PHP\Attribute//.+Extensions providing non-core attributes should consider using their own namespace, but this RFC makes no recommendation or rule about this.
  
 ===== Group statement for Attributes ===== ===== Group statement for Attributes =====
Line 56: Line 59:
 } }
 </code> </code>
 +
 +In line with many other recent RFCs, trailing commas will also be possible in an attribute group declarations:
 +
 +<code php>
 +    <<
 +      Attr1("foo"),
 +      Attr2("bar"),
 +    >>
 +    public function test()
 +    {
 +    }
 +</code>
 +
 +This feature would be superseded by any other RFC getting accepted that changes the syntax.
  
 ===== Validate Attribute Target Declarations ===== ===== Validate Attribute Target Declarations =====
Line 113: Line 130:
     public const int TARGET_ALL = ((1 << 6) - 1);     public const int TARGET_ALL = ((1 << 6) - 1);
  
-    public function __construct(int $target = self::TARGET_ALL)+    public function __construct(int $flags = self::TARGET_ALL)
     {     {
     }     }
Line 130: Line 147:
  
 For this reason we propose that by default attributes are not repeatable, and only For this reason we propose that by default attributes are not repeatable, and only
-if the attribute has the //RepeatableAttribute// attribute in addition to //PhpAttribute//+if the //PhpAttribute// has the flag //IS_REPEATABLE//
 should it be possible to use it multiple times on the same declaration: should it be possible to use it multiple times on the same declaration:
  
 <code php> <code php>
-<<PhpAttribute, RepeatableAttribute>>+class PhpAttribute 
 +{ 
 +    public const int IS_REPEATABLE = ((1 << 10)); 
 +} 
 + 
 +<<PhpAttribute(self::IS_REPEATABLE)>>
 class Route class Route
 { {
Line 149: Line 171:
 </code> </code>
  
-An alternative approach would be to introduce a second argument to //PhpAttribute// for flags: +Important note: The repeatable flag of an attribute is validated during the call to //ReflectionAttribute::newInstance//.
- +
-<code php> +
-<<PhpAttribute(PhpAttribute::TARGET_ALL, PhpAttribute::IS_REPEATABLE)>> +
-class Route +
-{ +
-} +
- +
-// with named parameters: +
-<<PhpAttribute(flags: PhpAttribute::IS_REPEATABLE)>> +
-class Route +
-{ +
-} +
-</code> +
- +
-Important note: The repeatable definition of an attribute is validated during the call to //ReflectionAttribute::newInstance//.+
 In fact it does not influence a call to //Reflection*::getAttributes()// and //ReflectionAttribute// instances can be returned In fact it does not influence a call to //Reflection*::getAttributes()// and //ReflectionAttribute// instances can be returned
 from this method, that are not valid on the reflected declaration. This is in line with the deferred validation of userland attributes from this method, that are not valid on the reflected declaration. This is in line with the deferred validation of userland attributes
Line 171: Line 178:
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
  
-No breaks.+Introducing a class //Attribute// into the global namespace is certainly going to break at least a handful of applications using this class name. 
  
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
Line 193: Line 200:
 ===== Open Issues ===== ===== Open Issues =====
  
-  - For repeated attribute declaration: Use a dedicated attribute class or flags on //PhpAttribute//?+none
  
 +===== Vote =====
  
-===== Proposed Voting Choices =====+Voting will end on June 22nd, 2020 - 8:00 UTC.
  
-  - Should //PhpAttribute// be renamed to //Attribute//? +==== Rename PhpAttribute class to Attribute ==== 
-  - Should a secondary grouped syntax for attributes be introduced? + 
-  - Should attributes allow definition of target declarations? +<doodle title="Should PhpAttribute be renamed to Attribute?" auth="beberlei" voteType="single" closed="true"> 
-  - Should attributes allow definition of repeatability?+   * Yes 
 +   * No 
 +</doodle> 
 + 
 +==== Group statement for Attributes ==== 
 + 
 +<doodle title="Should a secondary grouped syntax for attributes be introduced?" auth="beberlei" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle> 
 + 
 +==== Validate Attribute Target Declarations ==== 
 + 
 +<doodle title="Should attributes allow definition of target declarations?" auth="beberlei" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle> 
 + 
 +==== Validate Attribute Repeatability ==== 
 + 
 +<doodle title="Should attributes allow definition of repeatability?" auth="beberlei" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle>
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
  
-  - [[https://github.com/koolkode/php-src/pull/2|PR for Target and Repeatability Validations]] +  - https://github.com/php/php-src/pull/5751 
-  - [[https://github.com/koolkode/php-src/pull/1|PR for Grouped Attributes Syntax]]+
  
 ===== References ===== ===== References =====
  
   - [[https://wiki.php.net/rfc/attributes_v2|Attributes RFC]]   - [[https://wiki.php.net/rfc/attributes_v2|Attributes RFC]]
 +  
 +===== Updates =====
 +
 +  - 1.0 Initial RFC (11.5.2020)
 +  - 1.1 Attributes\Attribute namespace (28.5.2020)
 +  - 1.2 Revert Attributes\Attribute namespace, make IS_REPEATABLE flag on PhpAttribute (4.6.2020)
  
rfc/attribute_amendments.1589994951.txt.gz · Last modified: 2020/05/20 17:15 by beberlei

Page Tools