PHP's __isset() magic method has a structural ambiguity: it returns one bit but is asked two
questions (“does it exist?” and “is it non-null?”). The language constructs that trigger it
(isset(), ??, empty()) treat null as “not set”, forcing __isset() to answer the
narrow “set and not null” rather than the broader “exists”. This makes __isset() unable to
model an underlying store that distinguishes null from “missing” (a distinction arrays expose
through array_key_exists()) and it breaks the documented equivalence isset($x) ? $x : $y
<=> $x ?? $y for magic properties.
Magic accessors remain load-bearing in widely-used PHP: Laravel's Eloquent ORM is built on them, as is any code dealing with property names that are not known at class declaration. Native lazy objects and property hooks (PHP 8.4) cover declared shapes, not runtime-discovered ones. Fixing the broken documented semantics on magic properties is therefore a current concern, not a legacy cleanup.
This RFC adds a new opt-in magic method, __exists(), that answers the existence question
independently from value. It restores isset() <=> ?? equivalence on magic properties and gives
userland code a way to tell null apart from “missing” through a direct method call.
A narrower engine-side fix for the redundant __get() call under ?? and empty()
(tracked in GH-12695) landed separately in PHP 8.6
and is referenced in the Rationale section. This RFC addresses what that fix cannot reach by
design: the structural ambiguity above.
For arrays, the language gives users two distinct primitives:
$a = ['x' => null]; isset($a['x']); // false array_key_exists('x', $a); // true
For objects there is no equivalent. __isset() is forced into the isset() contract (return false
for null), so a userland store that uses null as a meaningful value (caches, JSON-mapped objects,
RPC stubs, configuration objects) cannot expose its own existence semantics through a magic method at all.
This is the central gap: a method whose return type is bool can carry only one bit of
information, while modelling these stores requires two (“exists?” and “non-null?”). The
single available bit is consumed by isset()s null-folding rule, leaving “exists?” unanswerable.
The ''??'' RFC documents that $x ?? $y is intended as a
shorthand for isset($x) ? $x : $y. This holds for normal properties and for arrays, but not for
magic properties:
class B { public function __get($n) { return null; } public function __isset($n) { return true; } } $b = new B; var_dump($b->any ?? 5); // int(5): ?? checks __get's return for null var_dump(isset($b->any) ? $b->any : 5); // NULL: isset() trusts __isset, returns null from __get var_dump(isset($b->any)); // bool(true) does not consult __get at all
The three forms disagree because isset() on a magic property today only calls __isset() and
does not verify the value is non-null via __get(). The ?? operator does. There is no way to
align these without either calling __get() twice (slow, breaks BC) or returning a possibly-null result
from ?? (breaks documentation and static analyzers). The ambiguity in __isset() is the reason
the engine had to choose, and either choice contradicts a different reasonable expectation.
This RFC adds a new magic method:
public function __exists(string $name): bool;
It answers “does this property logically exist?”, independent of whether its value is null.
__isset() BC behaviour) or declared as string. Subclasses may widen the parameter type contravariantly (e.g. string|int), as with any other method.bool (or a covariant subtype such as true or false). Unlike __isset(), which permits an undeclared return type for backwards compatibility with code that predates return type declarations, __exists() is a new method and the BC carve-out does not apply to it.__isset() / __get()).__isset()).
When a class defines __exists(), the engine consults it instead of __isset() for the following
language constructs:
$obj->prop ?? fallbackisset($obj->prop)empty($obj->prop)?? ($obj?->prop ?? fallback)
__isset() is not called by the engine when __exists() is defined. property_exists() is
not affected by __exists() (mirrors today's behavior for __isset()): property_exists()
continues to inspect the declared class shape and instance properties only, never magic.
The rules below apply only when a class defines __exists(). Classes that do not define
it observe the engine's existing behaviour unchanged; that behaviour is laid out in full under
Existing sequencing near the end of this RFC.
For $obj->prop ?? $y:
__exists($prop).false, ?? evaluates $y. __get() is not called.true and the property now exists on the object (typically because __exists() just wrote to it), its value is returned directly, with ?? applying its usual null check on top. __get() is not called.__get($prop) is called and its return is the result, with ?? applying its usual null check on top.
For isset($obj->prop) (and equivalently empty($obj->prop)):
__exists($prop).false, isset() returns false (and empty() returns true). __get() is not called.true and the property now exists on the object, the standard isset()/empty() rules are applied to its value (i.e. isset() is false when the value is null). __get() is not called.__get($prop) is called and the same rules are applied to its return value.
This restores the documented equivalence isset($x) ? $x : $y <=> $x ?? $y for any class that
defines __exists(): both go through the same fetch-then-null-check pipeline.
__exists() is allowed to mutate object state; the re-check above ensures any mutation is
observed without an extra __get() call. This matches the behaviour PHP 8.6 already gives
__isset() (the GH-12695 fix).
A class can declare both __isset() and __exists(). This is intended as a forward-compatibility
shim: a library can ship __exists() on PHP 8.6+ while keeping __isset() for older runtimes. On
PHP 8.6+, only __exists() is consulted by the engine. On older runtimes, only __isset() is.
No diagnostic is emitted for declaring both: that would defeat the shim.
__exists() is a regular method and can be called directly to disambiguate “set to null”
from “missing”, the same way array_key_exists() is called for arrays:
class C { private array $store = ['nullProp' => null]; public function __exists(string $n): bool { return array_key_exists($n, $this->store); } public function __get(string $n): mixed { return $this->store[$n] ?? null; } } $c = new C; var_dump($c->__exists('nullProp')); // bool(true): exists, even though value is null var_dump(isset($c->nullProp)); // bool(false): isset() still folds null into "not set"
Standard. __exists() is inherited like any other method. Classes that override their parent's
__isset() may instead introduce __exists(); this is the recommended migration path.
When a child defines __exists() and a parent defines __isset(), the child's __exists()
takes effect for the whole magic check (including for properties whose semantics live in the parent's
__get()).
__exists() uses the same recursion guard as __isset(): a recursive isset()/??
call on the same property from inside __exists() short-circuits to “not set”, preventing
infinite recursion.
__exists() is skipped for never-initialized typed properties, exactly like __isset().
The opt-in for engaging magic methods on a declared property is the existing one: call unset()
on it (typically from the constructor), which is the same pattern lazy proxies have used with
__isset() for years.
This keeps a single, well-known mental model for “when do magic methods apply to a typed property”
across both methods, so migration to __exists() does not require revisiting that question.
#[AllowDynamicProperties] class A { public function __exists(string $n): bool { $this->$n = 123; return true; } public function __get(string $n): mixed { throw new Exception('unreachable when __exists materialised the property'); } } $a = new A; echo $a->foo ?? 234; // 123 (__get is not called)
A class that has only __get() today sees isset() always return false and empty()
always return true on its magic properties (the engine never consults __get() from those
constructs). Adding __exists() fixes both for free, even when it always returns true:
class C { public function __exists(string $n): bool { return true; } public function __get(string $n): mixed { /* return value, or null if absent */ } }
| expression | __get() only | __get() + always-true __exists() |
|---|---|---|
isset($c->present) | false | true |
empty($c->present) | true | false |
$c->present ?? 'fb' | unchanged | unchanged |
Caveat: this default assumes __get() returns null for unknown names without throwing. If
__get() throws on unknown names, __exists() must instead mirror the underlying store (see
Distinguishing null from missing below) so that isset() does not propagate the exception.
class JsonRecord { public function __construct(private array $data) {} public function __exists(string $name): bool { return array_key_exists($name, $this->data); } public function __get(string $name): mixed { if (!array_key_exists($name, $this->data)) { throw new RuntimeException("Field $name does not exist in record"); } return $this->data[$name]; } } $r = new JsonRecord(['nullable' => null]); $r->__exists('nullable'); // true $r->__exists('missing'); // false isset($r->nullable); // false (isset()'s null-folding) isset($r->missing); // false $r->nullable; // null (no exception, exists) $r->missing; // throws (does not exist)
class LazyProxy extends Real { private bool $initialized = false; public function __exists(string $n): bool { if (!$this->initialized) { $this->initialize(); } return parent::__exists($n); // or property_exists / array_key_exists / etc. } public function __get(string $n): mixed { if (!$this->initialized) { $this->initialize(); } return parent::__get($n); } private function initialize(): void { /* ... */ } }
class C { // Used by PHP 8.5 and earlier: public function __isset(string $n): bool { return $this->__exists($n) && null !== $this->__get($n); } // Used by PHP 8.6 and later: public function __exists(string $n): bool { return /* ... */; } public function __get(string $n): mixed { /* ... */ } }
The smallest engine-side fix in this space, re-checking whether the property exists after
__isset() to skip a redundant __get() under ?? and empty(), already landed
in PHP 8.6 independently
of this RFC. It resolves the sequencing issue tracked in
GH-12695.
What the engine fix cannot reach is the structural ambiguity at the heart of this RFC:
__isset() returns one bit but is being asked two questions. Two broader fixes were discussed
in the GH-12695 thread and rejected for concrete behaviour breaks:
isset() call __get() to verify non-null on magic properties. Doubles the userland calls for every isset() on a magic property. Any class whose __get() has side effects (logging, cache warm-up, counters, lazy init) sees those side effects run at every isset(), where they don't run at all today. Universal BC break.?? trust __isset() and not check the __get() result for null. ?? would now be able to return null, contradicting the documented “set and not null” contract and breaking static analyzers that infer “non-null” from the operator.
Both alternatives are one-size changes to constructs that already-existing classes depend on. The
opt-in path here lets classes that need the correct semantics commit to a new contract
(__exists() plus the engine's adjusted dispatch) without forcing the entire ecosystem through
the same migration. Classes that don't opt in are unaffected; classes that do gain the cleaner
sequencing automatically.
Two reasons:
??. The documented contract isset($x) ? $x : $y <=> $x ?? $y is currently broken on magic properties; restoring it on classes that opt in is the cleanest available fix.isset() as “set and not null”. Magic properties that opt into the new mechanism should not silently break that learning.
The cost is one extra __get() call per isset() on a magic property. This is opt-in: classes that
care about preserving the old single-call behavior simply do not declare __exists().
Two alternative dispatch designs were considered and rejected:
__isset() and __exists() for every isset()/empty()/??. Doubles userland calls with subtle ordering rules and provides nothing the single-method dispatch cannot.isset()/empty() to __isset() and ?? to __exists(). Saves one __get() call per isset() on dual-defined classes, but requires userland to keep both methods consistent; any drift re-introduces the isset() vs ?? disagreement this RFC is fixing.
The simpler rule wins: “if __exists() is defined, __isset() is dormant on PHP 8.6+.”
Declaring both remains valid as a forward-compatibility shim pattern.
?? itself incurs no extra cost compared to today's __isset() path. The extra
__get() call only appears for standalone isset()/empty() and for the
isset($x) ? $x : $y form; code that prefers the documented-equivalent $x ?? $y gets the
optimal call count automatically.
__isset() has shipped since PHP 5 and is widely used. A deprecation in the same release that
introduces __exists() would force every existing class to migrate immediately, which is precisely
the BC cost this RFC is structured to avoid.
Eventual deprecation is a plausible long-term direction once __exists() has seen meaningful
adoption (a future major version, not this RFC). The present RFC takes no position on whether that
will actually happen; it simply leaves the door open. Both methods coexisting indefinitely is also
a valid endgame.
That said, the PHP manual and adjacent reference documentation should recommend __exists() as
the preferred choice for new code. This steers adoption without imposing the immediate migration
cost of a formal deprecation.
property_exists() is documented as a reflection-style operator over the declared class shape
plus instance dynamic properties; it explicitly does not invoke magic methods. Hooking __exists()
into it would change that contract and would also create a path for property_exists() to throw
or run arbitrary code, contradicting decades of expectations. Users who want “magic-aware
existence” should call $obj->__exists($name) directly.
__exists was chosen over __has, __propertyExists or __hasProperty. It mirrors
ArrayAccess::offsetExists() (closest existing analogue) and is short.
None. __exists() is opt-in: classes that do not define it observe identical behavior.
The __-prefix namespace is reserved by PHP for language use, so any pre-existing
__exists method is already operating in reserved space. In practice the name is
self-describing enough that a colliding method would already mean “does this exist?”, so the
new dispatch lines up with the existing intent. As with __isset() in PHP 5, the
engine validates the signature at class compile time and emits a fatal error if it is
incompatible.
Next minor version (PHP 8.6 or later).
None.
opcache: adds the new ce->__exists slot to the persistence path (zend_persist.c, zend_file_cache.c). Required because magic-method pointers are re-resolved across persistence; a missed slot results in an invalid pointer and a crash on the first call. Mechanical change.reflection: ReflectionProperty::isReadable() consults __exists() (preferred) or __isset() when __get() is defined. This matches user intent for “is this readable” on classes that have migrated to __exists().No other extension is affected.
__isset() patterns can update guidance.
During discussion, an alternative was raised: rather than adding __exists(), extend
__isset() to optionally return a three-state enum (e.g. Isset::Set, Isset::Null,
Isset::Unset) so that a single magic method carries both bits of information.
This was rejected for two main reasons:
__isset() return type other than bool or a covariant subtype. Declaring public function __isset(string $n): Isset or public function __isset(string $n): bool|Isset produces a fatal error at class compile time on those runtimes (ClassName::__isset(): Return type must be bool when declared). The only workarounds are dropping the return type entirely (a regression for typed codebases) or shipping two version-conditional class declarations (which defeats the single-source-of-truth premise the proposal rests on). By contrast, choosing a new magic method is a deliberate FC design choice: __exists() is a regular method on PHP 8.5 and earlier and elevates to magic on PHP 8.6+. The same source file runs everywhere with no declaration changes, and the convention is usable on older PHP today: callers can probe method_exists($obj, '__exists') and dispatch through it as a disambiguation primitive, so libraries can adopt the pattern now and deliver value before PHP 8.6 is universally available. The enum proposal has no such bridge.__isset() and __exists() could disagree about a property's state. But in this RFC, the engine never consults both: when __exists() is defined, __isset() is fully dormant. The disagreement is structurally impossible.
Direct-call ergonomics also favour a separate method: $obj->__exists($n) returns a
plain bool, making it the natural disambiguation primitive (mirroring
array_key_exists()), whereas $obj->__isset($n) === Isset::Null would be wordier and
leak the enum into every consumer that asks “exists?”.
PHP 8.4 property hooks raise an open question this RFC takes no position on: should there be an
exists hook alongside get/set?
One view: a hooked property already “exists” by virtue of having a hook, and isset()/?? on
it should simply use the value the get hook returns (which is what happens today). On that
view, there is no gap to close.
Another view: a get hook over a backing store where the key may legitimately be missing has the
same ambiguity this RFC fixes for magic properties. A symmetric exists hook would let the
hooked property model that distinction:
public ?string $name { get => $this->store['name'] ?? null; exists => array_key_exists('name', $this->store); }
Either way, hooks are a separate surface (per-property, declared-shape) with their own questions
(interaction with the $field backing-property visibility, virtual hooks, asymmetric visibility,
inheritance), and any extension belongs in its own RFC. This proposal is scoped to magic
properties.
A class with only __get() defined sees isset() always return false and empty()
always return true on its magic properties, which is a known footgun. An adjacent diagnostic
(warning, possibly graduating to a deprecation later) could nudge users to declare one of
__isset() or __exists(). Deferred to a follow-up RFC: it has its own impact analysis
to do (Eloquent and similar base classes may pattern-match the rule) and is orthogonal to this
proposal.
Discussed in the Rationale section: it is a plausible long-term direction but uncommitted, and deliberately left for a future RFC.
For completeness, here is the engine's behaviour today when a class does not define
__exists(). The property-table re-check after __isset() is the engine fix that landed
in PHP 8.6 for GH-12695.
For $obj->prop ?? $y:
__isset($prop).?? evaluates $y.__isset() just wrote to it), its value is the result. Otherwise __get($prop) is called and ?? applies its usual null check on top.
For isset($obj->prop):
__isset($prop). Its return (cast to bool) is the result; __get() is not called, even when the value is in fact null.
For empty($obj->prop):
__isset($prop).empty() returns true.empty() returns whether its value is falsy. Otherwise __get($prop) is called (when defined) and empty() applies the same check to its return value. With no __get(), empty() returns true.$obj->prop ?? $y: __get($prop) is called and ?? applies its usual null check.isset($obj->prop): always returns false. __get() is not called.empty($obj->prop): always returns true. __get() is not called.
This is the “broken isset() on magic properties” path that the Recommended floor for classes with __get example above fixes.
The standard “undefined property” path applies: $obj->prop ?? $y returns $y silently
(after a notice on direct read), isset($obj->prop) returns false, empty($obj->prop)
returns true.
Voting opens YYYY-MM-DD and closes YYYY-MM-DD.
Requires 2/3 majority.
Implementation: https://github.com/php/php-src/pull/22240
Tests live under Zend/tests/magic_methods/exists/ and cover:
?? with __exists() returning true / false?? when __exists() materialises the property (no __get() call)isset() / empty() equivalence with ??__isset() and __exists() defined: __exists() wins__exists() overrides parent __isset()__exists() on the same property__get()__isset()); unset() opt-in__exists() call disambiguates “set to null” from “missing”__isset() behavior remains unchanged when __exists() is absent