rfc:stringable

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:stringable [2020/01/22 15:29]
nicolasgrekas
rfc:stringable [2020/05/12 13:38]
nicolasgrekas
Line 2: Line 2:
   * Version: 0.9   * Version: 0.9
   * Date: 2020-01-15   * Date: 2020-01-15
-  * Author: Nicolas Grekas, nicolas.grekas+php@gmail.com +  * Author: Nicolas Grekas, nicolasgrekas@php.net 
-  * Status: Under Discussion+  * Status: Accepted
   * First Published at: http://wiki.php.net/rfc/stringable   * First Published at: http://wiki.php.net/rfc/stringable
  
 ===== Introduction ===== ===== Introduction =====
  
-This RFC introduces a new ''Stringable'' interface that can be added to classes that implement the ''%%__toString()%%'' method.+This RFC introduces a new ''Stringable'' interface that is automatically added to classes that implement the ''%%__toString()%%'' method.
  
 It has two goals: It has two goals:
-  - allow using ''string|Stringable'' to express ''string | object-with-%%__toString()%%''+  - allow using ''string|Stringable'' to express ''string|object-with-%%__toString()%%''
   - provide a forward upgrade path from PHP 7 to 8   - provide a forward upgrade path from PHP 7 to 8
  
 ===== Proposal ===== ===== Proposal =====
-Goal 1. is to allow using the ''string|Stringable'' union type in PHP 8, to accept both strings and objects that implement ''%%__toString()%%'' //and// declare this interface. This is critically missing currently, on codes that deal with stringable objects: they can't be made type-safe.+Goal 1. is to allow using the ''string|Stringable'' union type in PHP 8, to accept both strings and objects that implement ''%%__toString()%%''. This is critically missing currently, on codes that deal with stringable objects: they can't be made type-safe.
  
-Classes that implement ''%%__toString()%%'' aren'required to declare the interface as that would prevent seamless forward/backward compatibility with PHP 7.+Classes that implement ''%%__toString()%%'' can also declare the interface explicitly. Classes that don't declare the interface explicitly will still declare it implicitly. This allows both forward compatibility and backward compatibility: using a polyfill, classes can declare the interface on PHP 7; and on PHP 8, classes that don't do so will still be compatible with the ''string|Stringable'' union type.
  
-By being simple and without any magic capabilities on its own, this interface is trivially polyfilled on PHP < 8. +Once a polyfill becomes widely available (e.g. [[https://github.com/symfony/polyfill/pull/224|as part of symfony/polyfill-php80]]), code style checkers could be able to enforce declaring the interface when ''%%__toString()%%'' is declared explicitlyfor people that prefer doing so.
- +
-Once a polyfill becomes widely available (e.g. as part of symfony/polyfill-php80), we can expect code style checkers to be able to enforce declaring the interface when ''%%__toString()%%'' is used. For projects that don't use cs checkersthey'll notice quickly that they missed adding the interface when their users will ask for it if they do.+
  
 Here is the stub declaration of the interface: Here is the stub declaration of the interface:
Line 40: Line 38:
 Providing an easy forward-path is the second goal of this RFC. Providing an easy forward-path is the second goal of this RFC.
  
-For reference, [[https://github.com/symfony/symfony/search?q=%22%40param+string%7Cobject%22+stringable&unscoped_q=%22%40param+string%7Cobject%22+stringable|here are some annotations in Symfony]], added by contributions from real-world use cases and that currently cannot be expressed precisely enough using any union types in PHP 8.+For reference, [[https://github.com/symfony/symfony/search?q=%22%40param+string%7Cstringable%22|here are some annotations in Symfony]], added by contributions from real-world use cases and that currently cannot be expressed precisely enough using any union types in PHP 8.
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
Line 50: Line 48:
 ===== RFC Impact ===== ===== RFC Impact =====
 ==== To Existing Extensions ==== ==== To Existing Extensions ====
-Extensions will need to add the ''string'' return type when they declare ''%%__toString()%%'' methods.+Extensions will need to declare both the interface and the ''string'' return type when they declare ''%%__toString()%%'' methods if they want to pass the ''string|Stringable'' union type.
  
 ===== Open Issues ===== ===== Open Issues =====
Line 62: Line 60:
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
-Accept the proposed interface for PHP 8.0: yes/no+yes/no 
 + 
 +===== Vote ===== 
 +<doodle title="Adopt the Stringable interface as proposed in this RFC?" auth="nicolasgrekas" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle>
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
rfc/stringable.txt · Last modified: 2020/08/01 23:38 by carusogabriel