[php-src] PR #21574: Add `Invokable` interface

From: Date: Sun, 29 Mar 2026 20:15:53 +0000
Subject: [php-src] PR #21574: Add `Invokable` interface
Groups: php.git-pulls 
Request: Send a blank email to git-pulls+get-35433@lists.php.net to get a copy of this message
Pull Request: https://github.com/php/php-src/pull/21574 Author: aldemeery ### TLDR; 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. --- ### Background This has been a known gap for a while. The 2008 RFC (https://wiki.php.net/rfc/invokable) never landed, and the discussion resurfaced in PR #15492 when @ondrejmirtes asked about extending Closure's callable covariance to all __invoke() objects. @Girgias's reply at the time was direct: *"we'd need a Stringable equivalent for __invoke()"*. The same sentiment was echoed by her and @Crell on the [PHP Foundation Discourse in November 2024](https://discourse.thephp.foundation/t/php-dev-make-closure-covariant-to-callable/831). The idea had community endorsement but no implementation. This PR is that implementation. --- ### What this adds An Invokable marker interface, auto-implemented for any class that defines __invoke(), following the Stringable pattern precisely. The auto-implementation works in three phases: at compilation for user-space classes, at trait binding for __invoke() inherited from traits, and at internal class registration. Closure explicitly declares implements Invokable in its stub. This is necessary because its __invoke() is generated per-instance and never appears in the function table. Invokable also satisfies covariant return type checks against callable. Rather than adding Closure as a separate special case alongside this, Closure's existing covariance was unified under Invokable: it satisfies the check because it implements the interface, not through a parallel path. A side fix included here: __invoke was the only major magic method without a cached pointer in zend_class_entry. This adds zend_function *__invoke to the struct, consistent with every other magic method. --- ### On the marker interface design @iluuu1994 raised this in a [related discussion](https://github.com/php/php-src/issues/18161#issuecomment-2785947995): the interface could be a marker that the engine implements but that users cannot implement manually, since without a declared signature it's arguably meaningless. I think there's a better middle ground. The reason __invoke() can't be declared in the interface is LSP. Unlike __toString(): string, there is no signature compatible with all valid __invoke() implementations. But that doesn't mean explicit implementation is pointless. This PR allows users to write implements Invokable explicitly and enforces that they actually have __invoke(), with a fatal error if they don't. Abstract classes and interfaces are exempt, deferring enforcement to concrete subclasses. This gives explicit implements Invokable real meaning: it's self-documenting, statically analysable, and engine-enforced. More importantly, it enables typed callable contracts through interface extension: ```php interface RequestHandler extends Invokable { public function __invoke(Request $req): Response; } ``` Here Invokable is the base, and RequestHandler pins down the signature. This is the pattern that makes the interface genuinely useful beyond instanceof checks, something neither pure duck typing nor a non-implementable marker would allow. --- ### What this unlocks ```php // Property types class Pipeline { public function __construct(private Invokable $handler) {} } // Intersection types function process(Invokable&Loggable $handler): void {} // Covariant return types class Child extends Base { public function getHandler(): Invokable { ... } // parent returns callable } ``` --- ### Backward compatibility None broken. Classes with __invoke() gain the interface silently, same as Stringable in 8.0. --- ### Tests 15 new test files: auto-implementation, inheritance, traits, Closure, explicit implementation, enforcement, property types, callable covariance, type declarations, interface extension, abstract classes, anonymous classes, intersection types, enums, and visibility edge cases. --- ### RFC I'm working through the RFC submission process and will post to internals shortly. Submitting the implementation early to give reviewers something concrete to discuss.

« previous php.git-pulls (#35433) next »