[RFC] Never parameters

Zend/tests/never-parameters/allowed_on_abstract_method.phpt

@@ -0,0 +1,11 @@
+--TEST--
+`never` parameter types - allowed on abstract methods
+--FILE--
+<?php
+
+abstract class Demo {
+    abstract public function example(never $v);
+}
+
+?>
+--EXPECT--

Zend/tests/never-parameters/allowed_on_interfaces.phpt

@@ -0,0 +1,11 @@
+--TEST--
+`never` parameter types - allowed on interfaces' methods
+--FILE--
+<?php
+
+interface Demo {
+    public function example(never $v);
+}
+
+?>
+--EXPECT--

Zend/tests/never-parameters/ast_output.phpt

@@ -0,0 +1,19 @@
+--TEST--
+`never` parameter types - AST output from assertions
+--FILE--
+<?php
+
+try {
+    assert(false && new class {
+        public function invalid(never $v) {}
+    });
+} catch (Error $e) {
+    echo $e->getMessage() . "\n";
+}
+?>
+--EXPECT--
+assert(false && new class {
+    public function invalid(never $v) {
+    }
+
+})

Zend/tests/never-parameters/backed_enum.phpt

@@ -0,0 +1,91 @@
+--TEST--
+`never` parameter types - BackedEnum uses never, backed enums have parameter types
+--FILE--
+<?php
+
+function enumMethod(string $class, string $name) {
+    echo "$class::$name():\n";
+    $method = new ReflectionMethod($class, $name);
+    if ($method->hasPrototype()) {
+        $proto = $method->getPrototype();
+        echo "Prototype: " . $proto->class . "::" . $proto->name . "\n";
+    }
+    $param = $method->getParameters()[0];
+    echo $param . "\n";
+
+    $type = $param->getType();
+
+    assert($type instanceof ReflectionNamedType);
+    echo "Name: " . $type->getName() . "\n";
+    echo "isBuiltin: " . $type->isBuiltIn() . "\n";
+    echo "allowsNull: " . (int)$type->allowsNull() . "\n";
+}
+
+enum MyBoolean: int {
+    case FALSE = 0;
+    case TRUE = 1;
+}
+enum CardSuit: string {
+    case HEARTS = 'Hearts';
+    case DIAMONDS = 'Diamonds';
+    case CLUBS = 'Clubs';
+    case SPADES = 'Spades';
+}
+
+enumMethod(BackedEnum::class, "from");
+echo "\n";
+enumMethod(BackedEnum::class, "tryFrom");
+echo "\n\n";
+
+enumMethod(MyBoolean::class, "from");
+echo "\n";
+enumMethod(MyBoolean::class, "tryFrom");
+echo "\n\n";
+
+enumMethod(CardSuit::class, "from");
+echo "\n";
+enumMethod(CardSuit::class, "tryFrom");
+
+?>
+--EXPECT--
+BackedEnum::from():
+Parameter #0 [ <required> never $value ]
+Name: never
+isBuiltin: 1
+allowsNull: 0
+
+BackedEnum::tryFrom():
+Parameter #0 [ <required> never $value ]
+Name: never
+isBuiltin: 1
+allowsNull: 0
+
+
+MyBoolean::from():
+Prototype: BackedEnum::from
+Parameter #0 [ <required> int $value ]
+Name: int
+isBuiltin: 1
+allowsNull: 0
+
+MyBoolean::tryFrom():
+Prototype: BackedEnum::tryFrom
+Parameter #0 [ <required> int $value ]
+Name: int
+isBuiltin: 1
+allowsNull: 0
+
+
+CardSuit::from():
+Prototype: BackedEnum::from
+Parameter #0 [ <required> string $value ]
+Name: string
+isBuiltin: 1
+allowsNull: 0
+
+CardSuit::tryFrom():
+Prototype: BackedEnum::tryFrom
+Parameter #0 [ <required> string $value ]
+Name: string
+isBuiltin: 1
+allowsNull: 0

Zend/tests/never-parameters/basic_usage_abstract.phpt

@@ -0,0 +1,42 @@
+--TEST--
+`never` parameter types - basic usage with an abstract class
+--FILE--
+<?php
+
+abstract class BoxedValue {
+    abstract public function get(): mixed;
+    abstract public function set(never $v): void;
+}
+
+class BoxedInt extends BoxedValue {
+    public function __construct(
+        private int $value
+    ) {}
+
+    public function get(): int {
+        return $this->value;
+    }
+    public function set(int $v): void {
+        $this->value = $v;
+    }
+}
+
+$box = new BoxedInt(5);
+var_dump($box);
+var_dump($box->get());
+$box->set(7);
+var_dump($box);
+var_dump($box->get());
+
+?>
+--EXPECTF--
+object(BoxedInt)#%d (1) {
+  ["value":"BoxedInt":private]=>
+  int(5)
+}
+int(5)
+object(BoxedInt)#%d (1) {
+  ["value":"BoxedInt":private]=>
+  int(7)
+}
+int(7)

Zend/tests/never-parameters/basic_usage_interface.phpt

@@ -0,0 +1,42 @@
+--TEST--
+`never` parameter types - basic usage with an interface
+--FILE--
+<?php
+
+interface BoxedValue {
+    public function get(): mixed;
+    public function set(never $v): void;
+}
+
+class BoxedInt implements BoxedValue {
+    public function __construct(
+        private int $value
+    ) {}
+
+    public function get(): int {
+        return $this->value;
+    }
+    public function set(int $v): void {
+        $this->value = $v;
+    }
+}
+
+$box = new BoxedInt(5);
+var_dump($box);
+var_dump($box->get());
+$box->set(7);
+var_dump($box);
+var_dump($box->get());
+
+?>
+--EXPECTF--
+object(BoxedInt)#%d (1) {
+  ["value":"BoxedInt":private]=>
+  int(5)
+}
+int(5)
+object(BoxedInt)#%d (1) {
+  ["value":"BoxedInt":private]=>
+  int(7)
+}
+int(7)

Zend/tests/never-parameters/cannot_narrow.phpt

@@ -0,0 +1,16 @@
+--TEST--
+`never` parameter types - `never` narrows the signature
+--FILE--
+<?php
+
+interface Base {
+    public function example(string $v);
+}
+
+interface WithNever extends Base {
+    public function example(never $v);
+}
+
+?>
+--EXPECTF--
+Fatal error: Declaration of WithNever::example(never $v) must be compatible with Base::example(string $v) in %s on line %d

Zend/tests/never-parameters/must_be_method.phpt

@@ -0,0 +1,9 @@
+--TEST--
+`never` parameter types - can only be applied to class methods
+--FILE--
+<?php
+
+function demo(never $unused) {}
+?>
+--EXPECTF--
+Fatal error: never cannot be used as a parameter type for functions in %s on line %d

Zend/tests/never-parameters/no_body.phpt

@@ -0,0 +1,14 @@
+--TEST--
+`never` parameter types - cannot be used for parameters on methods with bodies
+--FILE--
+<?php
+
+abstract class Demo {
+    public function example(never $v) {
+        // Nothing
+    }
+}
+
+?>
+--EXPECTF--
+Fatal error: Function Demo::example() containing a body cannot use never as a parameter type in %s on line %d

Zend/tests/never-parameters/no_defaults.phpt

@@ -0,0 +1,12 @@
+--TEST--
+`never` parameter types - cannot be used for parameters with defaults
+--FILE--
+<?php
+
+interface Demo {
+    public function example(never $v = 5);
+}
+
+?>
+--EXPECTF--
+Fatal error: Cannot use int as default value for parameter $v of type never in %s on line %d

Zend/tests/never-parameters/no_hooks.phpt

@@ -0,0 +1,13 @@
+--TEST--
+`never` parameter types - cannot be used for hooked properties
+--FILE--
+<?php
+
+interface I
+{
+    public mixed $both { get; set( never $value ); }
+}
+
+?>
+--EXPECTF--
+Fatal error: Type of parameter $value of hook I::$both::set must be compatible with property type in %s on line %d

Zend/tests/never-parameters/no_intersection.phpt

@@ -0,0 +1,12 @@
+--TEST--
+`never` parameter types - cannot be part of an intersection
+--FILE--
+<?php
+
+interface Demo {
+    public function example(never&Example $v);
+}
+
+?>
+--EXPECTF--
+Fatal error: Type never cannot be part of an intersection type in %s on line %d

Zend/tests/never-parameters/no_union.phpt

@@ -0,0 +1,12 @@
+--TEST--
+`never` parameter types - cannot be part of a union
+--FILE--
+<?php
+
+interface Demo {
+    public function example(never|Example $v);
+}
+
+?>
+--EXPECTF--
+Fatal error: never can only be used as a standalone type in %s on line %d

Zend/tests/never-parameters/reflection.phpt

@@ -0,0 +1,26 @@
+--TEST--
+`never` parameter types - indicated via reflection
+--FILE--
+<?php
+
+abstract class BoxedValue {
+    abstract public function get(): mixed;
+    abstract public function set(never $v): void;
+}
+
+$ref = new ReflectionParameter([BoxedValue::class, 'set'], 'v');
+echo $ref . "\n";
+
+$type = $ref->getType();
+
+assert($type instanceof ReflectionNamedType);
+echo "Name: " . $type->getName() . "\n";
+echo "isBuiltin: " . $type->isBuiltIn() . "\n";
+echo "allowsNull: " . (int)$type->allowsNull() . "\n";
+
+?>
+--EXPECT--
+Parameter #0 [ <required> never $v ]
+Name: never
+isBuiltin: 1
+allowsNull: 0

Zend/tests/never-parameters/untyped_implements.phpt

@@ -0,0 +1,42 @@
+--TEST--
+`never` parameter types - on interface, implementing class has no parameter type
+--FILE--
+<?php
+
+interface BoxedValue {
+    public function get(): mixed;
+    public function set(never $v): void;
+}
+
+class BoxedAnything implements BoxedValue {
+    public function __construct(
+        private mixed $value
+    ) {}
+
+    public function get(): mixed {
+        return $this->value;
+    }
+    public function set($v): void {
+        $this->value = $v;
+    }
+}
+
+$box = new BoxedAnything(5);
+var_dump($box);
+var_dump($box->get());
+$box->set("testing");
+var_dump($box);
+var_dump($box->get());
+
+?>
+--EXPECTF--
+object(BoxedAnything)#%d (1) {
+  ["value":"BoxedAnything":private]=>
+  int(5)
+}
+int(5)
+object(BoxedAnything)#%d (1) {
+  ["value":"BoxedAnything":private]=>
+  string(7) "testing"
+}
+string(7) "testing"