Search by

adachsoft / automation-symfony-bundle

Arkadiusz Adach

Symfony bundle for scheduling and running JSON-backed automation workflows.

Package info

gitlab.com/a.adach/automation-symfony-bundle

Issues

pkg:composer/adachsoft/automation-symfony-bundle

Statistics

Installs: 2

Dependents: 0

Suggesters: 0

Stars: 0

v0.1.0 2026-11-22 21:58 UTC

This package is auto-updated.

Last update: 2026-11-22 20:59:48 UTC


README

A Symfony bundle that wires adachsoft/action and adachsoft/automation with JSON-file repositories. It provides scheduler commands and extension-point autoconfiguration. Applications remain responsible for building their own HTTP API; this bundle does not provide HTTP controllers.

Requirements

  • PHP ^8.3.
  • Symfony ^7.0 || ^8.0 components.
  • Writable local storage for JSON repository files.

Installation

composer require adachsoft/automation-symfony-bundle

Register the bundle in config/bundles.php if Symfony Flex does not do so automatically:

return [
    AdachSoft\AutomationSymfonyBundle\AdachSoftAutomationBundle::class => ['all' => true],
];

Configuration

Configure a writable directory for the JSON repositories:

# config/packages/adachsoft_automation.yaml
adachsoft_automation:
    storage_dir: '%kernel.project_dir%/var/data/automation'
    action_runs:
        max_records: 10000
    lock:
        ttl_seconds: 300
        service: null

storage_dir is required. Action-run history is capped at max_records (default 10000). Schedule locks use ttl_seconds (default 300). Set lock.service to a service ID implementing AdachSoft\Automation\Lock\ScheduleLockInterface to provide a custom lock.

Usage

Inject the schedule service to save, enable, disable, or remove a schedule. The scheduler tick processes schedules due at the supplied instant:

use AdachSoft\AutomationContracts\Runner\AutomationTickInterface;
use AdachSoft\AutomationContracts\Runner\ScheduleServiceInterface;
use AdachSoft\AutomationContracts\Schedule\ScheduleDto;
use AdachSoft\ReferenceContracts\PrincipalReference;
use DateTimeImmutable;

final class ScheduleSetup
{
    public function __construct(
        private ScheduleServiceInterface $schedules,
        private AutomationTickInterface $tick,
    ) {
    }

    public function save(ScheduleDto $schedule, PrincipalReference $actor): void
    {
        $this->schedules->save($schedule, $actor);
    }

    public function runDueSchedules(): void
    {
        $this->tick->tick(new DateTimeImmutable());
    }
}

The bundle also exposes ScheduleRepositoryInterface, ScheduleStateRepositoryInterface, FiredOccurrenceRepositoryInterface, ActionRunRepositoryInterface, ScheduleRunnerInterface, recurrence contracts, action execution services, and a PSR-20 ClockInterface alias.

Registering actions

Services implementing ActionHandlerInterface, ActionTypeProviderInterface, ActionTypeValidatorInterface, ParameterOptionsProviderInterface, StopConditionInterface, or AutomationListenerInterface receive the corresponding adachsoft_automation.* tag when service autoconfiguration is enabled. Symfony's usual autowire: true and autoconfigure: true defaults are sufficient:

# config/services.yaml
services:
    _defaults:
        autowire: true
        autoconfigure: true

    App\Automation\:
        resource: '../src/Automation/'

Action handlers execute configured action definitions, while type providers describe action schemas. The bundle composes all tagged handlers, providers, validators, option providers, stop conditions, and listeners.

Authorization

The default ActionAuthorizerInterface implementation is AllowAllActionAuthorizer. It allows every principal to save and execute actions and is intended only as a permissive default. Production applications should provide an authorization policy and alias the contract to it:

services:
    App\Security\AutomationActionAuthorizer: ~
    AdachSoft\ActionContracts\Authorization\ActionAuthorizerInterface:
        alias: App\Security\AutomationActionAuthorizer

Running the scheduler

Run one tick every minute from cron:

* * * * * cd /path/to/app && php bin/console automation:tick

For a continuously running worker service, use:

php bin/console automation:worker --interval=30 --max-iterations=0

The worker handles SIGTERM and SIGINT gracefully when the pcntl extension is available. --max-iterations defaults to 0 (unlimited). Run automation:prune to remove old fired-occurrence markers and action-run records; both retention options default to 90 days.

Storage files

The bundle stores data in separate JSON files under storage_dir:

  • action-runs.json — action execution history, retaining at most action_runs.max_records records.
  • schedules.json — schedule definitions.
  • schedule-states.json — schedule runtime state and next-occurrence cursors.
  • fired-occurrences.json — occurrence idempotency markers.

Repositories create their parent directory on first write and use sidecar lock files and atomic file replacement. Operations across the different documents are not transactional. The JSON-file adapters are intended for a local filesystem shared by the scheduler processes.

Locking

If lock.service is configured, the bundle uses that ScheduleLockInterface service. Otherwise, a registered Symfony LockFactory is adapted automatically, using non-blocking acquisition and the configured TTL. When neither is available, the bundle uses NullScheduleLock; this is appropriate only when scheduler workers cannot run concurrently. Configure a shared Symfony lock store when multiple workers may process schedules at the same time.