Constructor Property Promotion

Constructor property promotion is a syntactic shorthand introduced in PHP 8.0 that merges class property declaration, constructor parameter definition, and property assignment into a single construct. By prefixing a constructor parameter with a visibility modifier (public, protected, or private), the PHP engine automatically declares a corresponding class property and assigns the passed argument to it during object instantiation.

Syntax Mechanics

To trigger property promotion, the parameter within the __construct method signature must include a visibility modifier.

Traditional Syntax:

class Point {
    public float $x;
    public float $y;
    public float $z;

    public function __construct(float $x, float $y, float $z = 0.0) {
        $this->x = $x;
        $this->y = $y;
        $this->z = $z;
    }
}

Promoted Syntax:

class Point {
    public function __construct(
        public float $x,
        public float $y,
        public float $z = 0.0,
    ) {}
}

When the PHP engine parses the promoted syntax, it transforms it into the traditional AST (Abstract Syntax Tree) equivalent. The property assignment occurs immediately before the execution of any code defined within the constructor’s body block.

Technical Rules and Constraints

1. Allowed Contexts Property promotion is strictly limited to the __construct method. It cannot be used in standard methods, static methods, abstract constructors, or interface declarations.

2. Mixing Promoted and Non-Promoted Parameters You can mix promoted properties with standard constructor parameters. Standard parameters lack a visibility modifier and will not generate a class property.

class Configuration {
    public function __construct(
        public string $environment,
        array $rawOptions // Non-promoted parameter
    ) {
        // $this->environment is already assigned.
        // $rawOptions must be handled manually.
    }
}

3. Duplication Restrictions You cannot declare a standard class property and a promoted property with the same identifier. Doing so results in a fatal error.

class User {
    public string $name;

    public function __construct(
        public string $name // Fatal error: Cannot redeclare property
    ) {}
}

4. Default Values Promoted parameters can define default values. However, this default value applies strictly to the constructor parameter. The generated class property does not receive a default value at the class definition level; instead, the default value is assigned to the property during instantiation if no argument is provided.

5. Type Restrictions

• callable: Promoted properties cannot be typed as callable. Because callable is not a valid property type in PHP (due to context-dependent scope issues), the engine rejects it during promotion.
• Variadic Parameters: Variadic parameters (e.g., ...$args) cannot be promoted.
• Untyped Parameters: Omitting the type leaves the property completely untyped. This is distinct from an explicit mixed type. For example, in Reflection, an untyped property returns null for getType(), whereas an explicit mixed type returns a ReflectionNamedType.

6. Readonly Properties As of PHP 8.1, the readonly modifier can be used to promote a property. It must strictly be accompanied by a visibility modifier (public, protected, or private). Furthermore, due to PHP’s language constraints on readonly properties, promoted readonly properties must be explicitly typed. Attempting to promote an untyped readonly property (e.g., public readonly $id) will result in a fatal error.

class DataTransferObject {
    public function __construct(
        public readonly string $id,
        private readonly array $payload
    ) {}
}

Attribute Resolution

When applying PHP Attributes to a promoted property, the engine blindly applies the attribute to both the generated class property and the constructor parameter. PHP does not validate attribute targets during the initial parsing phase. If an attribute is strictly restricted to a specific target (e.g., Attribute::TARGET_PROPERTY), it will still be attached to the constructor parameter. Consequently, invoking ReflectionAttribute::newInstance() on that parameter will throw a fatal error (Error: Attribute "..." cannot target parameter).

Master PHP with Deep Grasping Methodology!

Learn More