Developed with love by KnpLabs Hire us for your project!
147

schedule-bundle

by zenstruck

Schedule Cron jobs (commands/callbacks/bash scripts) within your Symfony application.

The ScheduleBundle

CI
Scrutinizer Code Quality
Code Coverage

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 (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
.

  1. Installation
  2. Quick Start
  3. Defining the Schedule
    1. ScheduleBuilder Service
    2. Your Kernel
    3. Bundle Configuration
    4. Self-Scheduling Commands
    5. Timezone
    6. Schedule Extensions
      1. Filters
      2. Callbacks
      3. Ping Webhook
      4. Email On Failure
      5. Run on Single Server
      6. Limit to specific environment(s)
  4. Defining Tasks
    1. Task Types
      1. CommandTask
      2. CallbackTask
      3. ProcessTask
      4. PingTask
      5. CompoundTask
    2. Task Description
    3. Frequency
      1. Cron Expression
      2. Fluent Expression Builder
      3. Hashed Cron Expression
    4. Task ID
    5. Timezone
    6. Task Extensions
      1. Filters
      2. Callbacks
      3. Ping Webhook
      4. Email Output
      5. Prevent Overlap
      6. Run on Single Server
      7. Between
  5. Running the Schedule
    1. Cron Job on Server
    2. Symfony Cloud
    3. Alternatives
    4. Force Run
    5. Dealing with Failures
    6. Ensuring Schedule is Running
  6. CLI Commands
    1. schedule:list
    2. schedule:run
  7. Extending
    1. Custom Tasks
    2. Custom Extensions
    3. Events
  8. Full Configuration Reference

Installation

$ composer require zenstruck/schedule-bundle

If not using Symfony Flex, be sure to enable the bundle.

Quick Start

  1. Add your schedule service (assumes autowire and autoconfiguration enabled):

    // src/Schedule/AppScheduleBuilder.php
    
    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)
            ;
    
            // ...
        }
    }
    
  2. List your tasks to diagnose any problems:

    $ bin/console schedule:list
    
  3. Add the following Cron job on your server running every minute:

    * * * * * cd /path-to-your-project && 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

    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]"

    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

        # 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

        # 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
MIT License

Copyright (c) 2020 Kevin Bond

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
  • [minor] adjust CI badge
    By kbond, 4 months ago
  • [minor] fixcs
    By kbond, 4 months ago
  • Merge pull request #8 from kbond/refactor
    By web-flow, 5 months ago
  • [minor] update docs
    By kbond, 5 months ago
  • [bug] only enable ProcessTaskRunner if symfony/process is available
    By kbond, 5 months ago
  • [minor] add MissingDependency exception
    By kbond, 5 months ago
  • [minor] fix typo
    By kbond, 5 months ago
  • [BC BREAK] remove NullTask
    By kbond, 5 months ago
  • [feature] add PingTask
    By kbond, 5 months ago
  • [BC BREAK] rename config keys
    By kbond, 5 months ago
  • [BC BREAK] rename config keys
    By kbond, 5 months ago
  • [BC BREAK] remove Extension interface, extensions are plain objects
    By kbond, 5 months ago
  • [minor] move Extension constants to Task/Schedule
    By kbond, 5 months ago
  • [minor] refactor lock extensions
    By kbond, 5 months ago
  • [BC BREAK] remove the concept of self-handling extensions
    By kbond, 5 months ago
  • [minor] remove SelfHandlingExtension from WithoutOverlappingExtension
    By kbond, 5 months ago
  • [minor] add missing handler message to PingExtension
    By kbond, 5 months ago
  • [minor] remove SelfHandlingExtension from PingExtension
    By kbond, 5 months ago
  • [minor] make CallbackHandler/BetweenTimeHandler always available
    By kbond, 5 months ago
  • [minor] add CallbackHandler
    By kbond, 5 months ago
  • [minor] add BetweenTimeHandler
    By kbond, 5 months ago
  • [BC BREAK] remove the concept of self-running tasks
    By kbond, 5 months ago
  • [minor] merge doc/index.md into README.md
    By kbond, 5 months ago
  • [minor] move to zenstruck github organization
    By kbond, 5 months ago
  • [minor] fix cs
    By kbond, 6 months ago
  • [minor] adjust diff format for php-cs-fixer
    By kbond, 6 months ago
  • [minor] add ci tests for dev dependencies
    By kbond, 6 months ago
  • [minor] simplify github action config
    By kbond, 6 months ago
  • [minor] Adjust license to trigger github to detect
    By web-flow, 7 months ago
  • [feature] add Task::getContext() to show more info in schedule:list --detail
    By kbond, 8 months ago