Download the PHP package zuqongtech/laravel-kronos without Composer

⏱ Laravel Kronos

A reactive workflow orchestration and scheduling engine for Laravel.

Rule-driven. DAG-based. Multi-node safe.

Kronos bridges the gap between Laravel's built-in cron scheduler and a full workflow orchestration platform. It watches your Eloquent models, evaluates configurable rules, and reactively writes a canonical kronos.yaml / Redis configuration — then executes complex multi-step DAG workflows with branching, parallel execution, retries, shared context, and a full audit trail.

Think of it as Laravel's scheduler meets Apache Airflow, natively integrated with Eloquent, Horizon, and Filament.

Table of Contents

• Why Kronos?
• Requirements
• Installation
• Quick Start
• Core Concepts
  • Rule Engine
  • Config Writer (YAML + Redis)
  • Workflow Orchestration
  • DAG Resolution
  • Workflow Context
  • Triggers
  • Branching
• Building Steps
• Scheduled Tasks (Simple Cron)
• Multi-Node Deployments
• Filament UI
• Webhook API
• Artisan Commands
• Events
• Configuration Reference
• Testing
• FAQ
• Changelog
• Contributing
• Security
• License

Why Kronos?

Laravel's built-in scheduler is great for simple cron tasks but falls short when you need:

Requirements

Installation

Install via Composer:

Run the install command to publish config and run migrations:

This publishes config/kronos.php, runs the five Kronos migrations, and creates an empty storage/kronos.yaml.

Manual publish (optional):

Quick Start

1. Register rules and workflows in a Service Provider

Create a dedicated provider or use your AppServiceProvider:

2. Implement your step jobs

3. Trigger a workflow manually

Or via the facade:

Core Concepts

Rule Engine

The rule engine is the reactive heart of Kronos. Rules watch Eloquent model events and, when a condition is met, dispatch a debounced rebuild of the canonical config.

Cross-model conditions — a rule can require two models to both satisfy conditions:

How debouncing works: When any rule matches, Kronos dispatches RebuildKronosConfig — a ShouldBeUnique job. If fifty model saves fire in rapid succession, only one rebuild executes. This prevents write storms.

Config Writer (YAML + Redis)

Every rule match and workflow registration ultimately writes to two places:

storage/kronos.yaml — human-readable, version-controllable source of truth:

Redis (kronos:config) — fast key-value store read at every kernel boot. Preferred over the YAML file on multi-node setups. When the YAML is written, Redis is updated atomically and a pub/sub invalidation is broadcast to all nodes.

The YAML file is written using a rename-after-write strategy (write to .tmp, then rename()), guaranteeing no partial reads during kernel boot.

Workflow Orchestration

A workflow is a named DAG (Directed Acyclic Graph) of steps with a trigger, optional branching, and shared context.

Each ->register() call persists the workflow to the kronos_workflows table and triggers a config rebuild.

DAG Resolution

Kronos resolves step execution order using Kahn's topological sort algorithm. Steps with no unmet dependencies are dispatched as a batch (running in parallel via the queue). When a batch completes, the resolver re-evaluates and dispatches the next ready batch.

If a circular dependency is detected, Kronos throws KronosDeadlockException at registration time — not at runtime.

Workflow Context

WorkflowContext is a persistent key-value store shared across all steps in a run. It is backed by the kronos_workflow_runs.context JSON column and survives queue worker restarts and container crashes.

Available methods:

Triggers

Every workflow has exactly one trigger. Available trigger types:

Cron with timezone:

Branching

Workflows can define conditional branches evaluated at runtime against the workflow context:

The branch arm that does not match has all its steps marked as skipped — visible in the run history.

Building Steps

Every step must implement ZuqongTech\Kronos\Contracts\KronosStep:

Step options on the definition:

Scheduled Tasks (Simple Cron)

For simple scheduled commands without multi-step workflows, use the KronosScheduledTask model directly or via the Filament UI:

Or use the rule engine to derive tasks from your own models:

Multi-Node Deployments

Enable multi-node mode

When KRONOS_MULTI_NODE=true:

• All schedule entries are registered with ->onOneServer() automatically.
• The orchestrator wraps every advance() call in a Redis distributed lock.
• ExecuteWorkflowStep uses ShouldBeUnique — a step can only execute once per run regardless of node count.
• Config is always read from Redis first, with kronos.yaml as fallback.
• Config writes broadcast a Redis pub/sub invalidation on the kronos:invalidate channel.

Recommended ECS / Kubernetes setup

Run a single dedicated scheduler replica that only runs schedule:run, separate from your web/worker replicas:

This eliminates multi-node scheduler overlap at the infrastructure level, leaving Redis locking as a defence-in-depth layer only.

Write-path flow on multi-node

Filament UI

Kronos ships a first-class Filament v3 plugin.

Register the plugin

Available UI screens

Note: The Filament plugin requires filament/filament: ^3.0 in your application's composer.json. It is suggested but not required by Kronos itself.

Webhook API

Enable the HTTP webhook endpoint for external workflow triggers:

Trigger a workflow

Response:

Check run status

Response:

Artisan Commands

Events

Kronos fires standard Laravel events you can listen to:

Register listeners in your EventServiceProvider:

Payload:

Configuration Reference

Environment variables summary:

Testing

Kronos is tested with PestPHP.

Testing workflows in your application

Kronos exposes Laravel's standard Bus::fake() and Event::fake() patterns cleanly:

Testing your step jobs directly

Step jobs are plain PHP classes — test them in isolation without queue infrastructure:

FAQ

Q: Does Kronos replace Laravel Horizon?

No — Kronos uses Horizon (or any queue driver) to dispatch step jobs. Kronos handles orchestration (which jobs run in what order and when). Horizon handles execution (the worker pool, monitoring, retries at the queue level).

Q: Can I use a database queue instead of Redis?

Yes, Kronos works with any Laravel queue driver. Redis is recommended for multi-node deployments because it is also used for distributed locking and config pub/sub. For single-node or development setups, QUEUE_CONNECTION=database works fine.

Q: Does Kronos work with Laravel Octane?

Yes. The service provider uses callAfterResolving for schedule hydration, which is compatible with Octane's persistent process model. Ensure KRONOS_MULTI_NODE=true is set so config state is read from Redis rather than a process-local file cache.

Q: Can I define workflows in a config file instead of code?

Not currently — workflows are defined in code (service providers) and persisted to the DB. A YAML-first workflow definition format is planned for a future release.

Q: How does Kronos prevent duplicate job execution on multi-node?

Three layers:

1. RebuildKronosConfig is ShouldBeUnique — only one rebuild runs at a time.
2. ExecuteWorkflowStep is ShouldBeUnique per (run_id, step_name) — a step can only be dispatched once.
3. KronosOrchestrator::advance() acquires a Redis lock per run before evaluating ready steps.

Q: Can I cancel a running workflow?

Manual cancellation via Artisan or the Filament UI is on the roadmap. Currently you can set status = cancelled directly on the KronosWorkflowRun record — the orchestrator checks isTerminal() before advancing.

Q: How are failed workflows retried?

At the workflow level, retries are not automatic — re-triggering creates a new run. Step-level retries (the ->retries(n) option) are automatic and use Laravel's built-in job retry mechanism.

Changelog

Please see CHANGELOG.md for a history of changes.

Contributing

Contributions are very welcome. Please review CONTRIBUTING.md for guidelines on:

• Reporting bugs
• Suggesting features
• Submitting pull requests
• Coding standards (PSR-12 + PHPStan level 8)
• Commit message format (Conventional Commits)

Security

If you discover a security vulnerability, please review SECURITY.md and do not open a public issue. Email [email protected] directly.

Credits

• Zuqong Technologies — original author and maintainer
• All contributors who submit issues, PRs, and feedback

License

The MIT License (MIT). Please see LICENSE for details.# laravel-kronos