[php-src] PR #21574: Add `Invokable` interface
| From: | aldemeery | 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.