llms-full.txt

# OPC UA PHP Client Session Manager — Full Documentation

> Daemon-based session manager for opcua-client. Keeps OPC UA connections alive across PHP requests via a ReactPHP daemon and a local IPC channel (Unix-domain socket on Linux/macOS, TCP loopback on Windows — auto-selected). ManagedClient is a drop-in replacement for Client — same OpcUaClientInterface, persistent sessions.

Package: php-opcua/opcua-session-manager
Repository: https://github.com/php-opcua/opcua-session-manager
Packagist: https://packagist.org/packages/php-opcua/opcua-session-manager
License: MIT
PHP: >= 8.2
Dependencies: php-opcua/opcua-client ^4.5, react/event-loop ^1.5, react/socket ^1.16, psr/log ^3.0, psr/simple-cache ^3.0

---

## 1. Overview

PHP's request/response model destroys all state at the end of every request. OPC UA requires a 5-step handshake (TCP → Hello/Ack → OpenSecureChannel → CreateSession → ActivateSession) costing 50–200ms. This package solves the problem with a long-running ReactPHP daemon that holds sessions in memory, communicating via local IPC (Unix-domain socket on Linux/macOS, TCP loopback on Windows — auto-selected).

### Architecture

```
PHP Request (short-lived) ←→ Unix Socket IPC ←→ SessionManagerDaemon (ReactPHP) ←→ TCP ←→ OPC UA Server
```

Components:
- ManagedClient: drop-in OpcUaClientInterface proxy, translates method calls to IPC
- SessionManagerDaemon: ReactPHP event loop, Unix socket server, cleanup timer, signal handlers, auto-publish, auto-connect
- AutoPublisher: per-session auto-publish cycle with self-rescheduling timers, ack management, recovery
- CommandHandler: IPC dispatch, method whitelist (51 methods), credential sanitization, auto-connect sessions, `registerParamDeserializer()` extension point
- TypeSerializer: bidirectional JSON serialization for all OPC UA types and v4.0.0 DTOs
- SessionStore: in-memory session registry with expiration

### Installation

```
composer require php-opcua/opcua-session-manager
```

### Quick Start

```bash
php bin/opcua-session-manager
```

```php
use PhpOpcua\SessionManager\Client\ManagedClient;

$client = new ManagedClient();
$client->connect('opc.tcp://localhost:4840');

$value = $client->read('i=2259');
echo $value->getValue();

$client->disconnect();
```

---

## 2. Daemon

### Starting

```bash
php bin/opcua-session-manager [options]
```

### CLI Options

| Option | Default | Description |
|--------|---------|-------------|
| `--socket` | `/tmp/opcua-session-manager.sock` | Unix socket path |
| `--timeout` | `600` | Session inactivity timeout (seconds) |
| `--cleanup-interval` | `30` | Cleanup timer interval (seconds) |
| `--auth-token` | none | IPC auth token (visible in ps) |
| `--auth-token-file` | none | Read auth token from file |
| `--max-sessions` | `100` | Max concurrent sessions |
| `--socket-mode` | `0600` | Socket file permissions |
| `--allowed-cert-dirs` | none | Comma-separated cert directories |

Auth priority: OPCUA_AUTH_TOKEN env > --auth-token-file > --auth-token

### Security

- IPC authentication: timing-safe hash_equals()
- Socket permissions: 0600 default
- Method whitelist: 51 allowed operations (covering Read/Write/Browse/Call/Subscription/History — including v4.4.0 HistoryUpdate, Aggregate, FileTransfer surface — Discovery, NodeManagement), setters blocked
- Credential stripping: passwords/key paths removed after connection
- Input limit: 1MB max request
- Connection limits: 30s timeout, 50 max concurrent
- Error sanitization: messages truncated, file paths stripped
- PID lock: prevents duplicate instances

### Running as Service

systemd or Supervisor supported. See docs/daemon/running-as-a-service.md for examples.

### Auto-Publish

When `autoPublish: true` and an `EventDispatcherInterface` is provided, the daemon automatically calls `publish()` for sessions with active subscriptions. The client's internal `dispatchPublishEvents()` fires PSR-14 events (`DataChangeReceived`, `EventNotificationReceived`, `AlarmActivated`, `SubscriptionKeepAlive`, etc.) — no manual publish loop needed.

```php
$daemon = new SessionManagerDaemon(
    socketPath: '/tmp/opcua.sock',
    clientEventDispatcher: $dispatcher,
    autoPublish: true,
);
$daemon->run();
```

Acknowledgements are tracked internally. Self-rescheduling timers adapt to each session's minimum publishing interval. When `moreNotifications` is true, the next publish fires with 10ms delay. On connection errors, recovery is attempted automatically. After 5 consecutive generic errors, auto-publish stops for that session.

Manual `publish()` via IPC is blocked while auto-publish is active (returns `auto_publish_active` error).

### Auto-Connect

Pre-configure connections to auto-connect at daemon startup:

```php
$daemon->autoConnect([
    'plc-1' => [
        'endpoint' => 'opc.tcp://192.168.1.10:4840',
        'config' => ['username' => 'op', 'password' => 'secret', 'opcuaTimeout' => 3.0],
        'subscriptions' => [
            [
                'publishing_interval' => 500.0,
                'max_keep_alive_count' => 5,
                'monitored_items' => [
                    ['node_id' => 'ns=2;s=Temperature', 'client_handle' => 1],
                ],
                'event_monitored_items' => [
                    ['node_id' => 'i=2253', 'client_handle' => 10],
                ],
            ],
        ],
    ],
]);
```

Connections are established on the first event loop tick. Failed connections are logged but don't prevent the daemon from starting.

---

## 3. ManagedClient API

### Constructor

```php
$client = new ManagedClient(
    socketPath: '/tmp/opcua-session-manager.sock',
    timeout: 30.0,
    authToken: 'my-secret',
);
```

### Configuration

```php
$client->setTimeout(10.0);
$client->setAutoRetry(3);
$client->setBatchSize(50);
$client->setDefaultBrowseMaxDepth(20);
$client->setSecurityPolicy(SecurityPolicy::Basic256Sha256); // or EccNistP256, EccNistP384, EccBrainpoolP256r1, EccBrainpoolP384r1
$client->setSecurityMode(SecurityMode::SignAndEncrypt);
$client->setClientCertificate('/certs/client.pem', '/certs/client.key', '/certs/ca.pem'); // optional for ECC — auto-generated
$client->setUserCredentials('operator', 'secret');
$client->setUserCertificate('/certs/user.pem', '/certs/user.key');
$client->setLogger($logger);
$client->setCache($cache);
```

### Connection

```php
$client->connect('opc.tcp://localhost:4840');
$client->isConnected();
$client->getConnectionState();    // ConnectionState enum
$client->reconnect();
$client->disconnect();
$client->getSessionId();          // session ID for persistence
```

### String NodeIds

All methods accept NodeId|string. Strings parsed via NodeId::parse().

```php
$client->read('i=2259');
$client->browse('ns=2;s=MyFolder');
$client->write('ns=2;i=1001', 42, BuiltinType::Int32);
```

### Browse

```php
$refs = $client->browse('i=85', nodeClasses: [NodeClass::Object]);
$result = $client->browseWithContinuation('i=85');  // BrowseResultSet
$result = $client->browseNext($continuationPoint);   // BrowseResultSet
$refs = $client->browseAll('i=85', useCache: false);
$tree = $client->browseRecursive('i=85', maxDepth: 3);
```

ReferenceDescription properties: referenceTypeId, isForward, nodeId, browseName, displayName, nodeClass, typeDefinition
BrowseNode: reference (ReferenceDescription), getChildren(), hasChildren()

### Path Resolution

```php
$nodeId = $client->resolveNodeId('/Objects/Server/ServerStatus');

$results = $client->translateBrowsePaths()
    ->from('i=85')->path('Server', 'ServerStatus')
    ->execute();
// Returns BrowsePathResult[]
```

### Read / Write

```php
$dv = $client->read('i=2259');
$dv->getValue();       // unwrapped scalar
$dv->statusCode;       // int
$dv->sourceTimestamp;   // ?DateTimeImmutable

$results = $client->readMulti()
    ->node('i=2259')->value()
    ->node('ns=2;i=1001')->displayName()
    ->execute();

$status = $client->write('ns=2;i=1001', 42, BuiltinType::Int32);

$statuses = $client->writeMulti([
    ['nodeId' => 'ns=2;i=1001', 'value' => 42, 'type' => BuiltinType::Int32],
]);
```

### Method Call

```php
$result = $client->call('i=2253', 'i=11492', [new Variant(BuiltinType::UInt32, 1)]);
$result->statusCode;
$result->outputArguments;      // Variant[]
$result->inputArgumentResults; // int[]
```

### Subscriptions

```php
$sub = $client->createSubscription(publishingInterval: 500.0);
// SubscriptionResult: subscriptionId, revisedPublishingInterval, revisedLifetimeCount, revisedMaxKeepAliveCount

$items = $client->createMonitoredItems($sub->subscriptionId, [
    ['nodeId' => 'ns=2;i=1001'],
]);
// MonitoredItemResult[]: statusCode, monitoredItemId, revisedSamplingInterval, revisedQueueSize

$response = $client->publish();
// PublishResult: subscriptionId, sequenceNumber, moreNotifications, notifications, availableSequenceNumbers
// notifications is DataChangeNotification[]|EventNotification[] since v4.5.0 (typed objects, not arrays):
//   $n->clientHandle, $n->dataValue (DataChangeNotification) / $n->eventFields (EventNotification)

$client->deleteMonitoredItems($sub->subscriptionId, [$items[0]->monitoredItemId]);
$client->deleteSubscription($sub->subscriptionId);
```

### Transfer & Recovery

```php
$results = $client->transferSubscriptions([1, 2], sendInitialValues: true);
// TransferResult[]: statusCode, availableSequenceNumbers

$notifications = $client->republish(subscriptionId: 1, retransmitSequenceNumber: 42);
```

### History

```php
$values = $client->historyReadRaw('ns=2;i=1001', startTime: new DateTimeImmutable('-1 hour'), endTime: new DateTimeImmutable());
$values = $client->historyReadProcessed('ns=2;i=1001', $start, $end, 3600000.0, 'i=2342');
$values = $client->historyReadAtTime('ns=2;i=1001', $timestamps);
```

### Type Discovery

```php
$count = $client->discoverDataTypes();
$count = $client->discoverDataTypes(namespaceIndex: 2, useCache: false);
```

### Cache Management

```php
$client->invalidateCache('i=85');   // forwarded to daemon
$client->flushCache();              // forwarded to daemon
```

### Endpoints

```php
$endpoints = $client->getEndpoints('opc.tcp://localhost:4840', useCache: true);
```

### Error Handling

```php
try {
    $value = $client->read('i=2259');
} catch (ConnectionException $e) { /* connection lost or session expired */ }
  catch (ServiceException $e)    { /* OPC UA server error */ }
  catch (DaemonException $e)     { /* IPC error */ }
```

---

## 4. IPC Protocol

Transport: abstracted via `PhpOpcua\SessionManager\Ipc\TransportInterface` + `TransportFactory`.
`TransportFactory::create($endpoint)` turns an endpoint string into the right `TransportInterface`:
  - `unix:///absolute/path.sock` → `UnixSocketTransport`
  - `tcp://127.0.0.1:<port>` / `tcp://[::1]:<port>` → `TcpLoopbackTransport` (non-loopback hosts refused at construction)
  - scheme-less path → `UnixSocketTransport` (backwards-compatible with pre-v4.2.0 `--socket /tmp/foo.sock`)
`TransportFactory::defaultEndpoint()` returns `unix:///tmp/opcua-session-manager.sock` on Linux/macOS and `tcp://127.0.0.1:9990` on Windows.
`SocketConnection::send($endpoint, $payload)` delegates to the factory + `TransportInterface` (drop-in replacement for the pre-v4.2.0 Unix-socket inline implementation). `SocketConnection::sendVia(TransportInterface, $payload)` exposed for callers holding a long-lived transport.
Daemon side: `SessionManagerDaemon` listener is now `React\Socket\SocketServer` and accepts either `unix://` or `tcp://` URIs. A construction-time guard refuses any `tcp://` bind to a non-loopback host; `chmod` + socket-file cleanup apply only to Unix endpoints. PID file is placed next to the socket file on Unix, or under `sys_get_temp_dir()` keyed by endpoint slug for TCP.
NDJSON framing, binary-mode streams (Windows-safe), 16 MiB frame cap, 32-level JSON nesting cap.

### Commands

**ping**: health check → {status, sessions, time}
**list**: active sessions (sanitized) → {count, sessions[]}
**open**: create session → {sessionId}
**close**: disconnect session → null
**query**: execute whitelisted OPC UA method → TypeSerializer-encoded result
**describe**: return {methods, modules, wireClasses, enumClasses, wireTypeIds} of the session's underlying client — ManagedClient caches this on first call and uses it for hasMethod/hasModule/getRegisteredMethods/getLoadedModules + to mirror the daemon's WireTypeRegistry
**invoke**: generic method dispatch {method, args: [<wire-encoded>...]} → {data: <wire-encoded>}. Gated by $client->hasMethod($method) (not by ALLOWED_METHODS). Third-party module methods registered via ClientBuilder::addModule() are reachable here with zero plumbing. Args and results travel through WireMessageCodec with the describe-mirrored registry as the authoritative type allowlist.

### Authentication

Include "authToken" in every request. Validated with hash_equals().

### Allowed Query Methods (37)

Browse: browse, browseWithContinuation, browseNext, browseAll, browseRecursive
Path: translateBrowsePaths, resolveNodeId
Read/Write: read, readMulti, write, writeMulti
Call: call
Subscriptions: createSubscription, createMonitoredItems, createEventMonitoredItem, deleteMonitoredItems, deleteSubscription, publish, transferSubscriptions, republish
History: historyReadRaw, historyReadProcessed, historyReadAtTime
State: isConnected, getConnectionState, reconnect
Config: getTimeout, getAutoRetry, getBatchSize, getDefaultBrowseMaxDepth, getServerMaxNodesPerRead, getServerMaxNodesPerWrite
Discovery/Cache: getEndpoints, discoverDataTypes, invalidateCache, flushCache

### Wire Pipeline (describe + invoke)

- Wire format: every non-scalar typed value is `{"__t": "<id>", ...}` where `<id>` is registered on both sides. Unregistered `__t` values are rejected at decode — no `unserialize()` anywhere, no PHP gadget-chain surface.
- Registry contents: core types (NodeId, QualifiedName, LocalizedText, DataValue, Variant, ExtensionObject, BrowseNode, ReferenceDescription, EndpointDescription, UserTokenPolicy) + core enums (BuiltinType, NodeClass, BrowseDirection, ConnectionState) + each loaded module's getSerializableTypes contribution (SubscriptionResult, TransferResult, MonitoredItemResult, MonitoredItemModifyResult, PublishResult, DataChangeNotification, EventNotification, SetTriggeringResult, CallResult, BrowsePathResult, BrowsePathTarget, BrowseResultSet, AddNodesResult, BuildInfo, …).
- ManagedClient builds its own WireMessageCodec from the describe response — classes the daemon declares but the client cannot load are skipped (decode fails loudly if they appear in an invoke payload).
- NodeManagement methods (addNodes, deleteNodes, addReferences, deleteReferences) delegate through invoke in v4.2.0 — they succeed only when the daemon opted into NodeManagementModule via ClientBuilder::addModule().

### Query Param Deserialization (registry pattern, v4.2.0)

The IPC `query` command still goes through the legacy `TypeSerializer` path (wire migration deferred to v5), but the argument-decoding side now lives behind a registry.

- `PhpOpcua\SessionManager\Serialization\ParamDeserializerInterface` — `supports(string $method): bool` + `deserialize(string $method, array $params): array`.
- `PhpOpcua\SessionManager\Serialization\ParamDeserializerRegistry` — ordered list of deserializers, consulted first-match-wins.
- `PhpOpcua\SessionManager\Serialization\BuiltInParamDeserializer` — the shipped implementation covering every method in `CommandHandler::ALLOWED_METHODS` (45 methods). Encapsulates what used to be the 200-line `match` inside `CommandHandler::deserializeParams()`.
- Third-party modules that register custom service methods on the daemon's client ship their own deserializer and plug it in via `CommandHandler::registerParamDeserializer()`.

### Session Config DTO (v4.2.0)

The `open` command's `config` payload is consumed through `PhpOpcua\SessionManager\Daemon\SessionConfig` — a readonly DTO with one typed property per knob (`opcuaTimeout`, `autoRetry`, `securityPolicy`, `username`/`password`, `clientCertPath`/`clientKeyPath`/`caCertPath`, `userCertPath`/`userKeyPath`, `trustStorePath`, `trustPolicy`, `autoAccept`/`autoAcceptForce`, `verifyApplicationUri`, `autoDetectWriteType`, `readMetadataCache`, `batchSize`, `defaultBrowseMaxDepth`, `securityMode`).

Helpers:
- `SessionConfig::fromArray(array)` — parses the wire JSON with scalar coercion; unknown keys are silently ignored (forwards-compatible).
- `SessionConfig::toArray(): array` — emits only non-null fields.
- `SessionConfig::sanitized(): self` — returns a copy with `password`/`clientKeyPath`/`caCertPath`/`userKeyPath` nulled. `SESSION_CONFIG::SENSITIVE_FIELDS` lists them.

`CommandHandler::handleOpen()` is now a two-step flow: `SessionConfig::fromArray($cmd['config'])` → `$this->buildClientFromConfig($endpointUrl, $config)` (private helper) → `Session` creation. Wire format is unchanged for backwards compatibility.

---

## 5. Type Serialization

TypeSerializer handles bidirectional JSON ↔ OPC UA type conversion for IPC transport.

### Core Types

| Type | JSON |
|---|---|
| NodeId | {"ns": 0, "id": 2259, "type": "numeric"} |
| Variant | {"type": 6, "value": 42, "dimensions": null} |
| DataValue | {"value": 42, "type": 6, "dimensions": null, "statusCode": 0, "sourceTimestamp": "...", "serverTimestamp": "..."} |
| QualifiedName | {"ns": 0, "name": "Server"} |
| LocalizedText | {"locale": "en", "text": "Server"} |
| ReferenceDescription | {"referenceTypeId": {...}, "isForward": true, "nodeId": {...}, ...} |
| BrowseNode | {"reference": {...}, "children": [...]} |
| EndpointDescription | {"endpointUrl": "...", "securityMode": 1, ...} |
| BuiltinType | int (enum value) |
| NodeClass | int (enum value) |
| BrowseDirection | int (enum value) |
| ConnectionState | string (enum name) |
| DateTimeImmutable | string (ISO 8601) |

### v3.0.0 DTOs

| DTO | JSON |
|---|---|
| SubscriptionResult | {"subscriptionId": 1, "revisedPublishingInterval": 500.0, ...} |
| MonitoredItemResult | {"statusCode": 0, "monitoredItemId": 100, ...} |
| CallResult | {"statusCode": 0, "inputArgumentResults": [...], "outputArguments": [...]} |
| BrowseResultSet | {"references": [...], "continuationPoint": "..."} |
| PublishResult | {"subscriptionId": 1, "sequenceNumber": 42, ...} |
| DataChangeNotification | {"type": "DataChange", "clientHandle": 1, "dataValue": {...}} |
| EventNotification | {"type": "Event", "clientHandle": 2, "eventFields": [...]} |
| BrowsePathResult | {"statusCode": 0, "targets": [...]} |
| TransferResult | {"statusCode": 0, "availableSequenceNumbers": [...]} |

Variant dimensions are preserved through serialization roundtrips.

---

## 6. Session Persistence

```php
// Request 1: open session
$client = new ManagedClient();
$client->connect('opc.tcp://localhost:4840');
$sessionId = $client->getSessionId();
// Store $sessionId — do NOT disconnect

// Request 2: session is still alive
$client = new ManagedClient();
$client->connect('opc.tcp://localhost:4840');
$value = $client->read('i=2259'); // ~5ms, no handshake
```

Sessions expire after --timeout seconds of inactivity. The cleanup timer runs every --cleanup-interval seconds.

---

## 7. Project Structure

```
src/
├── Client/
│   ├── ManagedClient.php           # OpcUaClientInterface proxy
│   └── SocketConnection.php        # Unix socket transport
├── Daemon/
│   ├── SessionManagerDaemon.php    # ReactPHP daemon
│   ├── AutoPublisher.php           # Per-session auto-publish cycle manager
│   ├── CommandHandler.php          # Command dispatch + security + auto-connect
│   ├── Session.php                 # Session wrapper
│   └── SessionStore.php            # In-memory registry
├── Serialization/
│   └── TypeSerializer.php          # JSON ↔ OPC UA types
└── Exception/
    ├── DaemonException.php
    ├── SessionNotFoundException.php
    └── SerializationException.php
```

---

## Main Classes

- PhpOpcua\SessionManager\Client\ManagedClient — implements OpcUaClientInterface, proxies to daemon
- PhpOpcua\SessionManager\Client\SocketConnection — static send() for Unix socket JSON transport
- PhpOpcua\SessionManager\Daemon\SessionManagerDaemon — ReactPHP daemon with cleanup, signal handling, auto-publish, auto-connect
- PhpOpcua\SessionManager\Daemon\AutoPublisher — per-session auto-publish cycle with self-rescheduling timers and ack management
- PhpOpcua\SessionManager\Daemon\CommandHandler — IPC command processor with 37-method whitelist, auto-connect sessions
- PhpOpcua\SessionManager\Daemon\Session — readonly id, client, endpointUrl, config; mutable lastUsed; subscription interval tracking
- PhpOpcua\SessionManager\Daemon\SessionStore — create, get, remove, touch, getExpired, count, all
- PhpOpcua\SessionManager\Serialization\TypeSerializer — serialize/deserialize for all OPC UA types and DTOs
- PhpOpcua\SessionManager\Exception\DaemonException — socket/IPC errors
- PhpOpcua\SessionManager\Exception\SessionNotFoundException — session not in store
- PhpOpcua\SessionManager\Exception\SerializationException — type conversion errors

## Related Packages

- php-opcua/opcua-client: core OPC UA client library (required dependency)
- php-opcua/opcua-laravel: Laravel integration (service provider, facade, config)
- php-opcua/laravel-opcua: Laravel integration (service provider, facade, config)
- php-opcua/opcua-cli: CLI tool for OPC UA operations
- php-opcua/opcua-client-nodeset: Pre-generated PHP types from OPC Foundation companion specifications
- php-opcua/uanetstandard-test-suite: Docker-based OPC UA test servers (UA-.NETStandard)

## Links

- Repository: https://github.com/php-opcua/opcua-session-manager
- Documentation: https://github.com/php-opcua/opcua-session-manager/tree/master/docs (or https://www.php-opcua.com/documentation/opcua-session-manager)
- Issues: https://github.com/php-opcua/opcua-session-manager/issues
- Packagist: https://packagist.org/packages/php-opcua/opcua-session-manager
- Changelog: https://github.com/php-opcua/opcua-session-manager/blob/master/CHANGELOG.md