|
| 1 | +# Middleware |
| 2 | + |
| 3 | +_Introduced in `0.3`_ |
| 4 | + |
| 5 | +- [Scheduling](#Scheduling) |
| 6 | +- [Execution](#Execution) |
| 7 | +- [Order](#Order) |
| 8 | + |
| 9 | +This bundle defines middleware related to execution and scheduling phases. |
| 10 | + |
| 11 | +Middlewares are "man in the middle" that allows you to interact with the task |
| 12 | +that is about to be scheduled/executed or even after the scheduling/execution. |
| 13 | + |
| 14 | +There are two types of middleware: |
| 15 | + |
| 16 | +- Pre_*Action*_Middleware |
| 17 | +- Post_*Action*_Middleware |
| 18 | + |
| 19 | +Both are called by [SchedulerMiddlewareStack](../src/Middleware/SchedulerMiddlewareStack.php) and/or |
| 20 | +[WorkerMiddlewareStack](../src/Middleware/WorkerMiddlewareStack.php). |
| 21 | + |
| 22 | +## Scheduling |
| 23 | + |
| 24 | +The [SchedulerMiddlewareStack](../src/Middleware/SchedulerMiddlewareStack.php) allows to interact |
| 25 | +during the scheduling process, some points to keep in mind: |
| 26 | + |
| 27 | +- If an error/exception occurs/is thrown during the `preScheduling` process, the scheduling process is stopped. |
| 28 | +- Same thing goes for `postScheduling`. |
| 29 | + |
| 30 | +Defining a "scheduling middleware" is pretty straight-forward: |
| 31 | + |
| 32 | +```php |
| 33 | +<?php |
| 34 | + |
| 35 | +declare(strict_types=1); |
| 36 | + |
| 37 | +namespace App\Middleware; |
| 38 | + |
| 39 | +use SchedulerBundle\Middleware\PostSchedulingMiddlewareInterface; |
| 40 | +use SchedulerBundle\Middleware\PreSchedulingMiddlewareInterface; |
| 41 | +use SchedulerBundle\SchedulerInterface; |
| 42 | +use SchedulerBundle\Task\TaskInterface; |
| 43 | + |
| 44 | +final class FooMiddleware implements PreSchedulingMiddlewareInterface, PostSchedulingMiddlewareInterface |
| 45 | +{ |
| 46 | + public function preScheduling(TaskInterface $task, SchedulerInterface $scheduler) : void |
| 47 | + { |
| 48 | + } |
| 49 | + |
| 50 | + public function postScheduling(TaskInterface $task, SchedulerInterface $scheduler) : void |
| 51 | + { |
| 52 | + } |
| 53 | +} |
| 54 | +``` |
| 55 | + |
| 56 | +Both methods receive the current task (before scheduling it and sending it through transport) along with the scheduler. |
| 57 | + |
| 58 | +## Execution |
| 59 | + |
| 60 | +The [WorkerMiddlewareStack](../src/Middleware/WorkerMiddlewareStack.php) allows to interact |
| 61 | +during the execution process, some points to keep in mind: |
| 62 | + |
| 63 | +- If an error/exception occurs/is thrown during the `preExecute` process, |
| 64 | + the execution process is stopped then the task is stored in the failed task list. |
| 65 | +- Same thing goes for `postExecute`. |
| 66 | + |
| 67 | +Defining an "execution middleware" is pretty straight-forward: |
| 68 | + |
| 69 | +```php |
| 70 | +<?php |
| 71 | + |
| 72 | +declare(strict_types=1); |
| 73 | + |
| 74 | +namespace App\Middleware; |
| 75 | + |
| 76 | +use SchedulerBundle\Middleware\PostExecutionMiddlewareInterface; |
| 77 | +use SchedulerBundle\Middleware\PreExecutionMiddlewareInterface; |
| 78 | +use SchedulerBundle\Task\TaskInterface; |
| 79 | + |
| 80 | +final class FooMiddleware implements PreExecutionMiddlewareInterface, PostExecutionMiddlewareInterface |
| 81 | +{ |
| 82 | + public function preExecute(TaskInterface $task, array $extraOptions = []): void |
| 83 | + { |
| 84 | + } |
| 85 | + |
| 86 | + public function postExecute(TaskInterface $task) : void |
| 87 | + { |
| 88 | + } |
| 89 | +} |
| 90 | +``` |
| 91 | + |
| 92 | +Both methods receive the current task. |
| 93 | + |
| 94 | +### Extra information |
| 95 | + |
| 96 | +- Implementing both interfaces for each middleware is not required, your middleware can be focused on a single one. |
| 97 | +- A middleware can interact during both processes by implementing the desired interfaces, |
| 98 | + each stack sorts related middlewares before interacting with them. |
| 99 | + |
| 100 | +## Order |
| 101 | + |
| 102 | +Middlewares can be ordered using an integer, this approach allows to define a specific order |
| 103 | +when executing middlewares, this can be useful to prioritize specific behaviour. |
| 104 | + |
| 105 | +This behaviour is implemented via [OrderedMiddlewareInterface](../src/Middleware/OrderedMiddlewareInterface.php): |
| 106 | + |
| 107 | +```php |
| 108 | +<?php |
| 109 | + |
| 110 | +declare(strict_types=1); |
| 111 | + |
| 112 | +use SchedulerBundle\Middleware\OrderedMiddlewareInterface; |
| 113 | + |
| 114 | +final class FooMiddleware implements OrderedMiddlewareInterface |
| 115 | +{ |
| 116 | + public function getPriority() : int |
| 117 | + { |
| 118 | + return 1; |
| 119 | + } |
| 120 | +} |
| 121 | +``` |
| 122 | + |
| 123 | +_Note: The lower the priority, the earlier the middleware is called._ |
0 commit comments