README

在您的 Symfony 应用程序中安排 Cron 任务（命令/回调/bash 脚本）。大多数应用程序都有需要在特定间隔运行的任务。此包允许您在代码中定义这些任务。任务定义（任务）与应用程序的任何其他功能一样进行版本控制。服务器上每分钟运行一次的单个 Cron 条目（php bin/console schedule:run）执行到期任务。

此包的灵感和部分 API/代码来自 Laravel 的任务调度功能。

1. 安装
2. 快速入门
3. 定义调度
   1. ScheduleBuilder 服务
   2. 您的 Kernel
   3. 包配置
   4. AsScheduledTask 属性
   5. 自调度命令
   6. 时区
   7. 调度扩展
      1. 过滤器
      2. 回调
      3. ping webhook
      4. 失败时发送电子邮件
      5. 失败时通知
      6. 在单个服务器上运行
      7. 限制到特定环境
4. 定义任务
   1. 任务类型
      1. CommandTask
      2. CallbackTask
      3. ProcessTask
      4. MessageTask
      5. PingTask
      6. CompoundTask
   2. 任务描述
   3. 频率
      1. Cron 表达式
      2. 流畅表达式构建器
      3. 哈希 Cron 表达式
   4. 任务 ID
   5. 时区
   6. 任务扩展
      1. 过滤器
      2. 回调
      3. ping webhook
      4. 电子邮件输出
      5. 通知输出
      6. 防止重叠
      7. 在单个服务器上运行
      8. 之间
5. 运行调度
   1. 服务器上的 Cron 任务
   2. Symfony Cloud
   3. 替代方案
   4. 强制运行
   5. 处理失败
   6. 确保调度正在运行
   7. 部署期间禁用调度
6. CLI 命令
   1. schedule:list
   2. schedule:run
7. 扩展
   1. 自定义任务
   2. 自定义扩展
   3. 事件
8. 完整配置参考

安装

composer require zenstruck/schedule-bundle

如果不使用 Symfony Flex，请确保启用此包。

快速入门

1. 添加您的调度服务（假设 autowire 和 autoconfiguration 已启用）

   // 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)
           ;
   
           // ...
       }
   }

2. 列出您的任务以诊断任何问题

   php bin/console schedule:list

3. 在您的服务器上添加以下每分钟运行一次的 Cron 任务

   * * * * * cd /path-to-your-project && php bin/console schedule:run >> /dev/null 2>&1
   

有关更多选项，请参阅 定义调度 和 定义任务。

完整配置参考

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.ac.cn/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