PHP RFC: Harmonise "untyped" and "typed" properties

• Version: 0.3
• Date: 2023-11-16
• Author: Rowan Tommins imsop@php.net
• Status: Draft
• First Published at: http://wiki.php.net/rfc/mixed_vs_untyped_properties

This RFC proposes to remove the distinction between “typed” and “untyped” properties, by treating any property with no type information as though it was declared mixed. This is primarily aimed to reduce confusion around different states, error messages, and behaviours; to do so, it makes the language stricter in some circumstances, and changes the error message in others.

PHP currently has three primary ways of adding properties to an object:

1. Dynamically. The property is created automatically on a specific instance when it is first assigned to, and can be deleted completely using unset.
2. Declared, with optional visibility. The property is part of the class definition, and allocated on every instance, even if it is never assigned. The behaviour of unset is complex, hiding but not fully deleting the property.
3. Declared with a type. In addition to being allocated on every instance, the property is covered by extra guards on assignment to guarantee its type. If it is never assigned a value, or passed to unset, it is assigned a special “uninitialized” state.

The different behaviours of these properties are largely a result of the history of the language, rather than a consistent design. In particular, with the addition of the ''mixed'' type, it would seem logical for private $foo; to be short-hand for private mixed $foo;, since no type-guards are needed; but this is not currently the case, due to the different handling of initial states and unset.

The three types of property vary in their initial state, and in their state after calling unset, as can be seen in these three demos, which run the same code with the three types of property: dynamic property, untyped property, typed property.

The states can be summarised in this table:

Where:

• “Defined” is straight-forward: the property exists, and can be read subject to visibility constraints.
• “Undefined” means the property does not exist on the object. It does not show up in views such as var_dump. Attempting to read it currently produces a Warning, but will produce an Error in PHP 9.0.
• “Uninitialized” is a special state introduced as part of the introduction of typed properties to handle cases where neither null nor an inline initializer can be used. The property is still treated as present on the instance, but with a special value/state; in the example, the var_dump output shows this as [“foo”:“A”:private] => uninitialized(mixed)

The state marked “?”, for untyped properties after unset, is a complex one:

• In output such as var_dump, it is not listed, as with “undefined”
• *Reading* it gives a Warning (and future Error) of “Undefined property”
• Reading or writing still obeys the original visibility constraint - reading an unset private property from outside the class gives “Cannot access private property”, not “Undefined property”
• Writing to it does not give the deprecation notice for “Creation of dynamic property”; instead, the original declaration (including any visibility specifier) is silently re-used

Dynamic properties will be prohibited on most classes in 9.0, giving the following if we don't make other changes:

The behaviour of unset will be standardised for all declared properties, regardless of whether a type was included in the declaration.

For an untyped property, this means:

• The property will show up in var_dump and similar output, with a special type of “uninitialized”
• The error given when attempting to access the variable will refer to it as “uninitialized” rather than “undefined”

For typed properties, the current error message reads:

Typed property %s::%s must not be accessed before initialization

This will be changed, for both typed and untyped properties, to:

Property %s::%s must not be accessed before initialization

The remaining difference is the initial value of the property. We could in principle resolve this in two ways:

1. Initialize any property to null if that is a valid value, and it has no other initializer
2. Never initialize a property to null unless that initial value is explicitly specified

Option 1 has the advantage of not causing errors in any currently valid code; but it goes against the general trend of making the language stricter and more explicit.

Option 2 is a non-trivial breaking change, for which a deprecation period will be needed. The proposal is therefore to add the following deprecation notice in PHP 8.next:

Accessing property %s::%s before initialization is deprecated

The calling code will continue to see the value of the property as null. Assigning a value, either in the declaration (private $foo = null;) or in procedural code ($this->foo = null;) will suppress this notice for all further accesses.

In PHP 9.0, untyped properties will start in the uninitialized state unless an initial value is provided, and attempting to access them will give the error shown in the previous section.

Untyped properties will no longer have an implicit initial value of null. To retain the existing behaviour, an explicit initializer must be added:

// Before
class Example {
    public $foo;
}
 
// After
class Example {
    public $foo = null;
}

In PHP 8.next:

• Add deprecation notice for untyped properties accessed without initialization

In PHP 9.0:

• All declared properties will start “uninitialized”, rather than implicitly initialized to null, unless an explicit initial value is given
• All declared properties will become “uninitialized” when passed to unset
• The message for accessing uninitialized properties will be changed to remove reference to “typed properties”

No new functionality is added in the final proposed state. Indeed, some edge cases that currently need to be handled may be removed.

• Readonly properties were restricted to typed properties, citing the default null initializer as rationale; should this restriction be explicitly relaxed as part of this RFC?
• Are there other differences between typed and untyped properties to address?
• Can uninitialized untyped properties be implemented efficiently during the deprecation period?
• Is the removal of implicit null initializers controversial, and are there alternative approaches?

• The behaviour of dynamic properties, that is those not defined at all in the class definition, is not changed by this RFC.
• The interaction of unset and magic __get is the same for untyped and typed properties, so will not be affected by harmonising them. Specifically, following unset($foo->bar); a subsequent read of $foo->bar will call $foo->__get('bar') if available: https://3v4l.org/D16Tv

None identified at present.

TODO: Either a straight vote for the whole proposal, or separate proposals for initial state and unset behaviour, depending on initial feedback.

TODO

Related RFCs already accepted:

• Original definition of typed properties
• Addition of ''mixed'' type
• Promotion to error for "undefined" properties
• Deprecating "dynamic" properties

Previous mailing list threads touching on this issue:

• Discussion thread for "Undefined Property Error Promotion" RFC
• Vote thread for that RFC

None yet.