Skip to content

Commit

Permalink
Merge pull request #62 from kbond/invokable-service-tasks
Browse files Browse the repository at this point in the history 
Add `AsScheduledTask` attribute
  • Loading branch information
@kbond
kbond authored Apr 14, 2022
2 parents 30bb9d1 + 9c224b6 commit 7c8a225
Show file tree
Hide file tree
Showing 25 changed files with 586 additions and 69 deletions.
12 changes: 12 additions & 0 deletions .editorconfig
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
root = true

[*]
charset = utf-8
end_of_line = lf
indent_size = 4
indent_style = space
insert_final_newline = true
trim_trailing_whitespace = true

[*.yml]
indent_size = 2
7 changes: 3 additions & 4 deletions .github/workflows/ci.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ jobs:
matrix:
php: [7.4, 8.0, 8.1]
deps: [hightest]
symfony: [4.4.*, 5.3.*, 5.4.*]
symfony: [4.4.*, 5.4.*]
include:
- php: 7.2
deps: lowest
Expand All @@ -36,7 +36,7 @@ jobs:
code-coverage:
uses: zenstruck/.github/.github/workflows/php-coverage-codecov.yml@main
with:
php: 7.4
php: 8.1
phpunit: simple-phpunit

composer-validate:
Expand All @@ -45,8 +45,7 @@ jobs:
cs-check:
uses: zenstruck/.github/.github/workflows/php-cs-fixer.yml@main
with:
php: 7.2
version: 3.4
php: 8.0

sca:
uses: zenstruck/.github/.github/workflows/php-stan.yml@main
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,4 @@
/build/
/.php-cs-fixer.cache
/.phpunit.result.cache
/var/
11 changes: 6 additions & 5 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,10 @@ Task Scheduling feature](https://laravel.com/docs/master/scheduling).
1. [ScheduleBuilder Service](doc/define-schedule.md#schedulebuilder-service)
2. [Your Kernel](doc/define-schedule.md#your-kernel)
3. [Bundle Configuration](doc/define-schedule.md#bundle-configuration)
4. [Self-Scheduling Commands](doc/define-schedule.md#self-scheduling-commands)
5. [Timezone](doc/define-schedule.md#timezone)
6. [Schedule Extensions](doc/define-schedule.md#schedule-extensions)
4. [`AsScheduledTask` Attribute](doc/define-schedule.md#asscheduledtask-attribute)
5. [Self-Scheduling Commands](doc/define-schedule.md#self-scheduling-commands)
6. [Timezone](doc/define-schedule.md#timezone)
7. [Schedule Extensions](doc/define-schedule.md#schedule-extensions)
1. [Filters](doc/define-schedule.md#filters)
2. [Callbacks](doc/define-schedule.md#callbacks)
3. [Ping Webhook](doc/define-schedule.md#ping-webhook)
Expand Down Expand Up @@ -104,7 +105,7 @@ $ composer require zenstruck/schedule-bundle
->sundays()
->at(1)
;

// ...
}
}
Expand Down Expand Up @@ -239,7 +240,7 @@ zenstruck_schedule:
tasks:

# Example:
-
-
task: send:sales-report --detailed
frequency: '0 * * * *'
description: Send sales report hourly
Expand Down
1 change: 1 addition & 0 deletions composer.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
"matthiasnoback/symfony-dependency-injection-test": "^4.1",
"phpstan/phpstan": "^1.4",
"psr/log": "^1.1",
"symfony/framework-bundle": "^4.4|^5.0|^6.0",
"symfony/http-client": "^4.3|^5.0|^6.0",
"symfony/lock": "^4.4|^5.0|^6.0",
"symfony/mailer": "^4.4|^5.0|^6.0",
Expand Down
86 changes: 43 additions & 43 deletions doc/cli-commands.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Consider the following schedule definition:
zenstruck_schedule:
schedule_extensions:
on_single_server: ~

tasks:
- task: send-sales-report --hourly
description: Send the hourly sales report
Expand All @@ -54,16 +54,16 @@ $ php bin/console schedule:list
2 Scheduled Tasks Configured
============================
----------------- ------------------------------ ------------ ------------------------------------------------- ---------------------------
Type Description Extensions Frequency Next Run
----------------- ------------------------------ ------------ ------------------------------------------------- ---------------------------
[!] CommandTask Send the hourly sales report 2 15 * * * 1-5 (Once an hour 5 days a week) 2020-01-22T14:15:00-05:00
CommandTask Send the weekly sales report 1 0 1 * * 1-5 (Every day 5 days a week at 1:00am) 2020-01-23T01:00:00-05:00
----------------- ------------------------------ ------------ ------------------------------------------------- ---------------------------
----------------- ------------------------------ ------------ ------------------------------------------------- ---------------------------
Type Description Extensions Frequency Next Run
----------------- ------------------------------ ------------ ------------------------------------------------- ---------------------------
[!] CommandTask Send the hourly sales report 2 15 * * * 1-5 (Once an hour 5 days a week) 2020-01-22T14:15:00-05:00
CommandTask Send the weekly sales report 1 0 1 * * 1-5 (Every day 5 days a week at 1:00am) 2020-01-23T01:00:00-05:00
----------------- ------------------------------ ------------ ------------------------------------------------- ---------------------------
[WARNING] 1 task issue:
[ERROR] To use the email extension you must configure a mailer (config path: "zenstruck_schedule.mailer").
[ERROR] To use the email extension you must configure a mailer (config path: "zenstruck_schedule.mailer").
! [NOTE] For more details, run php bin/console schedule:list --detail
Expand All @@ -90,13 +90,13 @@ $ php bin/console schedule:list --detail
(1/2) CommandTask: Send the hourly sales report
-----------------------------------------------
------------------- ----------------------------------------------------
ID 9d2023944f540105dd47f7f314138fe92e40300c
Class Zenstruck\ScheduleBundle\Schedule\Task\CommandTask
Command Arguments --hourly
Frequency 15 * * * 1-5 (Once an hour 5 days a week)
Next Run Wed, Jan 22, 2020 @ 2:15 (America/New_York -0500)
------------------- ----------------------------------------------------
------------------- ----------------------------------------------------
ID 9d2023944f540105dd47f7f314138fe92e40300c
Class Zenstruck\ScheduleBundle\Schedule\Task\CommandTask
Command Arguments --hourly
Frequency 15 * * * 1-5 (Once an hour 5 days a week)
Next Run Wed, Jan 22, 2020 @ 2:15 (America/New_York -0500)
------------------- ----------------------------------------------------
// 2 Task Extensions:
Expand All @@ -105,18 +105,18 @@ $ php bin/console schedule:list --detail
[WARNING] 1 issue with this task:
[ERROR] To use the email extension you must configure a mailer (config path: "zenstruck_schedule.mailer").
[ERROR] To use the email extension you must configure a mailer (config path: "zenstruck_schedule.mailer").
(2/2) CommandTask: Send the weekly sales report
-----------------------------------------------
------------------- ----------------------------------------------------
ID 92e08f41a257b69fe877e132559fb7396e308309
Class Zenstruck\ScheduleBundle\Schedule\Task\CommandTask
Command Arguments --daily
Frequency 0 1 * * 1-5 (Every day 5 days a week at 1:00am)
Next Run Thu, Jan 23, 2020 @ 1:00 (America/New_York -0500)
------------------- ----------------------------------------------------
------------------- ----------------------------------------------------
ID 92e08f41a257b69fe877e132559fb7396e308309
Class Zenstruck\ScheduleBundle\Schedule\Task\CommandTask
Command Arguments --daily
Frequency 0 1 * * 1-5 (Every day 5 days a week at 1:00am)
Next Run Thu, Jan 23, 2020 @ 1:00 (America/New_York -0500)
------------------- ----------------------------------------------------
// 1 Task Extension:
Expand Down Expand Up @@ -152,12 +152,12 @@ $ php bin/console schedule:list
2 Scheduled Tasks Configured
============================
------------- ------------------------------ ------------ ------------------------------------------------- ---------------------------
Type Description Extensions Frequency Next Run
------------- ------------------------------ ------------ ------------------------------------------------- ---------------------------
CommandTask Send the hourly sales report 2 15 * * * 1-5 (Once an hour 5 days a week) 2020-01-22T14:15:00-05:00
CommandTask Send the weekly sales report 1 0 1 * * 1-5 (Every day 5 days a week at 1:00am) 2020-01-23T01:00:00-05:00
------------- ------------------------------ ------------ ------------------------------------------------- ---------------------------
------------- ------------------------------ ------------ ------------------------------------------------- ---------------------------
Type Description Extensions Frequency Next Run
------------- ------------------------------ ------------ ------------------------------------------------- ---------------------------
CommandTask Send the hourly sales report 2 15 * * * 1-5 (Once an hour 5 days a week) 2020-01-22T14:15:00-05:00
CommandTask Send the weekly sales report 1 0 1 * * 1-5 (Every day 5 days a week at 1:00am) 2020-01-23T01:00:00-05:00
------------- ------------------------------ ------------ ------------------------------------------------- ---------------------------
! [NOTE] For more details, run php bin/console schedule:list --detail
Expand All @@ -181,13 +181,13 @@ $ php bin/console schedule:list --detail
(1/2) CommandTask: Send the hourly sales report
-----------------------------------------------
------------------- ----------------------------------------------------
ID 9d2023944f540105dd47f7f314138fe92e40300c
Class Zenstruck\ScheduleBundle\Schedule\Task\CommandTask
Command Arguments --hourly
Frequency 15 * * * 1-5 (Once an hour 5 days a week)
Next Run Wed, Jan 22, 2020 @ 2:15 (America/New_York -0500)
------------------- ----------------------------------------------------
------------------- ----------------------------------------------------
ID 9d2023944f540105dd47f7f314138fe92e40300c
Class Zenstruck\ScheduleBundle\Schedule\Task\CommandTask
Command Arguments --hourly
Frequency 15 * * * 1-5 (Once an hour 5 days a week)
Next Run Wed, Jan 22, 2020 @ 2:15 (America/New_York -0500)
------------------- ----------------------------------------------------
// 2 Task Extensions:
Expand All @@ -197,13 +197,13 @@ $ php bin/console schedule:list --detail
(2/2) CommandTask: Send the weekly sales report
-----------------------------------------------
------------------- ----------------------------------------------------
ID 92e08f41a257b69fe877e132559fb7396e308309
Class Zenstruck\ScheduleBundle\Schedule\Task\CommandTask
Command Arguments --daily
Frequency 0 1 * * 1-5 (Every day 5 days a week at 1:00am)
Next Run Thu, Jan 23, 2020 @ 1:00 (America/New_York -0500)
------------------- ----------------------------------------------------
------------------- ----------------------------------------------------
ID 92e08f41a257b69fe877e132559fb7396e308309
Class Zenstruck\ScheduleBundle\Schedule\Task\CommandTask
Command Arguments --daily
Frequency 0 1 * * 1-5 (Every day 5 days a week at 1:00am)
Next Run Thu, Jan 23, 2020 @ 1:00 (America/New_York -0500)
------------------- ----------------------------------------------------
// 1 Task Extension:
Expand Down
60 changes: 59 additions & 1 deletion doc/define-schedule.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ and [schedule extensions](#schedule-extensions) can be configured:
zenstruck_schedule:
timezone: UTC
ping_on_success: https://example.com/schedule-success

tasks:
- task: app:send-weekly-report --detailed
frequency: '0 1 * * 0' # sundays @ 1am
Expand All @@ -85,11 +85,69 @@ zenstruck_schedule:
unless_between: 11-13 # except at lunch
```
## `AsScheduledTask` Attribute

_**NOTE:** PHP 8+ and Symfony 5.4+ required to use this feature._

You can mark [invokable services](#invokable-asscheduledtask-services) and
[console commands](#asscheduledtask-console-commands) with the
`Zenstruck\ScheduleBundle\Attribute\AsScheduledTask` attribute to _self-schedule_ them.

### Invokable `AsScheduledTask` Services

Services can be marked with `AsScheduledTask` to be scheduled (as a
[`CallbackTask`](define-tasks.md#callbacktask)). These services must be _callable_
(implement `__invoke()`) or have a custom method configured. The method must be
public and have no required parameters.

```php
use Zenstruck\ScheduleBundle\Attribute\AsScheduledTask;
#[AsScheduledTask('#daily')]
#[AsScheduledTask('#weekly')] // can be scheduled multiple times
#[AsScheduledTask('#monthly', description: 'some description')] // optionally set a description
#[AsScheduledTask('#daily', method: 'someOtherMethod')] // use a different method
class MyService
{
public function __invoke(): void
{
}
public function someOtherMethod(): void
{
}
}
```

### `AsScheduledTask` Console Commands

Console commands can be marked with `AsScheduledTask` to _self-schedule_ them.

**NOTE:** Use [Self-Scheduling Commands](#self-scheduling-commands) if you require more
fine-grained options.

```php
use Symfony\Component\Console\Command;
use Zenstruck\ScheduleBundle\Attribute\AsScheduledTask;
#[AsScheduledTask('#daily')]
#[AsScheduledTask('#weekly')] // can be scheduled multiple times
#[AsScheduledTask('#monthly', description: 'some description')] // optionally set a description
#[AsScheduledTask('#daily', arguments: '--no-interaction --verbose')] // optionally set arguments
class MyCommand extends Command
{
// ...
}
```

## Self-Scheduling Commands

You can make your application's console commands schedule themselves. Have your command
implement [`SelfSchedulingCommand`](../src/Schedule/SelfSchedulingCommand.php):

**NOTE:** If using PHP 8+ and Symfony 5.4+, see [`AsScheduledTask` Console Commands](#asscheduledtask-console-commands)
as a possible alternative.

```php
// src/Command/WeeklyReportCommand.php
Expand Down
14 changes: 7 additions & 7 deletions doc/define-tasks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ task *output*.

$schedule->addCallback(function () {
// do something

return 'task output';
});
```
Expand Down Expand Up @@ -110,7 +110,7 @@ zenstruck_schedule:

```yaml
# config/packages/zenstruck_schedule.yaml
zenstruck_schedule:
tasks:
- task: 'bash:cd %kernel.project_dir% && bin/my-script'
Expand Down Expand Up @@ -148,10 +148,10 @@ $schedule->addMessage(new MyMessage('argument'), [new DelayStamp(10)]);

```yaml
# config/packages/zenstruck_schedule.yaml
zenstruck_schedule:
messenger: ~
# optionally configure the message bus (uses "message_bus" by default)
messenger:
message_bus: my_bus
Expand Down Expand Up @@ -698,7 +698,7 @@ zenstruck_schedule:
default_from: [email protected] # exclude only if a "global from" is defined for your application
subject_prefix: "[Acme Inc]" # optional
```

3. Failed task emails have the subject `[Scheduled Task Failed] CommandTask: failed
task description` (the subject can be configured). The email body has the following
structure:
Expand Down Expand Up @@ -728,7 +728,7 @@ zenstruck_schedule:

## Task Output:

Task's output (if any)
Task's output (if any)
```

### Prevent Overlap
Expand Down Expand Up @@ -763,7 +763,7 @@ zenstruck_schedule:
```console
$ composer require symfony/lock
```

2. *Optionally* customize the `LockFactory` service in your configuration:

```yaml
Expand Down
2 changes: 1 addition & 1 deletion doc/extending.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ Below are some examples of custom extensions:
### Example: Skip Schedule if in maintenance mode

Say your application has the concept of maintenance mode. You want to prevent the
schedule from running in maintenance mode.
schedule from running in maintenance mode.

This example assumes your `Kernel` has an `isInMaintenanceMode()` method.

Expand Down
2 changes: 1 addition & 1 deletion doc/run-schedule.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ The following is an example log file (some context excluded):
[2020-01-20 13:17:13] schedule.INFO: Successfully ran "CommandTask": my:command
[2020-01-20 13:17:13] schedule.INFO: Running "ProcessTask": fdere -dsdfsd
[2020-01-20 13:17:13] schedule.ERROR: Failure when running "ProcessTask": fdere -dsdfsd
[2020-01-20 13:17:13] schedule.INFO: Running "CallbackTask": some callback
[2020-01-20 13:17:13] schedule.INFO: Running "CallbackTask": some callback
[2020-01-20 13:17:13] schedule.CRITICAL: Exception thrown when running "CallbackTask": some callback
[2020-01-20 13:24:11] schedule.INFO: Running "CommandTask": another:command
[2020-01-20 13:24:11] schedule.INFO: Skipped "CommandTask": another:command {"reason":"the reason for skip..."}
Expand Down
2 changes: 2 additions & 0 deletions phpunit.xml.dist
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@
<php>
<ini name="error_reporting" value="-1" />
<server name="SYMFONY_DEPRECATIONS_HELPER" value="max[self]=0&amp;max[direct]=0"/>
<server name="KERNEL_CLASS" value="Zenstruck\ScheduleBundle\Tests\Fixture\Kernel" />
<server name="SHELL_VERBOSITY" value="-1" />
</php>

<testsuites>
Expand Down
Loading

0 comments on commit 7c8a225

Please sign in to comment.