Download the PHP package codetechnl/laravel-taskbridge without Composer

laravel-taskbridge

A database-driven scheduler that runs your Laravel jobs through AWS EventBridge Scheduler and SQS — without needing a server running around the clock.

Laravel's built-in scheduler still works alongside this package. TaskBridge is an addition, not a replacement: use it for jobs that should be triggered by EventBridge so you are not dependent on a continuously running server or schedule:run cron for those tasks. Jobs are stored in your database, synced to EventBridge, and dispatched into SQS at the configured time. The queue worker picks them up and processes them as normal Laravel jobs.

Features

• No schedule:run dependency — EventBridge fires jobs directly onto SQS; your server does not need to run continuously
• Database-driven — every registered job is stored in taskbridge_jobs; history in taskbridge_job_runs
• Recurring schedules — standard 5-part cron or 6-part AWS cron expression
• One-time schedules — dispatch a job once at a specific date/time via scheduleOnce(); the record is kept in the database for visibility and purged automatically by PruneOnceSchedulesJob, or skipped altogether with log: false for bulk use
• Scalar constructor arguments — bool, int, float, string (and nullable variants) are serialized into the SQS payload at schedule-creation time and reconstructed by the queue worker
• Timezone-aware — cron expressions are sent with ScheduleExpressionTimezone matching config('app.timezone'); one-time at() expressions are always converted to UTC
• Full run history — every execution logged with status, duration, trigger type, sub-jobs dispatched, and structured output
• Enable / disable — toggle a schedule on/off without deleting it; disabled schedules are removed from EventBridge but kept in the database
• Runtime conditions — implement RunsConditionally to skip execution based on application state
• Structured output — implement ReportsTaskOutput to log per-run metadata (rows processed, records skipped, etc.)
• Domain events — hook into the execution lifecycle via Laravel events
• Built-in maintenance jobs — PruneRunsJob and PruneOnceSchedulesJob ship with the package
• Custom models — extend the default models for your own scopes and relations
• Predefined schedules — define jobs and their cron expressions in config/taskbridge.php and import them with a single artisan command

How it works

Your existing Laravel scheduler (schedule:run) keeps working unchanged. TaskBridge adds a separate path for jobs that should be triggered by EventBridge, removing the requirement for a continuously running server or cron daemon for those specific tasks.

Admin UI

A Filament admin panel integration is available as a separate package:

The Filament package adds a full CRUD interface for managing scheduled jobs, viewing run history, triggering manual executions, and configuring constructor arguments — all without touching AWS directly. See its README for installation and configuration details.

Requirements

• PHP 8.3+
• Laravel 12 or 13
• AWS account with EventBridge Scheduler and SQS access

Installation

Publish and run the migrations:

Publish the config file:

AWS setup

1. IAM execution role

EventBridge Scheduler needs an IAM role to put messages on your SQS queue. This role is separate from your application's AWS credentials — even admin credentials cannot bypass it.

Create the role with an SQS trust policy and sqs:SendMessage permission:

Using CDK? CDK can create and wire up this role automatically. Pass the generated role.roleArn output as TASKBRIDGE_SCHEDULER_ROLE_ARN.

2. EventBridge schedule group

Create a schedule group (or use the default default group):

3. Environment variables

Creating a scheduled job

Any standard Laravel ShouldQueue job can be used with TaskBridge. No extra interface required:

Predefined cron expression

Implement HasPredefinedCronExpression to bake a default cron expression into the job class. The Filament UI and sync() will pre-fill it automatically:

Alternatively, set the cron directly on the #[SchedulableJob] attribute:

The interface and attribute are both optional. If neither is set, the cron must be configured manually when creating the job record in the UI — useful when the schedule differs per environment.

The priority order is: #[SchedulableJob(cron:)] → HasPredefinedCronExpression::cronExpression() → set manually in the UI.

Constructor arguments

Jobs with scalar constructor parameters (bool, int, float, string, or nullable variants) are fully supported. TaskBridge discovers them automatically and the Filament UI renders an input field for each parameter.

The argument values are baked into the serialized SQS payload at the time the EventBridge schedule is created (or at the time a one-time schedule is set up). This means the job is reconstructed with the exact values you configured when the queue worker processes it — the arguments survive the full EventBridge → SQS → queue worker round-trip.

Jobs whose constructors require non-scalar arguments (e.g. Eloquent models, service objects) are excluded from registration — those values cannot be serialized into a static EventBridge payload. They are still surfaced in the Filament job picker as non-selectable cards with an explanation of which parameters are incompatible.

PHP constructor rule: Required parameters must come before optional ones. A parameter is optional only when it has a declared default value and all parameters after it also have default values. Violating this order causes PHP to silently strip the default value, making the parameter required.

Nullable parameters

There are two distinct nullable cases:

Required nullable — no default value, but accepts null. The Filament UI renders the field as required. Submitting it empty sends null to the job.

Optional nullable — has a default of null. The Filament UI renders the field as optional with a helper text hint. Leave it empty and the job receives null and can fall back to its own default logic:

The distinction matters in the UI: required nullable fields are validated as required; optional nullable fields show a "Leave empty to use the application default" hint.

Optional interfaces

All optional interfaces follow Laravel's naming conventions and are self-describing.

Tip: When using #[SchedulableJob] you can set name, group, and cron directly on the attribute instead of implementing the corresponding interface. The attribute takes precedence when both are present.

HasCustomLabel — display name

Without this interface (or the name attribute parameter), TaskBridge auto-derives a readable label from the class name: SendDailyReport → "Send daily report".

HasGroup — group in the UI

Without this interface (or the group attribute parameter), TaskBridge auto-detects the group from the job's folder: App\Jobs\Reporting\SendDailyReport → group "Reporting".

SkipOnMaintenance — skip when the application is down

Include this trait to automatically skip execution whenever the application is in maintenance mode. No configuration required — the run is recorded as Skipped in the history.

TaskBridge checks shouldSkipInMaintenanceMode() before evaluating RunsConditionally, so a job with both will short-circuit on maintenance without ever calling shouldRun(). To add a custom runtime condition on top, implement RunsConditionally alongside the trait:

RunsConditionally — runtime skip condition

Return false to skip execution. The run is recorded as Skipped in the history.

ReportsTaskOutput — log structured output

The metadata is stored as a success JobOutput in the run log. On failure, TaskBridge automatically records an error output with the exception message — no action needed in the job.

Job discovery

TaskBridge supports three ways to register jobs:

1. Auto-discovery — interface mode (default)

Scans directories and registers every non-abstract ShouldQueue job with a scalar constructor:

Subdirectories are scanned recursively. Jobs in app/Jobs/Reporting/ are automatically grouped under "Reporting" unless they implement HasGroup or carry #[SchedulableJob(group:)].

2. Auto-discovery — attribute mode

Only registers classes that carry the #[SchedulableJob] attribute. The ShouldQueue check is skipped; the attribute itself is the discovery gate. Useful when you want explicit opt-in instead of registering every queued job in the folder:

3. Manual registration

Disable discovery entirely and list jobs explicitly — useful for jobs from vendor packages or when you want full control:

The jobs array is always merged with discovered jobs, regardless of mode. Use it to add individual jobs from outside the scanned paths even when discovery is active:

#[SchedulableJob] attribute

The attribute can carry optional metadata that takes precedence over the equivalent interfaces:

All three parameters are optional. Omitting them falls back to the corresponding interface, then to auto-derived defaults. You may use #[SchedulableJob] with no arguments purely as a discovery marker while keeping existing interface implementations unchanged.

Predefined schedules

You can define jobs and their configuration directly in config/taskbridge.php under the schedules key, then import them into the database with a single artisan command:

Run the import command to upsert all entries into the database:

The command validates each entry before importing. Invalid entries are skipped (with a warning) and processing continues with the rest. The command returns a non-zero exit code if any entry failed validation.

Validation rules:

• Each entry must be an array with a cron key — plain-string shorthand is not accepted
• The class must exist and have a scalar-only constructor
• The cron expression must be valid (5-part or 6-part AWS format)
• The arguments array must match the number of constructor parameters

Note: Each entry is an upsert. Running the command a second time updates existing records rather than creating duplicates.

Task name prefix

Job identifiers are prefixed to avoid collisions across environments. The default is the slugified APP_ENV value:

Override via TASKBRIDGE_NAME_PREFIX or set to null to disable:

64-character identifier limit

EventBridge schedule names have a maximum length. TaskBridge enforces a 64-character limit on generated identifiers:

• If prefix + "-" + kebab-class-name exceeds 64 characters, the bare class-name part is replaced with its md5() hash (the prefix is not included in the hash input).
• If prefix + "-" + md5 would still exceed 64 characters (i.e. the prefix alone is longer than 31 characters), a RuntimeException is thrown.

This means prefixes up to 31 characters are always safe. Prefixes longer than 31 characters may cause an exception if the identifier would still overflow after md5 substitution.

One-time schedule names (once-{identifier}-{8 random characters}, see One-time scheduling) have a rule of their own, because an identifier may use the full 64 characters by itself: an identifier longer than 50 characters is shortened to its first 41 characters plus 8 hexadecimal characters of its md5(), so the name never exceeds 64 characters, the same identifier always shortens to the same stem, and two identifiers sharing a head still get different names.

Syncing to EventBridge

After adding jobs to the database (via the Filament UI or manually), sync them to EventBridge:

A sync reads the whole schedule group (following NextToken, so a group with more than 100 schedules is read completely), upserts a schedule for every enabled recurring job and deletes every other recurring schedule in the group. One-time schedules (names starting with once-) are never deleted by a sync: EventBridge removes them itself after they fire. enable(), overrideCron() and resetCron() sync as well.

Manual execution

One-time scheduling

Schedule a job to run once at a specific future time via EventBridge. The EventBridge schedule self-destructs after firing. A record is stored in taskbridge_jobs (run_once_at is set) so the scheduled time is visible in the UI until the row is pruned.

The datetime must be in the future. It is interpreted in config('app.timezone') and converted to UTC for the EventBridge at() expression.

Run tracking

The schedule is named once-{identifier}-{8 random characters} (shortened when the identifier is long, see the 64-character limit), and the SQS payload carries that name under taskbridge_schedule. When the schedule fires, the queue listener finds the one-time row by the name, moves the pending run to Running and then to Succeeded or Failed, and stamps last_run_at and last_status on the one-time row. The run keeps the job_class and aws_schedule_name it was created with; the job's own output is merged on top. The recurring row of the same class is left alone, and a recurring schedule is tracked on the row whose identifier it is, so a one-time row for the same class never absorbs its runs.

Without database rows

Every call above also writes a taskbridge_jobs row and a pending taskbridge_job_runs row so the schedule shows up in the UI. A caller that creates one-time schedules in bulk (wake-up calls for thousands of workflow runs, say) should not fill the Scheduled Jobs list with them. Pass log: false to create the EventBridge schedule only:

Nothing is written to the database, and nothing is logged when the schedule fires either: there is no row to track the run on, and the recurring row of the same class is left alone. The returned ScheduledJobRun is transient (not saved) and carries the schedule name in output['aws_schedule_name']; store it if the schedule may have to be cancelled later:

Use log: false as well for job classes that are not registered with TaskBridge. The queue listener only tracks registered classes, so the pending run row of an unregistered class would never be completed.

A sync of the recurring jobs leaves one-time schedules alone, logged or not.

Enable / disable jobs

Cron override

Override the cron expression without editing the job class — useful for environment-specific schedules:

Both 5-part standard cron (minute hour dom month dow) and 6-part AWS format (minute hour dom month dow year) are accepted.

Configuration reference

Built-in maintenance jobs

All three built-in jobs are listed in config/taskbridge.php under jobs. PruneRunsJob is enabled by default; uncomment the others as needed.

PruneRunsJob

Deletes run log entries older than a configurable retention window. Runs daily at 03:00.

The retention period is resolved in this order:

1. The $retentionDays constructor argument — configured via the Filament UI when creating or editing the job record
2. taskbridge.logging.retention_days config value
3. Hard-coded fallback of 30 days

PruneOnceSchedulesJob

Deletes taskbridge_jobs rows where run_once_at is set and the scheduled time is older than the configured retention window. Keeps the table clean after one-time schedules have fired. Runs daily at 03:00.

Constructor argument ?int $retentionDays = null — configure per-environment in the UI, or falls back to taskbridge.logging.retention_days.

CheckMissedJobs

Monitors jobs that haven't run within twice their expected cron interval and dispatches a JobMissed event. Runs every hour. Listen to this event to send alerts.

Requires taskbridge.monitoring.notify_on_miss to be true to take effect.

Events

Listen to these events to add custom behaviour:

Custom models

Extend and override the default models for custom logic:

Translating status labels

Publish the language files:

This creates lang/vendor/taskbridge/en/enums.php. Copy and translate for other locales.

Running the tests

This package was fully built with Claude Code.