Search by

adachsoft / action-json-file

Arkadiusz Adach

JSON file-backed action run repository with atomic writes and concurrent access locking.

Package info

gitlab.com/a.adach/action-json-file

Issues

pkg:composer/adachsoft/action-json-file

Statistics

Installs: 2

Dependents: 0

Suggesters: 0

Stars: 0

v0.1.0 2026-11-22 19:42 UTC

This package is auto-updated.

Last update: 2026-11-22 18:43:14 UTC


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.