adachsoft / automation-symfony-bundle
Symfony bundle for scheduling and running JSON-backed automation workflows.
Package info
gitlab.com/a.adach/automation-symfony-bundle
pkg:composer/adachsoft/automation-symfony-bundle
Requires
- php: ^8.3
- adachsoft/action: ^0.1
- adachsoft/action-contracts: ^0.1.2
- adachsoft/action-json-file: ^0.1
- adachsoft/automation: ^0.1
- adachsoft/automation-contracts: ^0.1.2
- adachsoft/automation-json-file: ^0.1
- adachsoft/recurrence: ^0.1
- adachsoft/recurrence-contracts: ^0.1
- psr/clock: ^1.0
- symfony/clock: ^7.0 || ^8.0
- symfony/config: ^7.0 || ^8.0
- symfony/console: ^7.0 || ^8.0
- symfony/dependency-injection: ^7.0 || ^8.0
- symfony/http-kernel: ^7.0 || ^8.0
- symfony/lock: ^7.0 || ^8.0
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
- symfony/framework-bundle: ^7.0 || ^8.0
- symplify/phpstan-rules: ^14.19
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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.0components. - 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 mostaction_runs.max_recordsrecords.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.