opcua-client copilot-instructions.md

OPC UA PHP Client — Copilot Instructions

This repository contains php-opcua/opcua-client, a pure PHP OPC UA client that communicates directly over TCP using the OPC UA binary protocol.

Project context

For a full understanding of this library, read these files in order:

1. llms.txt — compact project summary: architecture, classes, API, configuration
2. llms-full.txt — comprehensive technical reference: every class, method, DTO, encoding, security, protocol services
3. llms-skills.md — task-oriented recipes: connect, read, write, browse, subscribe, security, testing, Laravel integration

Architecture

ClientBuilder (configuration)
    │
    ▼ connect()
Client (OpcUaClientInterface)
    ├── Transport (TCP socket)
    ├── Protocol (OPC UA service encoding/decoding)
    ├── Encoding (binary serialization)
    ├── Security (secure channel, crypto)
    ├── Types (NodeId, DataValue, Variant, DTOs)
    ├── Repository (ExtensionObject codecs)
    ├── Cache (PSR-16: InMemoryCache, FileCache)
    ├── Event (47 PSR-14 events)
    ├── TrustStore (server certificate trust)
    └── Testing (MockClient)

Key classes

• src/ClientBuilder.php — builder / entry point, ClientBuilder::create()->connect()
• src/Client.php — connected client, implements OpcUaClientInterface
• src/ClientBuilder/ — 8 builder traits (cache, events, timeout, trust store, batching, etc.)
• src/Client/ — 14 runtime traits (browse, read/write, subscriptions, history, etc.)
• src/Types/ — all OPC UA data types, enums, and result DTOs (public readonly properties)
• src/Security/ — secure channel, crypto, 6 security policies
• src/Testing/MockClient.php — in-memory test double, no TCP connection
• src/Repository/ExtensionObjectRepository.php — per-client codec registry

Code conventions

• declare(strict_types=1) in every file
• Public readonly properties on all DTOs (not getters): $ref->nodeId, $dv->statusCode
• All methods accepting NodeId also accept string format: 'i=2259', 'ns=2;s=MyNode'
• Configuration on ClientBuilder before connect() — Client is immutable after connection
• PHPDoc on every class and public method (@param, @return, @throws, @see)
• No comments inside function bodies — if code needs a comment, it should be split into well-named methods
• Tests use Pest PHP (not PHPUnit)
• Integration tests grouped with ->group('integration')
• Coverage target: 99%+