History Read

OPC UA servers with historizing enabled can store past values. This library supports three types of historical queries: raw, processed, and at-time.

Raw History

Get stored values within a time range, exactly as recorded:

use PhpOpcua\Client\Types\NodeId;
use PhpOpcua\Client\Types\StatusCode;

$now = new \DateTimeImmutable();
$oneHourAgo = $now->modify('-1 hour');

$values = $client->historyReadRaw(
    'ns=2;i=1001',  // or NodeId::numeric(2, 1001)
    startTime: $oneHourAgo,
    endTime: $now,
    numValuesPerNode: 100,
    returnBounds: false,
);

foreach ($values as $dv) {
    echo sprintf(
        "[%s] %s (status: %s)\n",
        $dv->sourceTimestamp?->format('Y-m-d H:i:s.u'),
        $dv->getValue(),
        StatusCode::getName($dv->statusCode),
    );
}

Parameters

Parameter	Default	Description
`nodeId`	(required)	Node to read history from
`startTime`	`null`	Beginning of the time range
`endTime`	`null`	End of the time range
`numValuesPerNode`	`0`	Maximum values to return (`0` = no limit)
`returnBounds`	`false`	Include bounding values at the edges of the range

Processed History (Aggregates)

Get aggregated data over intervals. The server must support the HistoryRead service with processing:

$startTime = new \DateTimeImmutable('2024-01-01 00:00:00');
$endTime = new \DateTimeImmutable('2024-01-02 00:00:00');

$values = $client->historyReadProcessed(
    'ns=2;i=1001',
    $startTime,
    $endTime,
    processingInterval: 3600000.0, // 1 hour in ms
    aggregateType: 'i=2342', // Average
);

Common Aggregate Types

Aggregate	NodeId
Average	`NodeId::numeric(0, 2342)`
Interpolative	`NodeId::numeric(0, 2341)`
Minimum	`NodeId::numeric(0, 2346)`
Maximum	`NodeId::numeric(0, 2347)`
Count	`NodeId::numeric(0, 2352)`
Total	`NodeId::numeric(0, 2344)`

Note: Not all servers support all aggregate types. Check your server documentation or use getEndpoints() to discover capabilities.

History at Specific Times

Get interpolated values at exact timestamps:

$timestamps = [
    new \DateTimeImmutable('2024-01-01 08:00:00'),
    new \DateTimeImmutable('2024-01-01 12:00:00'),
    new \DateTimeImmutable('2024-01-01 16:00:00'),
    new \DateTimeImmutable('2024-01-01 20:00:00'),
];

$values = $client->historyReadAtTime(
    'ns=2;i=1001',
    $timestamps,
);

foreach ($values as $i => $dv) {
    echo sprintf(
        "At %s: %s\n",
        $timestamps[$i]->format('H:i:s'),
        $dv->getValue(),
    );
}

Tip: All three history methods return DataValue[]. Each DataValue includes ->statusCode, ->sourceTimestamp, and ->serverTimestamp alongside the value itself.