Upgrading

The bundle versions in lockstep with opcua-client and opcua-session-manager. A v4.4.x bundle uses ^4.4.x of both upstream packages.

Composer constraint

In your project's composer.json:

"php-opcua/symfony-opcua": "^4.4"

Caret allows minor/patch updates within the 4.x train. Major bumps (4 → 5) signal an intentional breaking change.

Reading the CHANGELOG

Three files matter for an upgrade:

A bundle entry references both upstream entries with the "downstream impact" callouts, so reading just the bundle one usually suffices.

Symfony version matrix

Note: the Symfony floor was raised from 7.3 to 7.4 in the current release. Symfony 7.3 reached end of life and no longer receives security fixes (PKSA-z7t6-zt6p-wtng), so it was dropped from the constraint and CI. Symfony 6.4 LTS is also not supported on the current release — stay on ^4.2 if you need 6.4 LTS compatibility.

PHP 8.2 is the minimum across the entire 4.x line. PHP 8.3 / 8.4 work transparently.

v4.3 → v4.4 — what to do

For most apps: one step. v4.4 is a pure additive release — the wire protocol, the cache codec, the config schema, and the bundle services are all unchanged. Three new module surfaces ride into the client your code already uses: HistoryUpdate (9 methods, Part 11), File Transfer (10 methods, Part 5), Aggregate (2 methods, Part 13).

Bump and clear container cache

composer require php-opcua/symfony-opcua:^4.4
php bin/console cache:clear

No persistent cache flush needed — the OPC UA wire-cache codec did not change between v4.3 and v4.4. v4.3-era entries decode cleanly.

Use the new methods (optional)

The bundle exposes the client unchanged through autowiring:

use PhpOpcua\Client\OpcUaClientInterface;
use PhpOpcua\Client\Types\BuiltinType;
use PhpOpcua\Client\Types\DataValue;

public function backfill(OpcUaClientInterface $client): Response
{
    // v4.4 — backfill historical samples
    $statuses = $client->historyInsertData('ns=2;s=Sensors/Temp', [
        DataValue::of(22.1, BuiltinType::Double)->withSourceTimestamp($t1),
        DataValue::of(22.3, BuiltinType::Double)->withSourceTimestamp($t2),
    ]);
    // ...
}

If you run the bundled session manager (any value other than null for session_manager.socket_path), upgrade the daemon first. A 4.4 application talking to a 4.3 daemon raises BadMethodCallException from the IPC layer when the application calls one of the 21 new methods — the older daemon's describe response does not advertise them.

v4.2 → v4.3 — what to do

For most apps: two steps.

1. Bump and update

composer require php-opcua/symfony-opcua:^4.3
php bin/console cache:clear

The cache clear is for Symfony's container cache; nothing OPC UA-specific yet.

2. Flush the persistent cache pool

The OPC UA wire-cache codec was hardened — unserialize() is out, JSON behind an allowlist is in. Pre-v4.3 cached entries are discarded on first access.

If you use a Redis / database / file pool for the bundle's cache, flush it explicitly to avoid a brief cold-cache window:

php bin/console cache:pool:clear cache.app

Or your specific pool name (cache.system, cache.redis, etc.).

That's the whole upgrade. Everything else (NodeManagement in defaults, ServiceFault decoding, daemon socket-permission fix, …) is transparent.

Symfony Flex recipe drift

If you forked the project's Flex recipe, compare against the current recipe shape:

composer recipes:install php-opcua/symfony-opcua --reset

--reset overwrites the recipe-managed files; review the diff before committing.

Removing deprecated config keys

The bundle has been additive-only through the 4.x train — no config keys have been removed. Your existing config/packages/php_opcua_symfony_opcua.yaml works unchanged on each new minor.

If a future major (5.x) does deprecate keys, the corresponding entry in symfony-opcua/CHANGELOG.md will spell out the migration path.

After upgrade

A short sanity check:

php bin/console debug:config php_opcua_symfony_opcua | head -40
php bin/console debug:autowiring opcua
php bin/console opcua:session --help

All three should succeed. If the third one fails, the bundle's console command isn't registered — most often a stale var/cache/ (run cache:clear).

Long-running workers — restart

After the upgrade, restart any long-running workers:

sudo systemctl restart opcua-session-manager
sudo systemctl reload-or-restart 'messenger@*'

Workers cache the autoload index at boot. Without a restart they keep running the pre-upgrade code until the next deploy.

What "supported" means

The bundle's CI matrix runs against:

• PHP 8.2, 8.3, 8.4, 8.5 (release candidates)
• Symfony 7.4, 7.x current, 8.x current
• Ubuntu, macOS, Windows

A version combination outside this matrix may work but isn't guaranteed. File issues at github.com/php-opcua/symfony-opcua/issues.

Where to read next

• Bundle YAML — the full config tree.
• Caching — the v4.3 cache-codec details.