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
rfc:stringable [2020/01/22 15:29]
nicolasgrekas
rfc:stringable [2020/08/01 23:38] (current)
carusogabriel RFC was implemented
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: Implemented
   * 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.1579706991.txt.gz · Last modified: 2020/01/22 15:29 by nicolasgrekas