Add Invokable interface

Analogous to the Stringable interface, Invokable is automatically
implemented for classes defining __invoke(), but can also be explicitly implemented.

This addresses a gap in PHP's type system:
- `callable` is too broad (accepts strings, arrays) and cannot be used as a property type.
- `Closure` is too narrow (excludes objects with __invoke()).
Invokable provides a proper OOP type for invokable objects, enabling property types,
intersection types, and instanceof checks.

Key behaviors:
- Marker interface with no methods to avoid LSP conflicts across varying __invoke() signatures.
- Auto-implemented in three phases: compilation, trait binding, and internal class registration (mirrors Stringable exactly).
- Can also be explicitly implemented:
    - Explicitly implementing Invokable requires an __invoke() method, or a fatal error is raised.
    - Abstract classes and interfaces are exempt, deferring the requirement to concrete subclasses.
- Closure explicitly implements Invokable.
- Invokable is covariant to callable in return type checks.
- Cached `ce->__invoke` field added to zend_class_entry for consistency with other magic methods, improving runtime lookup.

Author: aldemeery

Zend/tests/get_error_handler.phpt

@@ -8,7 +8,7 @@ class C {
     static function handleStatic() {}
 }
 
-class Invokable {
+class InvokableHandler {
     public function __invoke() {
     }
 }
@@ -46,8 +46,8 @@ echo "\nClosure\n";
 set_error_handler($f = function () {});
 var_dump(get_error_handler() === $f);
 
-echo "\nInvokable\n";
-set_error_handler($object = new Invokable());
+echo "\nInvokableHandler\n";
+set_error_handler($object = new InvokableHandler());
 var_dump(get_error_handler() === $object);
 
 echo "\nStable return value\n";
@@ -80,7 +80,7 @@ bool(true)
 Closure
 bool(true)
 
-Invokable
+InvokableHandler
 bool(true)
 
 Stable return value

Zend/tests/get_exception_handler.phpt

@@ -8,7 +8,7 @@ class C {
     static function handleStatic() {}
 }
 
-class Invokable {
+class InvokableHandler {
     public function __invoke() {
     }
 }
@@ -46,8 +46,8 @@ echo "\nClosure\n";
 set_exception_handler($f = function () {});
 var_dump(get_exception_handler() === $f);
 
-echo "\nInvokable\n";
-set_exception_handler($object = new Invokable());
+echo "\nInvokableHandler\n";
+set_exception_handler($object = new InvokableHandler());
 var_dump(get_exception_handler() === $object);
 
 echo "\nStable return value\n";
@@ -79,7 +79,7 @@ bool(true)
 Closure
 bool(true)
 
-Invokable
+InvokableHandler
 bool(true)
 
 Stable return value

Zend/tests/magic_methods/invokable_abstract_class.phpt

@@ -0,0 +1,45 @@
+--TEST--
+Abstract class can implement Invokable with abstract or concrete __invoke()
+--FILE--
+<?php
+
+/* Abstract class with abstract __invoke forces signature on subclasses */
+abstract class TypedHandler implements Invokable {
+    abstract public function __invoke(int $x): int;
+}
+
+class Doubler extends TypedHandler {
+    public function __invoke(int $x): int { return $x * 2; }
+}
+
+var_dump(new Doubler() instanceof Invokable);
+var_dump((new Doubler())(5));
+
+/* Abstract class with concrete __invoke */
+abstract class BaseHandler implements Invokable {
+    public function __invoke(string $s): string { return strtoupper($s); }
+}
+
+class MyHandler extends BaseHandler {}
+
+var_dump(new MyHandler() instanceof Invokable);
+var_dump((new MyHandler())("hello"));
+
+/* Abstract class implementing Invokable without __invoke at all (deferred to child) */
+abstract class DeferredHandler implements Invokable {}
+
+class ConcreteHandler extends DeferredHandler {
+    public function __invoke(): string { return "concrete"; }
+}
+
+var_dump(new ConcreteHandler() instanceof Invokable);
+var_dump((new ConcreteHandler())());
+
+?>
+--EXPECT--
+bool(true)
+int(10)
+bool(true)
+string(5) "HELLO"
+bool(true)
+string(8) "concrete"

Zend/tests/magic_methods/invokable_anonymous_class.phpt

@@ -0,0 +1,30 @@
+--TEST--
+Anonymous class with __invoke() auto-implements Invokable
+--FILE--
+<?php
+
+$obj = new class {
+    public function __invoke(): string {
+        return "anonymous";
+    }
+};
+
+var_dump($obj instanceof Invokable);
+var_dump($obj());
+
+/* Anonymous class with explicit implements */
+$obj2 = new class implements Invokable {
+    public function __invoke(): int {
+        return 42;
+    }
+};
+
+var_dump($obj2 instanceof Invokable);
+var_dump($obj2());
+
+?>
+--EXPECT--
+bool(true)
+string(9) "anonymous"
+bool(true)
+int(42)

Zend/tests/magic_methods/invokable_automatic_implementation.phpt

@@ -0,0 +1,75 @@
+--TEST--
+Invokable is automatically implemented
+--FILE--
+<?php
+
+/* Basic auto-implementation */
+class Test {
+    public function __invoke(): string {
+        return "foo";
+    }
+}
+
+var_dump(new Test instanceof Invokable);
+var_dump((new ReflectionClass(Test::class))->getInterfaceNames());
+
+/* Inheritance: child inherits Invokable from parent */
+class Child extends Test {}
+
+var_dump(new Child instanceof Invokable);
+var_dump((new ReflectionClass(Child::class))->getInterfaceNames());
+
+/* Child overrides __invoke */
+class ChildOverride extends Test {
+    public function __invoke(): string {
+        return "bar";
+    }
+}
+
+var_dump(new ChildOverride instanceof Invokable);
+
+/* Arbitrary signature: different params and return type */
+class Adder {
+    public function __invoke(int $a, int $b): int {
+        return $a + $b;
+    }
+}
+
+var_dump(new Adder instanceof Invokable);
+
+/* No params, no return type */
+class NoSig {
+    public function __invoke() {}
+}
+
+var_dump(new NoSig instanceof Invokable);
+
+/* Explicit + implicit: class has __invoke and writes implements Invokable */
+class ExplicitAndImplicit implements Invokable {
+    public function __invoke(): void {}
+}
+
+var_dump(new ExplicitAndImplicit instanceof Invokable);
+/* Should appear only once in the interface list */
+var_dump((new ReflectionClass(ExplicitAndImplicit::class))->getInterfaceNames());
+
+?>
+--EXPECT--
+bool(true)
+array(1) {
+  [0]=>
+  string(9) "Invokable"
+}
+bool(true)
+array(1) {
+  [0]=>
+  string(9) "Invokable"
+}
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+array(1) {
+  [0]=>
+  string(9) "Invokable"
+}

Zend/tests/magic_methods/invokable_callable_covariance.phpt

@@ -0,0 +1,65 @@
+--TEST--
+Invokable is covariant to callable in return types
+--FILE--
+<?php
+
+class Base {
+    public function getHandler(): callable {
+        return fn() => 1;
+    }
+}
+
+/* Invokable is a valid covariant return type for callable */
+class Child extends Base {
+    public function getHandler(): Invokable {
+        return new class {
+            public function __invoke(): int {
+                return 2;
+            }
+        };
+    }
+}
+
+$c = new Child();
+$handler = $c->getHandler();
+var_dump($handler instanceof Invokable);
+var_dump($handler());
+
+/* Concrete class with __invoke is also covariant to callable */
+class Handler {
+    public function __invoke(): int {
+        return 3;
+    }
+}
+
+class Child2 extends Base {
+    public function getHandler(): Handler {
+        return new Handler();
+    }
+}
+
+$c2 = new Child2();
+$handler2 = $c2->getHandler();
+var_dump($handler2 instanceof Invokable);
+var_dump($handler2());
+
+/* Closure is covariant to callable via Invokable */
+class Child3 extends Base {
+    public function getHandler(): Closure {
+        return fn() => 4;
+    }
+}
+
+$c3 = new Child3();
+$handler3 = $c3->getHandler();
+var_dump($handler3 instanceof Invokable);
+var_dump($handler3());
+
+?>
+--EXPECT--
+bool(true)
+int(2)
+bool(true)
+int(3)
+bool(true)
+int(4)

Zend/tests/magic_methods/invokable_closure.phpt

@@ -0,0 +1,31 @@
+--TEST--
+Closure implements Invokable
+--FILE--
+<?php
+
+/* Arrow function */
+$fn = fn() => 1;
+var_dump($fn instanceof Invokable);
+
+/* Anonymous function */
+$fn2 = function(int $x): int { return $x * 2; };
+var_dump($fn2 instanceof Invokable);
+
+/* Closure::fromCallable */
+$fn3 = Closure::fromCallable('strlen');
+var_dump($fn3 instanceof Invokable);
+
+/* First-class callable syntax */
+$fn4 = strlen(...);
+var_dump($fn4 instanceof Invokable);
+
+/* Reflection confirms Closure implements Invokable */
+var_dump(in_array('Invokable', (new ReflectionClass(Closure::class))->getInterfaceNames()));
+
+?>
+--EXPECT--
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)

Zend/tests/magic_methods/invokable_enum.phpt

@@ -0,0 +1,31 @@
+--TEST--
+Enums with __invoke() auto-implement Invokable
+--FILE--
+<?php
+
+/* Enum with __invoke auto-implements Invokable */
+enum Color {
+    case Red;
+    case Blue;
+    public function __invoke(): string { return $this->name; }
+}
+
+var_dump(Color::Red instanceof Invokable);
+var_dump((Color::Red)());
+
+/* Enum explicitly implementing Invokable */
+enum Direction implements Invokable {
+    case Up;
+    case Down;
+    public function __invoke(): int { return $this === self::Up ? 1 : -1; }
+}
+
+var_dump(Direction::Up instanceof Invokable);
+var_dump((Direction::Up)());
+
+?>
+--EXPECT--
+bool(true)
+string(3) "Red"
+bool(true)
+int(1)

Zend/tests/magic_methods/invokable_enum_without_invoke.phpt

@@ -0,0 +1,12 @@
+--TEST--
+Enum explicitly implementing Invokable without __invoke() causes fatal error
+--FILE--
+<?php
+
+enum Color implements Invokable {
+    case Red;
+}
+
+?>
+--EXPECTF--
+Fatal error: Enum Color must have an __invoke() method to implement Invokable in %s on line %d

Zend/tests/magic_methods/invokable_explicit_without_invoke.phpt

@@ -0,0 +1,10 @@
+--TEST--
+Explicit implements Invokable without __invoke() causes fatal error
+--FILE--
+<?php
+
+class Bad implements Invokable {}
+
+?>
+--EXPECTF--
+Fatal error: Class Bad must have an __invoke() method to implement Invokable in %s on line %d