zenstruck / schedule-bundle
Schedule Cron jobs (commands/callbacks/bash scripts) within your Symfony application.
Fund package maintenance!
kbond
Installs: 619 930
Dependents: 3
Suggesters: 0
Security: 0
Stars: 386
Watchers: 13
Forks: 20
Open Issues: 13
Type:symfony-bundle
Requires
- php: >=8.0
- dragonmantank/cron-expression: ^2.3|^3.0
- symfony/console: ^5.4|^6.0|^7.0
- symfony/dependency-injection: ^5.4|^6.0|^7.0
- symfony/event-dispatcher: ^5.4|^6.0|^7.0
- symfony/http-kernel: ^5.4|^6.0|^7.0
Requires (Dev)
- lorisleiva/cron-translator: ^0.1.0|^0.3.1|^0.4.0
- matthiasnoback/symfony-dependency-injection-test: ^4.1|^5.0
- phpstan/phpstan: ^1.4
- phpunit/phpunit: ^9.5
- psr/log: ^1.1
- symfony/framework-bundle: ^5.4|^6.0|^7.0
- symfony/http-client: ^5.4|^6.0|^7.0
- symfony/lock: ^5.4|^6.0|^7.0
- symfony/mailer: ^5.4|^6.0|^7.0
- symfony/messenger: ^5.4|^6.0|^7.0
- symfony/notifier: ^5.4|^6.0|^7.0
- symfony/phpunit-bridge: ^6.2|^7.0
- symfony/process: ^5.4|^6.0|^7.0
Suggests
- lorisleiva/cron-translator: Displays human readable cron expression in schedule:list
- symfony/http-client: Allows usage of ping* extensions
- symfony/lock: Allows usage of withoutOverlapping and onSingleServer extensions
- symfony/mailer: Allows usage of email* extensions
- symfony/notifier: Allows usage of notify* extensions
- symfony/process: Allows usage of ProcessTask
README
Schedule Cron jobs (commands/callbacks/bash scripts) within your Symfony
application. Most applications have jobs that need to run at specific intervals.
This bundle enables you to define these jobs in your code. Job definitions (tasks)
are version controlled like any other feature of your application. A single Cron
entry (php bin/console schedule:run
) on your server running every minute executes due
tasks.
The inspiration and some of the API/code for this Bundle comes from Laravel's Task Scheduling feature.
- Installation
- Quick Start
- Defining the Schedule
- Defining Tasks
- Running the Schedule
- CLI Commands
- Extending
- Full Configuration Reference
Installation
composer require zenstruck/schedule-bundle
If not using Symfony Flex, be sure to enable the bundle.
Quick Start
-
Add your schedule service (assumes autowire and autoconfiguration enabled):
// src/Schedule/AppScheduleBuilder.php namespace App\Schedule; use Zenstruck\ScheduleBundle\Schedule; use Zenstruck\ScheduleBundle\Schedule\ScheduleBuilder; class AppScheduleBuilder implements ScheduleBuilder { public function buildSchedule(Schedule $schedule): void { $schedule ->timezone('UTC') ->environments('prod') ; $schedule->addCommand('app:send-weekly-report --detailed') ->description('Send the weekly report to users.') ->sundays() ->at(1) ; // ... } }
-
List your tasks to diagnose any problems:
php bin/console schedule:list
-
Add the following Cron job on your server running every minute:
* * * * * cd /path-to-your-project && php bin/console schedule:run >> /dev/null 2>&1
See Defining the Schedule and Defining Tasks for more options.
Full Configuration Reference
zenstruck_schedule: # The LockFactory service to use for the without overlapping extension without_overlapping_lock_factory: null # Example: lock.default.factory # The LockFactory service to use for the single server extension - be sure to use a "remote store" (https://symfony.com/doc/current/components/lock.html#remote-stores) single_server_lock_factory: null # Example: lock.redis.factory # The HttpClient service to use http_client: null # Example: http_client # The default timezone for tasks (override at task level), null for system default timezone: null # Example: America/New_York messenger: enabled: false # The message bus to use message_bus: message_bus mailer: enabled: false # The mailer service to use service: mailer # The default "from" email address (use if no mailer default from is configured) default_from: null # The default "to" email address (can be overridden by extension) default_to: null # The prefix to use for email subjects (use to distinguish between different application schedules) subject_prefix: null # Example: "[Acme Inc Website]" notifier: enabled: false # The notifier service to use service: notifier # The default channel (can use a string, or array of channels) default_channel: null # The default email address for email notifications default_email: null # The default phone number for SMS notifications (can be overridden by extension) default_phone: null # The prefix to use for notification subjects (use to distinguish between different application schedules) subject_prefix: null # Example: "[Acme Inc Website]" schedule_extensions: # Set the environment(s) you only want the schedule to run in. environments: [] # Example: [prod, staging] # Run schedule on only one server on_single_server: enabled: false # Maximum expected lock duration in seconds ttl: 3600 # Send email if schedule fails (alternatively enable by passing a "to" email) email_on_failure: enabled: false # Email address to send email to (leave blank to use "zenstruck_schedule.mailer.default_to") to: null # Email subject (leave blank to use extension default) subject: null # Send notification if schedule fails (alternatively enable by passing a channel) notify_on_failure: enabled: false # Channel to send notification to (leave blank to use "zenstruck_schedule.notifier.default_channel") channel: null # Notification subject (leave blank to use extension default) subject: null # Email address for email notifications (leave blank to use extension default) email: null # Phone number for SMS notifications (leave blank to use extension default) phone: null # Ping a url before schedule runs (alternatively enable by passing a url) ping_before: enabled: false # The url to ping url: ~ # Required # The HTTP method to use method: GET # See HttpClientInterface::OPTIONS_DEFAULTS options: [] # Ping a url after schedule runs (alternatively enable by passing a url) ping_after: enabled: false # The url to ping url: ~ # Required # The HTTP method to use method: GET # See HttpClientInterface::OPTIONS_DEFAULTS options: [] # Ping a url if the schedule successfully ran (alternatively enable by passing a url) ping_on_success: enabled: false # The url to ping url: ~ # Required # The HTTP method to use method: GET # See HttpClientInterface::OPTIONS_DEFAULTS options: [] # Ping a url if the schedule failed (alternatively enable by passing a url) ping_on_failure: enabled: false # The url to ping url: ~ # Required # The HTTP method to use method: GET # See HttpClientInterface::OPTIONS_DEFAULTS options: [] tasks: # Example: - task: send:sales-report --detailed frequency: '0 * * * *' description: Send sales report hourly without_overlapping: ~ only_between: 9-17 ping_on_success: https://example.com/hourly-report-health-check email_on_failure: sales@example.com notify_on_failure: chat/slack # Prototype - # Defaults to CommandTask, prefix with "bash:" to create ProcessTask, prefix url with "ping:" to create PingTask, pass array of commands to create CompoundTask (optionally keyed by description) task: ~ # Required, Example: "my:command arg1 --option1=value", "bash:/bin/my-script" or "ping:https://example.com" # Cron expression frequency: ~ # Required, Example: '0 * * * *' # Task description description: null # The timezone for this task, null for system default timezone: null # Example: America/New_York # Prevent task from running if still running from previous run without_overlapping: enabled: false # Maximum expected lock duration in seconds ttl: 86400 # Only run between given times (alternatively enable by passing a range, ie "9:00-17:00" only_between: enabled: false start: ~ # Required, Example: 9:00 end: ~ # Required, Example: 17:00 # Skip when between given times (alternatively enable by passing a range, ie "17:00-06:00" unless_between: enabled: false start: ~ # Required, Example: 17:00 end: ~ # Required, Example: 06:00 # Ping a url before task runs (alternatively enable by passing a url) ping_before: enabled: false # The url to ping url: ~ # Required # The HTTP method to use method: GET # See HttpClientInterface::OPTIONS_DEFAULTS options: [] # Ping a url after task runs (alternatively enable by passing a url) ping_after: enabled: false # The url to ping url: ~ # Required # The HTTP method to use method: GET # See HttpClientInterface::OPTIONS_DEFAULTS options: [] # Ping a url if the task successfully ran (alternatively enable by passing a url) ping_on_success: enabled: false # The url to ping url: ~ # Required # The HTTP method to use method: GET # See HttpClientInterface::OPTIONS_DEFAULTS options: [] # Ping a url if the task failed (alternatively enable by passing a url) ping_on_failure: enabled: false # The url to ping url: ~ # Required # The HTTP method to use method: GET # See HttpClientInterface::OPTIONS_DEFAULTS options: [] # Send email after task runs (alternatively enable by passing a "to" email) email_after: enabled: false # Email address to send email to (leave blank to use "zenstruck_schedule.mailer.default_to") to: null # Email subject (leave blank to use extension default) subject: null # Send email if task fails (alternatively enable by passing a "to" email) email_on_failure: enabled: false # Email address to send email to (leave blank to use "zenstruck_schedule.mailer.default_to") to: null # Email subject (leave blank to use extension default) subject: null # Send notification after task runs (alternatively enable by passing a channel) notify_after: enabled: false # Channel to send notification to (leave blank to use "zenstruck_schedule.notifier.default_channel") channel: null # Notification subject (leave blank to use extension default) subject: null # Email to send email notifications to (leave blank to use extension default) email: null # Phone number for SMS notifications (leave blank to use extension default) phone: null # Send email if task fails (alternatively enable by passing a "to" email) notify_on_failure: enabled: false # Channel to send notification to (leave blank to use "zenstruck_schedule.notifier.default_channel") channel: null # Notification subject (leave blank to use extension default) subject: null # Email to send email notifications to (leave blank to use extension default) email: null # Phone number for SMS notifications (leave blank to use extension default) phone: null