Scheduling - Ronin

Simple, powerful background job scheduling—declarative, type-safe, and event-aware.

Like a master-less samurai it wanders across the land until it finds a job.

What is Ronin?

Ronin is Sugoi Cloud’s built-in system for scheduling background jobs. It’s as simple as annotating any method with #[Ronin(...)].

Whether you want to run a job every night at midnight, or react to a published event—Ronin handles it, declaratively. The framework automatically manages and starts background workers, so the entire system is plug and play with attributes.

Quick Start Example

use SugoiCloud\Attributes\Ronin;
use SugoiCloud\Common\Schedule;

#[Component]
class BackgroundJobs {
    #[Ronin(
        name: 'nightly-report',
        schedule: Schedule::DAILY_AT_00_00,
        priority: Ronin::PRIORITY_HIGH,
        strategy: Ronin::STRATEGY_SINGLETON,
        timeout: 120
    )]
    public function generateDailyReport(): void
    {
        // Your job logic here
    }
}

This will:

• Run every night at midnight
• Execute with high priority
• Cancel future runs if a previous one is still running
• Time out after 2 minutes if it hangs

Scheduling Options

Ronin supports two powerful scheduling modes:

Scheduled, CRON-Based

Use one of Sugoi’s built-in cron recipes via the Schedule class, e.g.:

Schedule Constant	Description
Schedule::DAILY_AT_00_00	Every day at midnight
Schedule::EVERY_5_MINUTES	Every 5 minutes
Schedule::DAILY_DURING_MIDNIGHT	Between 00:00–01:00
Schedule::YEARLY	Once a year
(and more…)	Custom cron supported too

Triggered, Event-Based

Instead of a schedule, you can provide a trigger, which is:

• A string event name, or
• A class name of an Event payload for type-safe dispatch

#[Ronin(
    name: 'send-welcome',
    trigger: UserRegisteredEvent::class
)]
public function sendWelcomeEmail(UserRegisteredEvent $event): void
{
    // Called automatically when UserRegisteredEvent is published
}

Ronin Options

Option	Description
name	Unique job name (used for overrides, tracking)
schedule	Cron-style job schedule (see above)
trigger	Event-based trigger (alternative to schedule)
priority	Execution priority: LOW, NORMAL, HIGH
strategy	Execution strategy (see below)
timeout	Max runtime (in seconds), default: 300
immediate	If true, runs immediately on boot if schedule matches

Execution Strategies

Strategy	Behaviour
STRATEGY_CONCURRENT	Runs jobs concurrently as scheduled
STRATEGY_STACKING	Queues jobs in order of arrival
STRATEGY_SINGLETON	Ensures only one job runs at a time; future duplicates are skipped if a previous run is active

Immediate Execution

Set immediate: true to run the job as soon as the app starts, if the schedule window matches.

Great for “fire once on boot” jobs like cache warmers or analytics aggregation.