History writes — HistoryUpdate

The HistoryUpdate service set (Part 11 §6.9) lets a client mutate the historical record itself — insert missing samples, replace one that turned out to be wrong, delete a range, manage historical events. Like HistoryRead, it is optional in the spec: many servers reject every operation with Bad_ServiceUnsupported or Bad_HistoryOperationUnsupported. Test against your target server before designing a feature around the call.

This library exposes nine methods, all on OpcUaClientInterface:

Insert / Replace / Update share the same semantics as the underlying PerformUpdateType enum (Part 11 §6.9.2): Insert fails per-entry if a value already exists at the timestamp; Replace fails if none exists; Update is the upsert combination.

PerformUpdateType enum

The four server-side semantics that travel inside HistoryUpdateData calls:

You normally don't construct this enum yourself — each typed method picks the right PerformUpdateType internally. The enum surfaces on the HistoryDataUpdated / HistoryEventUpdated events so a listener can branch on which operation produced the change.

The enum lives at PhpOpcua\Client\Module\History\PerformUpdateType and is backed by int matching the Part 11 numeric values.

Inserting / replacing / updating data

All three accept a NodeId|string and an array of DataValues. Each DataValue carries the value, status code, and the sourceTimestamp that identifies the entry. The return value is an int[] parallel to the input array — one OPC UA status code per value.

use PhpOpcua\Client\Types\DataValue;
use PhpOpcua\Client\Types\StatusCode;

$values = [
    new DataValue(
        value:           42.5,
        statusCode:      StatusCode::Good,
        sourceTimestamp: new DateTimeImmutable('2026-05-19 08:00:00'),
    ),
    new DataValue(
        value:           42.7,
        statusCode:      StatusCode::Good,
        sourceTimestamp: new DateTimeImmutable('2026-05-19 08:00:01'),
    ),
];

$statuses = $client->historyInsertData('ns=2;s=Tank42/Level', $values);

foreach ($statuses as $i => $status) {
    if (! StatusCode::isGood($status)) {
        // BadEntryExists, BadHistoryOperationUnsupported, …
    }
}

The three calls differ only in their conflict semantics:

Use historyUpdateData() when you don't care which one happened — the upsert is the most forgiving and the most common choice for backfill scripts.

Deleting data by range or timestamp

Delete every stored sample in [startTime, endTime]. $isDeleteModified = true targets the Modified history (the audit copy of previous-value versions) instead of the raw history.

$status = $client->historyDeleteRawModified(
    nodeId:     'ns=2;s=Tank42/Level',
    startTime:  new DateTimeImmutable('-30 days'),
    endTime:    new DateTimeImmutable('-7 days'),
);

if (! StatusCode::isGood($status)) {
    throw new RuntimeException(
        'History purge rejected: ' . StatusCode::getName($status)
    );
}

This call returns a single overall status code — the spec does not expose per-sample failures for range deletes. For a fine-grained delete, list the timestamps:

$statuses = $client->historyDeleteAtTime(
    nodeId:     'ns=2;s=Tank42/Level',
    timestamps: [
        new DateTimeImmutable('2026-05-19 08:00:00'),
        new DateTimeImmutable('2026-05-19 08:00:01'),
    ],
);

The return is one status per timestamp — Bad_NoEntryExists for any entry that wasn't found.

Inserting / replacing / updating events

Event history writes carry a parallel selectFields / eventData shape:

• $selectFields — string[], the BrowseName-path of each event field (e.g. ['EventId', 'Severity', 'Message', 'Time']).
• $eventData — array<int, Variant[]>, one Variant[] per event, matching $selectFields index-by-index.

The $nodeId is the Event source node (typically the Server object ns=0;i=2253, or a specific device that emits the alarms you're backfilling).

use PhpOpcua\Client\Types\Variant;
use PhpOpcua\Client\Types\BuiltinType;

$selectFields = ['EventId', 'Severity', 'Message', 'Time'];

$events = [
    [
        new Variant(BuiltinType::ByteString, hex2bin('0102030405060708')),
        new Variant(BuiltinType::UInt16,     800),
        new Variant(BuiltinType::String,     'Tank42 level exceeded HighLimit'),
        new Variant(BuiltinType::DateTime,   new DateTimeImmutable('2026-05-19 09:14:32')),
    ],
    [
        new Variant(BuiltinType::ByteString, hex2bin('0102030405060709')),
        new Variant(BuiltinType::UInt16,     400),
        new Variant(BuiltinType::String,     'Tank42 level returned to normal'),
        new Variant(BuiltinType::DateTime,   new DateTimeImmutable('2026-05-19 09:18:11')),
    ],
];

$statuses = $client->historyInsertEvent('i=2253', $selectFields, $events);

Replace and Update follow the same pattern, with the same Insert/Replace/Update conflict semantics as the data variants.

Deleting events by EventId

Each EventId is the raw byte string the server originally minted for the event — typically captured from a prior EventNotificationReceived and stored alongside the user's record of the alarm. The method targets the same Event-source node and returns one status per EventId.

$statuses = $client->historyDeleteEvent(
    nodeId:   'i=2253',
    eventIds: [
        hex2bin('0102030405060708'),
        hex2bin('0102030405060709'),
    ],
);

Events emitted by the write path

Every HistoryUpdate call dispatches one PSR-14 event after the request returns. Wire a listener to instrument writes, audit backfills, or push status to a dashboard:

All four carry a $client reference too. See Observability · Event reference for the full field list.

Failure modes

The same per-server caveat as HistoryRead applies, plus a few HistoryUpdate-specific status codes:

Bad_ServiceUnsupported is unwrapped into a ServiceUnsupportedException rather than being returned as a status — catch it specifically. See Reference · Exceptions and Recipes · Handling unsupported services.

Test server

extra-test-suite v1.2.0 ships an open62541-historizing service on port 24842 with a single historizing Double at ns=2;s=Historizing.Counter and an in-memory backend. The five Data operations round-trip cleanly there; the event variants are framed correctly at the wire level but the Memory backend doesn't implement the actual event paths — expect Bad_HistoryOperationUnsupported for those.

See extra-test-suite/docs/servers/open62541-historizing for the full behaviour matrix.

What to read next

• History reads — the read side of the same service set.
• Client-side aggregates — compute aggregates from a raw read instead of asking the historian for them.