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/06/01 22:51] – 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 11: Line 13:
 This RFC discusses a few amendments to the [[https://wiki.php.net/rfc/attributes_v2|original Attributes RFC]] that was accepted for PHP 8. This RFC discusses a few amendments to the [[https://wiki.php.net/rfc/attributes_v2|original Attributes RFC]] that was accepted for PHP 8.
  
-===== Rename PhpAttribute class to Attributes\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> <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>
Line 21: Line 23:
  
 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. But the set of all attributes is a logical unit of code and namespaces are a concept that helps grouping them. +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 be namespaced under //Attributes\Attribute// and in addition +Therefore we propose to rename //PhpAttribute// to be just //Attribute// and in addition 
-recommend that all internal/compiler attributes should be placed under that namespace.+recommend that all internal/compiler attributes should be placed under the global namespace as well.
  
-Extensions providing non-core functionality should consider using their own namespace, but this RFC makes no recommendation or rule about this.+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 70: Line 72:
 </code> </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 127: 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 144: 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 163: 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 185: 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 207: 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 //Attributes\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.1591051875.txt.gz · Last modified: 2020/06/01 22:51 by beberlei

Page Tools