PHP: rfc:never-parameters-v2

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: Never Parameters (v2) ======
  * Version: 0.2
  * Date: 2025-03-10
  * Author: Daniel Scherzer, daniel.e.scherzer@gmail.com
  * Status: In voting
  * First Published at: https://wiki.php.net/rfc/never-parameters-v2
  * Discussion: https://news-web.php.net/php.internals/126698

Currently, there is no way to specify a parameter with a [[https://en.wikipedia.org/wiki/Bottom_type|bottom type]], indicating that a function has a parameter but not providing any guarantees on the types of values it accepts. This RFC proposes allowing the <php>never</php> type to be used on methods in places where methods are just declared to exist, like interfaces and abstract class methods.

===== Introduction =====
For a use case, and the inspiration for this RFC, consider the case of the <php>BackedEnum</php> interface that was added in PHP 8.1. It is defined as:

<PHP>
interface BackedEnum extends UnitEnum {
  public string $value;
  
  public static function from(int|string $value): static;
  public static function tryFrom(int|string $value): ?static;
}
</PHP>

However, this interface is incorrect from a type perspective. Backed enums are backed by string or by integers, and in either scenario, //all// cases of the enum have values of that type. For enums that are string-backed, the <php>::from()</php> and <php>::tryFrom()</php> methods should be typed with string parameters; for enums that are int-backed, the methods should be typed with integer parameters.

But, since parameter types are contravariant, for enums to have the right signatures the base <php>BackedEnum</php> methods would need to have types that are more restrictive than either <php>string</php> or <php>int</php> - something like <php>string&int</php>, or, since that is impossible (and just a confusing way of saying "absolutely no values"), what is proposed in this RFC:

<PHP>
interface BackedEnum extends UnitEnum {
  public string $value;
  
  public static function from(never $value): static;
  public static function tryFrom(never $value): ?static;
}
</PHP>

That way, for enums that were backed by strings, the methods could be
<PHP>
  public static function from(string $value): static;
  public static function tryFrom(string $value): ?static;
</PHP>

While, for enums backed by ints, the methods could be
<PHP>
  public static function from(int $value): static;
  public static function tryFrom(int $value): ?static;
</PHP>

And, importantly, LSP is followed - since <php>never</php> is the bottom type, having a <php>string</php> or <php>int</php> parameter //widens// the acceptable types.

===== Proposal =====
<php>never</php> can be used as a parameter type, subject to the following restrictions
  * it cannot be used in the declaration of any method that has an implementation. Methods with <php>never</php> can **never** (pun intended) be called, because there are no values that satisfy the type constraint. Instead of delaying the error until runtime when the user attempts to call the method, just require that the method not have a body. In other words, this can be used in interfaces and in the declaration of abstract methods in both traits and abstract classes.
  * it cannot be used in non-class functions. This follows from the restriction above - because non-class functions always have an implementation, they cannot use <php>never</php> parameters, or they would be unusable.
  * it cannot be used in the <php>set</php> property hook. Because property hook parameter types are contravariant with the type of the property itself, the property hook parameter cannot be declared with a narrower type than the property itself. At the moment, properties cannot be declared to have <php>never</php> types, so using this in a property hook would be impossible regardless, but it is worth pointing out.
  * it cannot be used for a parameter with a default. Because <php>never</php> does not accept any values, there is no possible default value that would be accepted by the current validation that the default value be legal, but it is worth pointing out.

Additionally, making use of this new feature, the definitions of the <php>BackedEnum::from()</php> and <php>BackedEnum::tryFrom()</php> methods are updated to use <php>never</php> parameters, and for any individual backed enum, the signature documents that the method accepts only string parameters (or only int parameters).

===== Differences from prior RFC =====
In developing this RFC the author discovered a prior RFC, [[rfc:never_for_parameter_types]], with a similar goal. Differences from that proposal include

  * <php>never</php> parameters can only be used when on methods (not free-standing functions)
  * <php>never</php> parameters can only be used when a method has no body associated with the declaration
  * <php>never</php> parameters cannot have default values
  * <php>BackedEnum</php> is updated as part of this proposal

===== Backward Incompatible Changes =====
Anything previously relying on the exact type information for <php>BackedEnum::from()</php> and <php>BackedEnum::tryFrom()</php>, or the corresponding inherited methods on any backed enum, may need to be updated to account for the fact that the information is correct now.

As with all RFCs that make code that previously had a compile-time error become valid, this RFC requires updates to static analyzers and IDEs to understand the semantics of never parameters.

===== Userland example =====

in the [[https://github.com/thephpleague/commonmark|thephpleague/commonmark]] package, different renderers are added to render different types (subclasses) of <php>\League\CommonMark\Node\Node</php>. You can see the interface for renderers [[https://github.com/thephpleague/commonmark/blob/2.6/src/Renderer/NodeRendererInterface.php|here]]. The overall interface supports being called with any Node type, but each underlying renderer expects to be called with a //narrower// type than that. To avoid LSP violations, the renderers

  * have a Node typehint
  * have a documentation comment with the actual subclass of Node that they support
  * manually throw an exception on invalid values

See, e.g., [[https://github.com/thephpleague/commonmark/blob/2.6/src/Renderer/Block/ParagraphRenderer.php|the default renderer for paragraphs]]. This seems like exactly the place where you would find it useful to have never parameters. The current implementation

  * uses comments and static analysis tools to document the restriction
  * manually throws an exception when violated

Whereas if the base class had a never parameter, it could

  * use language typehints to document the restriction
  * have the exception enforced automatically

To be clear, this is just one possible place where <php>never</php> parameters might be useful in userland classes; more were discussed on the mailing list thread.

===== Proposed PHP Version(s) =====
Next version of PHP (PHP 8.5 or PHP 9.0)

===== RFC Impact =====

==== To Reflection ====
Information about <php>BackedEnum::from()</php>, <php>BackedEnum::tryFrom()</php>, and the inherited versions thereof on individual backed enums will be updated.

Any code that relied on the assumption that parameters did not have <php>never</php> types will need to be updated to check the actual type.

===== Unaffected PHP Functionality =====
Since <php>never</php> was previously not allowed as a parameter, the behavior of existing legal code is unchanged.

Since PHP internal methods (in this case <php>BackedEnum::from()</php> and <php>BackedEnum::tryFrom()</php>) do their type checking manually in their implementations rather than having signatures enforced by the engine upon calling, the types of values allowed were already restricted based on the backing type of enums. Thus, the behavior of calling <php>BackedEnum::from()</php> or <php>BackedEnum::tryFrom()</php> is unchanged.

===== Future Scope =====
Further work might include

  * <php>never</php>-typed properties, to indicate that a property exists but subclasses are free to impose any restrictions desired on the type of the parameter; this would also allow <php>never</php>-typed property set hooks
  * Updating other existing core interfaces and abstract methods to use <php>never</php>-typed parameters; the case of <php>ArrayAccess</php> was heavily discussed on the mailing list with regard to the previous RFC. This RFC explicitly **does not** change any interface interface or abstract class other than <php>BackedEnum</php>

===== Proposed Voting Choices =====
Add <php>never</php>-typed parameters in the limited cases described above, and use them for backed enums?

<doodle title="Allow never parameters" auth="daniels" voteType="single" closed="false" closeon="2025-05-05T23:59:59Z">
   * Yes
   * No
</doodle>

===== Patches and Tests =====
https://github.com/php/php-src/pull/18016

===== Implementation =====
After the project is implemented, this section should contain 
  - the version(s) it was merged into
  - a link to the git commit(s)
  - a link to the PHP manual entry for the feature
  - a link to the language specification section (if any)

===== References =====
Links to external references, discussions or RFCs

  * [[rfc:never_for_parameter_types]] RFC
  * Discussion from that RFC: https://externals.io/message/115712
  * https://en.wikipedia.org/wiki/Bottom_type
  * [[rfc:property-hooks]] RFC
  * [[rfc:enumerations]] RFC

===== Changelog =====

0.2:

  * Added userland example

0.1:

  * Initial proposal
Page Tools
