PHP 8.4 Upgrade Notes for Older Codebases: Property Hooks and Asymmetric Visibility in Practice

PHP 8.4 introduced two features that change how you think about class design: property hooks and asymmetric visibility. If you are working on a legacy codebase, the question is not whether to adopt these features immediately but whether they break anything in your existing code and how to use them where they genuinely help.

This article covers the practical impact of PHP 8.4 on older codebases, the upgrade issues you will actually hit, and where the new features solve real problems in legacy PHP projects.

What Property Hooks Actually Do

Property hooks let you define get and set behaviour directly on a property declaration, without writing separate getter and setter methods:

1
2
3
4
5
6
7
8
9
10
11
12

class Temperature
{
    public float $celsius {
        get => $this->fahrenheit !== null ? ($this->fahrenheit - 32) * 5/9 : $this->celsius;
        set(float $value) {
            if ($value < -273.15) {
                throw new \InvalidArgumentException('Below absolute zero');
            }
            $this->celsius = $value;
        }
    }
}

Before property hooks, this required a private backing property plus public getter and setter methods. The hook syntax reduces the boilerplate while keeping the validation and transformation logic visible on the property itself.

Why This Matters for Legacy Code

Legacy PHP codebases fall into two camps regarding property access:

Camp 1: Public properties everywhere. The code uses $object->property directly throughout the application. There are no getters or setters. Changing a property’s behaviour requires finding every access point. This camp benefits from property hooks because you can add validation or transformation to an existing public property without changing any consuming code.

Camp 2: Private properties with getters/setters. The code follows encapsulation practices with $object->getProperty() and $object->setProperty(). This camp does not immediately benefit from property hooks, but when writing new code or refactoring, hooks provide a cleaner alternative.

The important thing is that property hooks do not break either pattern. They are additive. Your existing code continues to work on PHP 8.4 without modification.

What Asymmetric Visibility Does

Asymmetric visibility lets you set different access levels for reading and writing a property:

1
2
3
4
5

class User
{
    public private(set) string $email;
    public protected(set) int $loginCount = 0;
}

The $email property can be read from anywhere but can only be set within the class itself. The $loginCount property can be read from anywhere but only set from within the class or its subclasses.

Replacing Getters in Legacy Code

This feature directly addresses a common pattern in legacy code: a property that should be publicly readable but only settable through controlled methods:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// Before PHP 8.4
class Order
{
    private string $status;

    public function getStatus(): string
    {
        return $this->status;
    }

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

// Reading
$order->getStatus();

// With PHP 8.4
class Order
{
    public private(set) string $status;

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

// Reading
$order->status;

The asymmetric visibility version is shorter and the intent is clearer. But migrating to it requires changing every call site from $order->getStatus() to $order->status, which in a large codebase may not be worth the effort.

Deprecations That Actually Break Legacy Code

While the new features are additive, PHP 8.4 also deprecates and changes several patterns that legacy code commonly uses.

Implicit Nullable Types (Deprecation)

This one affects a lot of legacy code. The pattern:

1

function sendEmail(Mailer $mailer = null)

is deprecated. The correct form is:

1

function sendEmail(?Mailer $mailer = null)

Search your codebase:

1

grep -Prn 'function\s+\w+\s*\([^)]*[A-Z]\w+\s+\$\w+\s*=\s*null' src/ app/

This is tedious but mechanical. Fix every instance. PHP 8.5 will enforce this more aggressively.

Nested Attributes Syntax

PHP 8.4 supports nested attributes, which means attribute argument positions may be parsed differently in edge cases. If your code uses custom attributes with complex arguments, verify the parsing has not changed.

Round Half Away from Zero

round() now defaults to PHP_ROUND_HALF_AWAY_FROM_ZERO mode in certain contexts. If your application has financial calculations that depend on rounding behaviour, verify the results match your expectations:

1
2

echo round(2.5);  // 3 (unchanged)
echo round(-2.5); // -3 (verify this matches your expectations)

Class Constant Typing

PHP 8.3 introduced typed class constants. PHP 8.4 continues to promote their use. While not a breaking change, if your code overrides class constants in child classes with incompatible types, you will see errors:

1
2
3
4
5
6
7
8

class Base {
    const string TYPE = 'base';
}

class Child extends Base {
    const string TYPE = 'child'; // fine
    // const int TYPE = 42;      // error: type mismatch
}

Extension and Library Compatibility

PHPUnit

PHPUnit 11 is required for PHP 8.4 testing with full compatibility. If you are on PHPUnit 9 or 10, upgrade before testing on PHP 8.4. The migration typically involves:

• Updating phpunit.xml schema references
• Replacing deprecated assertion methods
• Adjusting mock creation syntax

Xdebug

Xdebug 3.4+ supports PHP 8.4. Older Xdebug versions will not load. This affects your development environment and any CI pipelines that use Xdebug for code coverage.

OPcache

OPcache handles the new syntax features transparently. No configuration changes are needed, but clear the OPcache after upgrading PHP to avoid stale bytecache.

When to Adopt the New Features in Legacy Code

Adopt Property Hooks When…

• You are adding validation to a public property that is accessed directly throughout the codebase. Hooks let you add the validation without changing any consuming code.
• You are creating new value objects or DTOs. Hooks provide cleaner construction and validation than separate methods.
• You are wrapping database column values with transformation logic (unit conversion, formatting, lazy loading).

Avoid Property Hooks When…

• Your team is not yet on PHP 8.4 across all environments. Using hooks means the code cannot run on older PHP versions.
• The property access pattern is already well-served by existing getters and setters. Rewriting working code for syntax preference is not a productive use of time.
• The hook logic is complex. If the get or set behaviour is more than a few lines, a dedicated method is more readable.

Adopt Asymmetric Visibility When…

• You are designing new API surfaces and want to make the read/write contract explicit in the property declaration.
• You are replacing simple getter-only patterns where the getter method adds no logic beyond returning the property value.

Avoid Asymmetric Visibility When…

• Migrating would require changing hundreds of $object->getProperty() call sites. The benefit does not justify the churn.
• Your codebase needs to support PHP 8.3 or earlier. The syntax is a parse error on older versions.

Practical Upgrade Steps

1. Set up PHP 8.4 in your CI pipeline as an additional matrix entry. Run tests on both your current PHP version and 8.4.
2. Fix deprecation notices first. These are the items that will become errors in 8.5 or 9.0.
3. Update Composer dependencies. Run composer why-not php 8.4 to find blocking packages.
4. Update PHPUnit and static analysis tools. These need PHP 8.4-compatible versions to test correctly.
5. Fix test failures. Most will be type-related or deprecation-related.
6. Deploy to staging. Run your critical paths manually.
7. Deploy to production with monitoring.

Do not try to adopt the new features and fix compatibility issues in the same pass. Upgrade first, adopt features later.

The Bigger Picture

PHP 8.4 continues the language’s shift toward stricter typing, explicit declarations, and reduced magic. Each version makes the implicit more explicit: nullable types must be declared, return types must be specified, properties must be declared. For legacy codebases, this means each upgrade requires a round of cleanup.

The upside is that cleaned-up code is more maintainable. Explicit nullable types catch bugs. Declared properties prevent typos. Return types enable better IDE support and static analysis. The upgrade work is not just compliance; it improves the codebase.

For the broader legacy upgrade strategy, the Working with Legacy PHP Codebases article covers the systematic approach, and the Model chapter explains the domain layer patterns where property hooks and asymmetric visibility add the most value.

The Modernising Zend Framework Applications guide covers the framework-level modernisation that often accompanies PHP version upgrades.