PHP RFC: Deprecate dynamic properties

• Date: 2021-08-23
• Author: Nikita Popov nikic@php.net
• Status: Under Discussion
• Target Version: PHP 8.2
• Implementation: https://github.com/php/php-src/pull/7390

When writing to a property that has not been declared, PHP will silently create a dynamic property instead. In modern code, this is rarely done intentionally. This RFC proposes to deprecate and later remove the creation of dynamic properties, unless the class explicitly allows dynamic properties. stdClass and __get/__set are not affected by this change.

class User {
    public $name;
}
 
$user = new User;
 
// Assigns declared property User::$name.
$user->name = "foo";
 
// Oops, a typo:
$user->nane = "foo";
// PHP <= 8.1: Silently creates dynamic $user->nane property.
// PHP    8.2: Raises deprecation warning, still creates dynamic property.
// PHP    9.0: Throws Error exception.

“Dynamic property” here refers to a property that has not been declared in the class. It has no relation to the access style (e.g. $user->{'na' . 'me'} is still an access to a declared property).

The creation of dynamic properties on classes that aren't marked with the #[AllowDynamicProperties] attribute is deprecated in PHP 8.2 and becomes an Error exception in PHP 9.0. All used properties should be declared in the class declaration.

class Foo {}
$foo = new Foo;
 
// Deprecated: Creation of dynamic property Foo::$bar is deprecated
$foo->bar = 1;
 
// No deprecation warning: Dynamic property already exists.
$foo->bar = 2;

Classes marked with #[AllowDynamicProperties] as well as their children can continue using dynamic properties without deprecation or removal. The only bundled class marked as #[AllowDynamicProperties] is stdClass.

$obj = (object) []; // = new stdClass;
 
// No deprecation warning
$obj->foo = 1;
 
#[AllowDynamicProperties]
class Test {}
class Test2 extends Test {}
 
// No deprecation warning
$obj = new Test;
$obj->bar = 1;
 
// No deprecation warning
$obj = new Test2;
$obj->bar = 1;

It should be noted that properties accessed through __get()/__set() are not considered as “dynamic properties”. The following example does not generate any deprecation warnings:

class ArrayLikeObject {
    private array $data = [];
    public function &__get($name) { return $this->data[$name]; }
    public function __isset($name, $value) { return isset($this->data[$name]; }
    public function __set($name, $value) { $this->data[$name] = $value; }
    public function __unset($name) { unset($this->data[$name]; }
}
 
$obj = new ArrayLikeObject;
 
// Calls ArrayLikeObject::__set(), no deprecation warning.
$obj->foo = 1;

Removing support for dynamic properties constitutes a significant backwards compatibility break. While modern PHP code consistently declares used properties, this is not necessarily the case for legacy code. When encountered with a dynamic property deprecation warning, there are a number of things that can be done to avoid it.

The simplest and most common would be to simply add the property declaration:

class Test {
    public $value; // <-- Add property declaration.
 
    public function __construct($value) {
        $this->value = $value;
    }
}

For classes that intentionally don't have a fixed set of properties, it's possible to either implement magic __get()/__set() or mark the class using the #[AllowDynamicProperties] attribute. Marking a class with #[AllowDynamicProperties] is fully backwards-compatible with earlier PHP version, because prior to PHP 8.0 this would be interpreted as a comment, and the use non-existent classes as attributes is not an error.

In some cases it is desirable to associate information with objects that you do not own. Previously, it was possible to add a dynamic property for this purpose. Instead, a WeakMap should be used to store the information in a non-intrusive way:

class Test {
    private WeakMap $extraInfo;
 
    public function addExtraInfo(object $obj) {
        // Instead of:
        $obj->extraInfo = ...;
        // Use:
        $this->extraInfo[$obj] = ...;
    }
}

In rare cases, dynamic properties are used for lazy initialization. For example Symfony's Constraint::$groups property is not declared and then dynamically created inside __get(). This use-case can be accommodated by declaring the property, but then unsetting it in the constructor:

abstract class Constraint {
    public $groups;
 
    public function __construct() {
        unset($this->groups);
    }
 
    public function __get($name) {
        // Will get called on first access, but once initialized.
        $this->groups = ...;
    }
}

A declared property that has been unset remains a declared property, and will not result in a dynamic property when it is reinitialized.

This RFC offers #[AllowDynamicProperties] as a way to opt-in to the use of dynamic properties. A previous version of this proposal instead suggested to extend from stdClass, and make stdClass the only class with first-class dynamic property support.

The difference between these approaches is in the end goal: #[AllowDynamicProperties] requires making classes that rely on dynamic properties explicit and prevents accidental use of dynamic properties. This is a big win for the ecosystem, but it does not have much effect on the overall complexity of the language or implementation, as dynamic properties still need to be supported on arbitrary classes. Requiring an extension of stdClass would allow us to actually remove the “dynamic properties” concept from the language in the future: stdClass would effectively just provide very optimized implementations of __get() and __set().

While completely removing dynamic properties is an worthwhile end goal, we also need to acknowledge that dynamic properties have played an important historical role in PHP, and legacy codebases in particular may be making heavy use of them. While adding an attribute provides a straightforward upgrade path, extending stdClass may not always be easily possible due to lack of multiple inheritance support. For this reason, this RFC pursues the more conservative attribute-based approach.

We may still wish to remove dynamic properties entirely at some later point. Having the #[AllowDynamicProperties] attribute will make it much easier to evaluate such a move, as it will be easier to analyze how much and in what way dynamic properties are used in the ecosystem.

The Locked classes RFC took an alternative approach to this problem space: Rather than deprecating/removing dynamic properties and providing an opt-in for specific classes, it instead allowed marking specific classes as locked in order to forbid creation of dynamic properties on them.

I don't believe that this is the right strategy, because in contemporary code, classes being “locked” is the default state, while classes that require dynamic properties are a rare exception. Additionally, this requires that class owners (which may be 3rd party packages) consistently add the “locked” keyword to be effective.

An alternative that has been discussed in the context of the language evolution proposal is to instead disallow the use of dynamic properties in a file through a declare directive (whether that be a fine-grained option or an “edition” mechanism). This does not require the cooperation of 3rd-party libraries.

However, based on the discussion on the language evolution proposal, this would only delay the time where disallowed dynamic properties become the default and only behavior, as there was a strong consensus that diverging language behavior should not be maintained indefinitely. Dynamic properties would ultimately still get deprecated and removed.

Yes/No.