PHP 8.4: Property Hooks, Asymmetric Visibility, and Lazy Objects Explained

PHP 8.4 introduces three powerful features that change how you design and interact with objects: property hooks, asymmetric visibility, and lazy objects. These features address long-standing pain points in PHP development, such as boilerplate getter/setter methods, inconsistent access control, and unnecessary object initialization. Property hooks allow you to add logic to property access without breaking the public API, making your code more maintainable and expressive. Asymmetric visibility gives you fine-grained control over who can read vs. write a property, eliminating the need for separate getter/setter methods with different visibility. Lazy objects defer the creation and initialization of objects until they are actually needed, which can significantly improve performance in applications with many optional dependencies or heavy objects. In this tutorial, you'll learn each feature with real-world examples, best practices, and debugging tips. By the end, you'll be able to refactor legacy code and design new systems that are cleaner, faster, and more secure.

Understanding Property Hooks

Property hooks allow you to define custom behavior when a property is read or written, without breaking the public API. Before PHP 8.4, you had to use getter and setter methods, which cluttered the interface. Now you can attach hooks directly to properties. The syntax uses 'get' and 'set' keywords after the property declaration. The get hook runs when the property is read, and the set hook runs when it's written. Inside the set hook, you can use the special variable '$value' to refer to the incoming value. You can also omit the set hook to make a property read-only (but still writable internally if you use asymmetric visibility). Property hooks are especially useful for validation, logging, lazy loading, and computed properties. They work with typed properties and can be combined with asymmetric visibility. Note that hooks cannot be used with static properties or properties in interfaces (yet).

<?php

class User {
    public string $name {
        get => ucfirst($this->name);
        set => strtolower($value);
    }

    public function __construct(string $name) {
        $this->name = $name;
    }
}

$user = new User('john');
echo $user->name; // Outputs: John
$user->name = 'JANE';
echo $user->name; // Outputs: Jane

Asymmetric Visibility: Read vs. Write Access

Asymmetric visibility allows you to specify different access levels for reading and writing a property. The syntax is 'public private(set)' meaning anyone can read, but only the class itself can write. You can also use 'protected private(set)' or 'public protected(set)'. This is useful for value objects or DTOs where you want to expose data but prevent external modification. It replaces the common pattern of having a public getter and a private setter. Asymmetric visibility can be combined with readonly properties (readonly implies public private(set) by default). Note that asymmetric visibility only affects the property's visibility; you can still have hooks that run on set. Also, the write visibility cannot be wider than the read visibility (e.g., you cannot have private read and public write).

<?php

class Order {
    public private(set) string $status = 'pending';

    public function approve(): void {
        $this->status = 'approved';
    }
}

$order = new Order();
echo $order->status; // Outputs: pending
// $order->status = 'shipped'; // Error: Cannot modify readonly property
$order->approve();
echo $order->status; // Outputs: approved

Lazy Objects: Deferred Initialization

Lazy objects are objects that are not fully initialized until a property or method is accessed. PHP 8.4 introduces two types: lazy ghosts and lazy proxies. A lazy ghost is an object that is initially empty and becomes the real object upon first access. A lazy proxy is a separate proxy object that forwards calls to the real object after initialization. To create a lazy ghost, use ReflectionClass::newLazyGhost with a callable initializer. The initializer receives the object instance and should set its properties. Lazy objects are ideal for expensive-to-create objects like database connections, API clients, or large configuration objects. They can significantly reduce memory usage and startup time. However, they add a small overhead on first access. Use them judiciously.

<?php

class DatabaseConnection {
    public function __construct(private string $dsn) {
        // Simulate heavy initialization
        sleep(1);
        echo "Connected to $dsn\n";
    }

    public function query(string $sql): string {
        return "Result for: $sql";
    }
}

$reflector = new ReflectionClass(DatabaseConnection::class);
$connection = $reflector->newLazyGhost(function (DatabaseConnection $object) {
    // Initializer: called when first accessed
    $object->__construct('mysql:host=localhost;dbname=test');
});

echo "Object created, but not yet initialized.\n";
sleep(2);
echo $connection->query('SELECT 1'); // Triggers initialization

Combining Features: Property Hooks with Asymmetric Visibility

You can combine property hooks and asymmetric visibility for powerful effects. For example, you might have a property that is publicly readable but only privately settable, and you want to validate the value on set. The syntax is straightforward: declare the asymmetric visibility first, then the hook. The set hook will run when the property is written internally. This combination is perfect for value objects that need validation. It also allows you to expose computed properties that are derived from other data. Remember that the get hook can also be used to transform the value on read. This pattern reduces the need for separate getter/setter methods and keeps the logic co-located with the property.

<?php

class Temperature {
    public private(set) float $celsius {
        set {
            if ($value < -273.15) {
                throw new InvalidArgumentException('Temperature below absolute zero');
            }
            $this->celsius = $value;
        }
    }

    public float $fahrenheit {
        get => $this->celsius * 9 / 5 + 32;
    }

    public function __construct(float $celsius) {
        $this->celsius = $celsius;
    }
}

$temp = new Temperature(25);
echo $temp->celsius; // 25
echo $temp->fahrenheit; // 77
// $temp->celsius = 30; // Error: Cannot modify readonly property

Lazy Objects and Property Hooks: A Perfect Match

Lazy objects can benefit from property hooks to add logging or validation when properties are accessed. For example, you might have a lazy-loaded configuration object that logs every access for debugging. You can define property hooks on the class that will be used after initialization. However, note that hooks are not called during the initialization of a lazy ghost (the initializer sets properties directly). After initialization, hooks work normally. This allows you to have lazy objects with smart properties. Another use case is to make a property lazily computed: you can use a get hook that triggers initialization of a related lazy object. This pattern is powerful for building complex object graphs that are loaded on demand.

<?php

class Config {
    public private(set) array $data {
        get {
            echo "Accessing config data\n";
            return $this->data;
        }
    }

    public function __construct() {
        // Heavy initialization
        $this->data = ['db' => 'mysql', 'cache' => 'redis'];
    }
}

$reflector = new ReflectionClass(Config::class);
$config = $reflector->newLazyGhost(function (Config $object) {
    $object->__construct();
});

echo "Before access\n";
$data = $config->data; // Triggers initialization and hook
echo "After access\n";

Migration Guide: Refactoring Legacy Code

Migrating existing code to use PHP 8.4 features should be done incrementally. Start by identifying properties that have getter/setter methods. Replace them with property hooks, ensuring backward compatibility. For asymmetric visibility, look for properties that are exposed via public getters but have private setters. Replace with public private(set). For lazy objects, identify heavy objects that are created early but used rarely. Use lazy ghosts or proxies to defer initialization. Always run your test suite after changes. Note that property hooks cannot be added to interfaces yet, so you may need to keep interfaces unchanged. Also, be careful with serialization: lazy objects may not serialize correctly before initialization. Consider using the 'lazy' keyword in docblocks to document the behavior.

<?php

// Before PHP 8.4
class User {
    private string $name;

    public function getName(): string {
        return ucfirst($this->name);
    }

    public function setName(string $name): void {
        $this->name = strtolower($name);
    }
}

// After PHP 8.4
class User {
    public string $name {
        get => ucfirst($this->name);
        set => strtolower($value);
    }
}