rfc:shorter_attribute_syntax

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
rfc:shorter_attribute_syntax [2020/06/16 15:25]
theodorejb Add community poll info and move alternate syntax proposal before discussion section
rfc:shorter_attribute_syntax [2020/08/12 15:56]
theodorejb Update nested syntax for #[] - I think this was a relic of the idea to strip all leading hashes
Line 2: Line 2:
   * Date: 2020-06-03   * Date: 2020-06-03
   * Author: Theodore Brown <theodorejb@outlook.com>, Martin Schröder   * Author: Theodore Brown <theodorejb@outlook.com>, Martin Schröder
-  * Status: Under Discussion+  * Status: Implemented
   * Discussion: https://externals.io/message/110355   * Discussion: https://externals.io/message/110355
   * Target Version: PHP 8.0   * Target Version: PHP 8.0
-  * Implementation for ''@@''Based on https://github.com/kooldev/php-src/pull/2 (requires a single character to be changed in the lexer and a small grammar adjustment) +  * Implementation: https://github.com/php/php-src/pull/5796
-  * Implementation for ''#[]'': https://github.com/koolkode/php-src/pull/5+
  
 ===== Introduction ===== ===== Introduction =====
Line 165: Line 164:
 ===== Alternative #[] syntax ===== ===== Alternative #[] syntax =====
  
-An alternative to using ''@@Attr'' would be to borrow the ''#[attr]'' syntax from Rust. This would have the benefit of reusing the same syntax as another language, and it is also potentially forwards compatible for single-line attributes. E.g. the following code works with both PHP 7 and PHP 8 (the attribute is treated as a comment on PHP 7):+An alternative to using ''@@Attr'' would be to borrow the ''#[attr]'' syntax from Rust. This would have the benefit of reusing the same syntax as another language, and it is also potentially forwards compatible for single-line attributes. E.g. the following code could work with both PHP 7 and PHP 8 (the attribute is treated as a comment on PHP 7):
  
 <code php> <code php>
Line 174: Line 173:
 So with this syntax, in theory it would be possible for a library to support both native PHP 8 attributes and PHP 7 docblock annotations with the same code. E.g. PHPUnit could introduce a ''Covers'' attribute class which would also work in PHP 7 to encapsulate information from an ''@covers'' docblock annotation. So with this syntax, in theory it would be possible for a library to support both native PHP 8 attributes and PHP 7 docblock annotations with the same code. E.g. PHPUnit could introduce a ''Covers'' attribute class which would also work in PHP 7 to encapsulate information from an ''@covers'' docblock annotation.
  
-However, this benefit would be lost as soon as a library wants to depend on any other PHP 8 features, and it will become irrelevant anyway once most users upgrade to PHP 8. Even with the ''@@'' syntax, libraries can support both native attributes and docblock annotations, they just would need to use a different class (or a parent class) to encapsulate the docblock arguments on PHP 7.x.+However, this benefit would be lost as soon as a library wants to depend on any other PHP 8 features, and it will become irrelevant anyway once most users upgrade to PHP 8. With the ''@@'' syntax, libraries can still support both native attributes and docblock annotations, they just would need to use a different class (or a parent class) to encapsulate the docblock arguments on PHP 7.x.
  
 ==== Downsides ==== ==== Downsides ====
  
-  * Larger BC break than ''@@''. While duplicate error suppression operators aren't useful, there is a use for comments starting with a left bracket (e.g. for making checkboxes, or to comment out an array).+  * Larger BC break than ''@@'' (see Backward Incompatible Changes section below).
   * Slightly more verbose than ''@@'', which works against one of the goals of this RFC.   * Slightly more verbose than ''@@'', which works against one of the goals of this RFC.
   * Arguably more difficult to type than ''@@'' on common qwerty keyboard layouts.   * Arguably more difficult to type than ''@@'' on common qwerty keyboard layouts.
Line 199: Line 198:
     #[JoinTable(     #[JoinTable(
         "User_Group",         "User_Group",
-        #JoinColumn("User_id", "id"), +        #[JoinColumn("User_id", "id")]
-        #JoinColumn("Group_id", "id"),+        #[JoinColumn("Group_id", "id")],
     )]     )]
     private $groups;     private $groups;
Line 263: Line 262:
 ==== Isn't the syntax choice just something subjective we'll get used to? ==== ==== Isn't the syntax choice just something subjective we'll get used to? ====
  
-To some extent this may be true. However, in this case we believe there are also objective reasons to prefer the shorter syntax, which this RFC attempts to outline.+To some extent this may be true. However, in this case we believe there are also objective shortcomings with using ''%%<<>>%%'' for attributes, which we have the opportunity to solve with a shorter syntax.
  
  
Line 279: Line 278:
   * Swift: ''@attr'' [[https://docs.swift.org/swift-book/ReferenceManual/Attributes.html|9]]   * Swift: ''@attr'' [[https://docs.swift.org/swift-book/ReferenceManual/Attributes.html|9]]
   * TypeScript/JS: ''@Attr'' [[https://www.typescriptlang.org/docs/handbook/decorators.html|10]]   * TypeScript/JS: ''@Attr'' [[https://www.typescriptlang.org/docs/handbook/decorators.html|10]]
- 
- 
-===== Community Poll ===== 
- 
-On June 10 there was a poll on Reddit to see which syntax the community prefers. [[https://www.reddit.com/r/PHP/comments/h06bra/community_poll_attribute_syntax/|11]] 
- 
-''@@'' was by far the most popular, with 436 votes. ''%%<<>>%%'' was second most popular, with 240 votes. ''#[]'' came in third place, with 159 votes. 
  
  
Line 299: Line 291:
 </code> </code>
  
-There is definitely code in the wild using hash comments starting with a left bracket that would break. [[https://grep.app/search?q=%23%5B&filter[lang][0]=PHP|12]]+While duplicate error suppression operators aren't useful, there is a use for comments starting with a left bracket (e.g. making checkboxes or commenting out an array). There is definitely code in the wild like this that would break. [[https://grep.app/search?q=%23%5B&filter[lang][0]=PHP|11]]
  
  
Line 307: Line 299:
  
 Finally, this proposal does not conflict with the [[https://wiki.php.net/rfc/attribute_amendments|Attribute Amendments]] RFC, with the exception that if the ''@@'' syntax is accepted, it will supersede the syntax for grouped attributes. Finally, this proposal does not conflict with the [[https://wiki.php.net/rfc/attribute_amendments|Attribute Amendments]] RFC, with the exception that if the ''@@'' syntax is accepted, it will supersede the syntax for grouped attributes.
 +
 +
 +===== Community Poll =====
 +
 +On June 10-13 there was a poll on Reddit to see which syntax the community prefers. [[https://www.reddit.com/r/PHP/comments/h06bra/community_poll_attribute_syntax/|12]]
 +
 +''@@'' was the most popular, with 436 votes. ''%%<<>>%%'' came in second place, with 240 votes. ''#[]'' came in third place, with 159 votes.
  
  
 ===== Vote ===== ===== Vote =====
  
-Are you okay with re-voting on the attribute syntax for PHP 8.0, including the already accepted ''%%<<>>%%'' option? Yes/No+Voting started on 2020-06-17 and ended on 2020-07-01. 
 + 
 +==== Primary vote ==== 
 + 
 +<doodle title="Are you okay with re-voting on the attribute syntax for PHP 8.0?" auth="theodorejb" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle> 
 + 
 +==== Secondary vote ==== 
 + 
 +This is a ranked-choice poll (following [[https://en.wikipedia.org/wiki/Single_transferable_vote#Example|STV]]) between the ''@@'', ''#[]'', and ''%%<<>>%%'' syntax alternatives. You can vote **three** times, but make sure you select each syntax only once. 
 + 
 +=== First choice === 
 + 
 +<doodle title="Attribute syntax choice #1" auth="theodorejb" voteType="single" closed="true"> 
 +   * @@ 
 +   * #[] 
 +   * <<>> 
 +</doodle> 
 + 
 +=== Second choice === 
 + 
 +<doodle title="Attribute syntax choice #2" auth="theodorejb" voteType="single" closed="true"> 
 +   * @@ 
 +   * #[] 
 +   * <<>> 
 +</doodle> 
 + 
 +=== Third choice === 
 + 
 +<doodle title="Attribute syntax choice #3" auth="theodorejb" voteType="single" closed="true"> 
 +   * @@ 
 +   * #[] 
 +   * <<>> 
 +</doodle>
  
-Secondary vote: ranked-choice vote between ''@@'', ''#[]'', and ''%%<<>>%%'' syntax alternatives. 
  
 ===== References ===== ===== References =====
Line 319: Line 352:
   * Previous discussion about nested attributes: https://externals.io/message/108907#109623 and https://externals.io/message/108907#109688   * Previous discussion about nested attributes: https://externals.io/message/108907#109623 and https://externals.io/message/108907#109688
   * Previous comments in favor of ''@@'': https://externals.io/message/109713#109742   * Previous comments in favor of ''@@'': https://externals.io/message/109713#109742
 +
  
 ===== Changelog ===== ===== Changelog =====
  
   * 2020-06-09 - Added ''#[Attr]'' syntax alternative with ranked-choice vote.   * 2020-06-09 - Added ''#[Attr]'' syntax alternative with ranked-choice vote.
-  * 2020-06-16 - Added community poll and moved alternative syntax proposal before discussion section.+  * 2020-06-16 - Summarized community poll and moved alternative syntax proposal before discussion section.
rfc/shorter_attribute_syntax.txt · Last modified: 2020/08/12 15:56 by theodorejb