====== PHP RFC: Allow Object Property Writes on Objects Referenced by Constants ======
    * Version: 0.3
    * Date: 2026-06-28
    * Author: Khaled Alam, khaledalam.net@gmail.com
    * Status: Under Discussion
    * Implementation: https://github.com/php/php-src/pull/20903

===== Introduction =====
This RFC allows writing to **object properties** (and <php>isset()</php> / <php>unset()</php> on properties) when the object instance is referenced by a constant.

PHP constants are immutable in the sense that the constant binding cannot be changed. However, objects in PHP are mutable by design: mutating an object property does not rebind the constant, it only updates the state of the referenced object.

Today, PHP rejects <php>CONST_OBJ->prop = ...</php> with a fatal error ("Cannot use temporary expression in write context").
This RFC proposes permitting property write operations in this specific scenario, aligning behavior with user expectations while keeping the constant binding immutable.

<PHP>
<?php
const OBJ = new stdClass();

OBJ->value = 123;
var_dump(OBJ->value); // int(123)

unset(OBJ->value);
var_dump(isset(OBJ->value)); // bool(false)
?>
</PHP>

This applies both to **global constants** (<php>const</php> / <php>define()</php>) and to **class constants** (<php>Cls::CONST</php>).
  
===== Proposal =====
This RFC proposes to allow property write operations where the base expression is a constant that evaluates to an object.

The change is intentionally narrow:
  * It permits **object property** writes (<php>-></php>) and related operations (<php>isset</php>, <php>unset</php>, compound assignment, increment/decrement, string concatenation) on objects referenced by constants.
  * It permits **passing constant object properties by reference** to functions (including the "BP_VAR_FUNC_ARG" path when the function is declared after the call site).
  * It does **not** make constants mutable (rebinding remains illegal).
  * It does **not** change array/dimension write semantics (<php>[]</php>), nor does it change "write-to-temporary" behavior for dims.
  * It applies to both **global constants** (<php>CONST->prop = ...</php>) and **class constants** (<php>Cls::CONST->prop = ...</php> and <php>$obj::CONST->prop = ...</php>).
 

Specifically, the following operations become valid:

  * Assignment to a property:<PHP>
<?php
const OBJ = new stdClass();
OBJ->prop = "value";
?>
</PHP><PHP> 
  <?php
  const BACKING = new stdClass();
  
  class C {
      const O = BACKING;
  }

  C::O->prop = 42;        // via class name
  var_dump(C::O->prop);   // int(42)
  
  $c = new C();
  $c::O->prop = 'updated'; // via instance
  var_dump(C::O->prop);    // string(7) "updated"
  ?>
  </PHP>

  * Compound operations on a property:<PHP>
<?php
const OBJ = new stdClass();
OBJ->counter = 0;
OBJ->counter++;
OBJ->counter--;
OBJ->counter += 10;
OBJ->str = 'hello';
OBJ->str .= ' world';
?>
</PHP>

  * <php>isset()</php> / <php>unset()</php> on a property:<PHP>
<?php
const OBJ = new stdClass();
OBJ->prop = 1;
var_dump(isset(OBJ->prop)); // true
unset(OBJ->prop);
var_dump(isset(OBJ->prop)); // false
?>
</PHP>

  * Nested property operations:<PHP>
<?php
const OBJ = new stdClass();
OBJ->a = new stdClass();
OBJ->a->b = 7;
var_dump(OBJ->a->b); // int(7)
?>
</PHP>

  * Passing properties by reference:<PHP>
<?php
const OBJ = new stdClass();
OBJ->val = 10;

function modify(&$v) { $v = 42; }
modify(OBJ->val);
var_dump(OBJ->val); // int(42)
?>
</PHP>

==== Semantics ====
  * The constant binding remains immutable.
  * The referenced object may be mutated, consistent with PHP's object behavior.
  * If the constant does not evaluate to an object at runtime, existing behavior (type error/fatal in property access) applies as usual.
  * Class constants holding objects behave identically to global constants; only the object state can change, never the constant binding.

==== Note on Array Constants ====
A related but distinct scenario exists with array constants:

<PHP>
<?php
const ARR = [1, 2, 3];
$ref = ARR;
$ref[0] = 9;
var_dump(ARR); // [1, 2, 3] — original unchanged
?>
</PHP>

Because arrays use copy-on-write semantics, modifying the copy has no effect on the original constant. Similarly:

<PHP>
<?php
const C = [1, 2, 3];
function foo(): array { return C; }
foo()[] = 4;
var_dump(C); // [1, 2, 3] — unmodified, assignment is on a temporary
?>
</PHP>

These dim-write cases involve assignment to temporaries that silently have no effect. Whether such no-effect writes should produce a warning or error is a valid concern but is **out of scope** for this RFC and may be addressed separately (e.g. warning/throwing on "ASSIGN_DIM" when OP1 is not a pointer — i.e. not an indirect, reference, or object — as the operation can never have an effect). See the Future Scope section.

==== Non-goals / Explicitly Unchanged ====
This RFC does NOT change:
  * Rebinding constants:<PHP>
<?php
const OBJ = new stdClass();
OBJ = new stdClass(); // still illegal (parse error)
?>
</PHP>

  * Dimension/array writes or other write-to-temporary semantics:<PHP>
<?php
const ARR = [1,2,3];
ARR[0] = 9; // unchanged (still rejected as before)

const OBJ = new stdClass();
OBJ['x'] = 1; // unchanged (still rejected as before)
?>
</PHP>

==== Implementation Details ====
The compiler change is in "zend_delayed_compile_prop()" in "Zend/zend_compile.c". When the object AST node is a constant used in a write context ("BP_VAR_W", "BP_VAR_RW", "BP_VAR_UNSET", or "BP_VAR_FUNC_ARG"), the compiler fetches the constant at runtime so the subsequent property write opcodes operate on the real object:
* For a global constant ("ZEND_AST_CONST"), it emits a "ZEND_FETCH_CONSTANT" opcode that produces a "VAR" result (via "zend_emit_op") instead of a "TMP" result (via "zend_emit_op_tmp").
* For a class constant ("ZEND_AST_CLASS_CONST"), it emits a "ZEND_FETCH_CLASS_CONSTANT" opcode the same way. As with global constants, the constant is fetched at runtime rather than compile-time evaluated, so the write targets the actual object.

Constants used in read contexts ("BP_VAR_R", "BP_VAR_IS") still produce "TMP" results as before.

==== Why This Brings Value ====
This feature addresses a common surprise: PHP already permits objects in constants (since PHP 8.1), and developers naturally expect to mutate the object's state through the constant reference. The current fatal error is not about constant immutability per se, but rather about an overly broad "temporary write context" restriction in the compiler. Narrowly enabling property writes reduces friction, improves ergonomics, and matches the runtime model of objects without increasing language complexity for other write contexts.

===== Backward Incompatible Changes =====
Enum cases are class constants, so this change affects them. Writing to or unsetting a readonly case property — for example <php>unset(Enum::Case->value)</php> or <php>Enum::Case->value = $x</php> — now raises the standard runtime readonly-property "Error" ("Cannot unset/modify readonly property") instead of the previous compile-time fatal ("Cannot use temporary expression in write context").

This makes enum-case property access consistent with plain variable access (<php>$x = Enum::Case;
unset($x->value);</php>). Enum case properties remain immutable — no value that was previously read-only becomes writable, and dynamic properties on enum cases continue to be rejected.

Apart from this, code that previously terminated with a fatal error for <php>CONST_OBJ->prop = ...</php> will now execute successfully. This is a compatibility improvement — no previously-working code changes behavior.

===== Proposed PHP Version(s) =====
PHP 8.6

===== RFC Impact =====
==== To the Ecosystem ====
  * IDEs / LSPs: Mostly positive; previously-invalid syntax becomes valid.
  * Static analyzers: May need minor updates to remove a false-positive for property writes via constants. Semantics remain straightforward: constant binding is unchanged, object state may change.
  * Formatters / linters: No expected changes beyond accepting the syntax.

==== To Existing Extensions ====
No expected impact. This is a core compilation change around property write access, not an extension API change.

==== To SAPIs ====
No expected impact.

===== Open Issues =====
None currently.

===== Future Scope =====
  * **No-effect dim writes**: A future RFC could explore whether certain no-effect write cases should produce a warning or error. For example, "ASSIGN_DIM" when OP1 is not a "pointer" (indirect, reference, or object) can never have an effect, since the write is to a temporary that is immediately discarded. This is a distinct concern from the property-write issue addressed here.
  * **Other write-to-temporary semantics**: Cases like <php>foo()[0] = 1</php> where the return value is a temporary are similarly out of scope but could be revisited.

===== Voting Choices =====
Voting has not opened yet. The primary vote will require a 2/3 majority for acceptance. The voting period will be specified when voting opens.

<doodle title="Allow object property writes on objects referenced by constants as described in this RFC?" voteType="single" closed="true">
   * Yes
   * No
   * Abstain
</doodle>

===== Patches and Tests =====
Proof of concept implementation:
  * https://github.com/php/php-src/pull/20903

===== Implementation =====
(To be filled after merge)
  - Merged into: PHP 8.6
  - Git commits: ...
  - Manual entry: ...

===== References =====
  * GH-10497: https://github.com/php/php-src/issues/10497
  * PR #20903: https://github.com/php/php-src/pull/20903
  * Internals discussion thread: https://news-web.php.net/php.internals/129157
  * Internals thread (language change notes, incl. class-constant feedback): https://news-web.php.net/php.internals/130606

===== Rejected Features =====
  * Extending the change to dimension/array writes (out of scope for this RFC; involves distinct copy-on-write and temporary semantics)
  * Changing "write-to-temporary" warning/error policy for dims (out of scope; may be addressed in a future RFC)

===== Changelog =====
  * 2026-02-24: Initial draft created.
  * 2026-04-04: v0.2 — Updated after PR review feedback. Added by-ref passing examples, implementation details section, note on array constant behavior per internals feedback, explicit test inventory, updated voting timeline.
  * 2026-06-28: v0.3 — Extended scope to class constants (<php>Cls::CONST->prop</php> and <php>$obj::CONST->prop</php>) per Claude Pache's feedback. Documented the enum readonly-property backward-incompatible change. Restored the Abstain vote option (added by Tim Düsterhus). Restarted the discussion period for the widened scope.

Key changes from v0.1:
- Added by-ref passing examples (confirmed working in tests)
- Added implementation details section explaining the compiler change
- Added "Note on Array Constants" section addressing Ilija's and Tim's feedback about silent no-op dim writes
- Expanded Future Scope with Tim's suggestion about warning on ASSIGN_DIM with non-pointer OP1
- Voting options were revised during later RFC updates; the current vote includes Yes, No, and Abstain
- Removed the placeholder voting close date until voting opens
- Targeted PHP 8.6 explicitly
- Listed all test files in the Patches and Tests section
- Removed Open Issues (the by-ref question is answered, isset/unset is confirmed)
- Added full URLs to References
- Added changelog entry for v0.2