adachsoft / action-json-file
JSON file-backed action run repository with atomic writes and concurrent access locking.
Requires
- php: ^8.3
- adachsoft/action-contracts: ^0.1.2
- adachsoft/reference-contracts: ^0.1
Requires (Dev)
- adachsoft/php-code-style: ^0.7.3
- friendsofphp/php-cs-fixer: ^3.95
- phpstan/phpstan: ^2.3
- phpunit/phpunit: ^13.4
- rector/rector: ^2.8
- symplify/phpstan-rules: ^14.19
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
adachsoft/action-json-file provides a framework-free JSON-file implementation of ActionRunRepositoryInterface from adachsoft/action-contracts.
Requirements
- PHP 8.3 or later
- Composer
Installation
composer require adachsoft/action-json-file
The repository package installs adachsoft/action-contracts and adachsoft/reference-contracts as dependencies. To execute actions with the framework-free ActionFactory, also install adachsoft/action:
composer require adachsoft/action
Usage
Usage with ActionFactory
Create the repository with the path where action history should be stored and pass it to ActionFactory as the runRepository. The handlers, providers, authorizer, and clock are application services implementing the corresponding contracts.
<?php
declare(strict_types=1);
use AdachSoft\Action\ActionFactory;
use AdachSoft\ActionContracts\Authorization\ActionAuthorizerInterface;
use AdachSoft\ActionContracts\Execution\ActionHandlerInterface;
use AdachSoft\ActionContracts\History\ActionRunRepositoryInterface;
use AdachSoft\ActionContracts\Type\ActionTypeProviderInterface;
use AdachSoft\ActionJsonFile\Repository\JsonActionRunRepository;
use Psr\Clock\ClockInterface;
$runRepository = new JsonActionRunRepository(__DIR__ . '/var/action-runs.json');
/** @var list<ActionHandlerInterface> $handlers */
/** @var list<ActionTypeProviderInterface> $providers */
/** @var ActionAuthorizerInterface $authorizer */
/** @var ClockInterface $clock */
$factory = new ActionFactory(
handlers: $handlers,
providers: $providers,
validators: [],
authorizer: $authorizer,
runRepository: $runRepository,
clock: $clock,
);
$executor = $factory->create();
A custom implementation can be used anywhere ActionRunRepositoryInterface is required:
use AdachSoft\ActionContracts\History\ActionRunRepositoryInterface;
use AdachSoft\ActionJsonFile\Repository\JsonActionRunRepository;
/** @var ActionRunRepositoryInterface $runRepository */
$runRepository = new JsonActionRunRepository('/var/lib/my-app/action-runs.json');
Storage format
The file is a UTF-8 JSON object with a format version and a list of action runs:
{
"version": 1,
"runs": [
{
"runId": "run-123",
"type": "demo.echo",
"params": {
"message": "Hello"
},
"actor": {
"type": "user",
"id": "alice"
},
"trigger": {
"type": "manual",
"id": null,
"occurrenceKey": null
},
"status": "succeeded",
"message": null,
"output": {
"message": "Hello"
},
"startedAt": "2025-01-01T09:00:00.123456+00:00",
"finishedAt": "2025-01-01T09:00:00.234567+00:00"
}
]
}
Dates are serialized in Y-m-d\TH:i:s.uP format. Each run stores the action type identifier and parameter/output snapshots, nested actor and trigger references, the status enum value, an optional message, and start/finish timestamps. A missing or empty file is treated as an empty repository. Unsupported document versions, malformed JSON, and invalid records raise JsonFileStorageException; mapper validation messages include the invalid field path.
Record retention
The constructor accepts an optional maximum record count:
$runRepository = new JsonActionRunRepository(
__DIR__ . '/var/action-runs.json',
maxRecords: 10_000,
);
The default is 10_000. When saving a record would exceed this limit, the repository retains the records with the newest startedAt values and removes older records. Saving a record with an existing runId replaces that record before retention is applied. The limit must be at least one.
Locking and atomic writes
Every storage file has a sidecar lock file with the .lock suffix. Reads acquire a shared flock lock. Read-modify-write operations acquire an exclusive lock for the complete cycle so updates from separate repository or storage instances do not overwrite one another.
Writes are encoded with pretty-printed, unescaped Unicode/slashes JSON, written to a temporary file in the same directory, and committed by renaming that file over the target. Keeping the temporary file beside the target allows the rename to be atomic on the same filesystem. The parent directory is created automatically. Use a filesystem that supports PHP flock and atomic same-filesystem renames for reliable coordination.