Transaction
Handle to a streaming transaction running on the ArangoDB server.
Streaming transactions group N HTTP requests into a single atomic unit: either every operation is durably applied (after a successful commit()), or none are (after abort() or after the server-side idle timeout). This handle keeps the server-assigned transaction id and exposes the lifecycle operations the caller needs.
Two ways to scope operations to this transaction:
- call step() and run regular CRUD calls inside the
callback — they automatically carry the
x-arango-trx-idheader thanks to HttpTransport::withActiveTransactionId(), - pass the transaction handle's $id explicitly to
Database::request() via its
$transactionIdparameter (lower level, useful for hand-rolled wire calls).
Example — atomic two-step write:
$trx = $db->beginTransaction
(
read : [ 'audits' ] ,
write : [ 'users' , 'audits' ] ,
) ;
try
{
$trx->step( static function () use ( $db )
{
$db->collection( 'users' )->update( 'alice' , [ 'status' => 'archived' ] ) ;
$db->collection( 'audits' )->insert( [ 'user' => 'alice' , 'action' => 'archive' ] ) ;
} ) ;
$trx->commit() ;
}
catch ( \Throwable $e )
{
try { $trx->abort() ; } catch ( ArangoException ) }
throw $e ;
}
Or with the higher-level Database::withTransaction() helper (lands in Lot 7.0c) which wraps the try/commit/abort pattern.
Tags
Table of Contents
Constants
- ID_FIELD : string = 'id'
- Field carrying the transaction id in the response of every transaction lifecycle endpoint.
- RESULT_FIELD : string = 'result'
- Wrapper of every transaction lifecycle response.
- STATUS_FIELD : string = 'status'
- Field carrying the lifecycle status (one of {@see TransactionStatus}).
Properties
Methods
- __construct() : mixed
- abort() : string
- Aborts the transaction on the server, discarding every staged write.
- commit() : string
- Commits the transaction on the server, durably applying every staged write.
- exists() : bool
- Returns true when the server still knows about this transaction.
- status() : string
- Fetches the current status of the transaction on the server.
- step() : mixed
- Runs `$callback` with this transaction's id installed as the active transaction scope on the underlying HTTP transport, so that every CRUD call inside the callback automatically carries the `x-arango-trx-id` header.
- parseStatus() : string
- Extracts the `status` field from a transaction lifecycle response, unwrapping the outer `result` envelope when present.
- path() : string
- Builds the `/_api/transaction/{id}` path with the id URL-encoded.
Constants
ID_FIELD
Field carrying the transaction id in the response of every transaction lifecycle endpoint.
private
string
ID_FIELD
= 'id'
RESULT_FIELD
Wrapper of every transaction lifecycle response.
private
string
RESULT_FIELD
= 'result'
STATUS_FIELD
Field carrying the lifecycle status (one of {@see TransactionStatus}).
private
string
STATUS_FIELD
= 'status'
Properties
$database read-only
public
Database
$database
$id read-only
public
string
$id
Methods
__construct()
public
__construct(Database $database, string $id) : mixed
Parameters
- $database : Database
-
Parent database (provides the shared HTTP transport).
- $id : string
-
Server-assigned transaction id (as returned by
POST /_api/transaction/begin).
abort()
Aborts the transaction on the server, discarding every staged write.
public
abort() : string
After this call, the handle becomes useless — calling another
lifecycle method on it will surface as a 1656
(TRANSACTION_ABORTED) or 1655 (TRANSACTION_NOT_FOUND)
error depending on how long ago the server discarded it.
Tags
Return values
string —The terminal status reported by the server (TransactionStatus::ABORTED).
commit()
Commits the transaction on the server, durably applying every staged write.
public
commit() : string
The handle becomes useless after this call (see abort()).
Tags
Return values
string —The terminal status reported by the server (TransactionStatus::COMMITTED).
exists()
Returns true when the server still knows about this transaction.
public
exists() : bool
The endpoint returns the same payload as status() on
success; a 404 (or a 1655 error code) means the transaction
was never started, has expired, or was already terminated and
forgotten. Any other failure rethrows as an
ArangoException.
Tags
Return values
boolstatus()
Fetches the current status of the transaction on the server.
public
status() : string
Tags
Return values
string —One of the TransactionStatus constants.
step()
Runs `$callback` with this transaction's id installed as the active transaction scope on the underlying HTTP transport, so that every CRUD call inside the callback automatically carries the `x-arango-trx-id` header.
public
step(callable(): mixed $callback) : mixed
The previous active id (typically null) is always restored on
exit, including when the callback throws — so a panicked
caller never leaves the transport state dangling.
Example:
$trx->step( static function () use ( $db )
{
$db->collection( 'users' )->insert( [ '_key' => 'alice' ] ) ;
$db->collection( 'audits' )->insert( [ 'msg' => 'created alice' ] ) ;
} ) ;
Parameters
- $callback : callable(): mixed
-
User-provided block to run inside the transaction's scope.
Tags
Return values
mixed —The value returned by $callback.
parseStatus()
Extracts the `status` field from a transaction lifecycle response, unwrapping the outer `result` envelope when present.
private
parseStatus(mixed $body) : string
Parameters
- $body : mixed
-
Decoded response body.
Return values
string —One of the TransactionStatus constants, or an empty string when the field is absent (defensive — the server always emits it on success).
path()
Builds the `/_api/transaction/{id}` path with the id URL-encoded.
private
path() : string