feat(task): fluent expression (#26)

* feat(task): fluent expression WIP

* refactor(task): expression

* refactor(core): expression builders WIP

* tests(expression): progress

* refactor(core): progress on ExpressionBuilder

* refactor(core): ExpressionBuilderr

* tests(command): ConsumeTaskCommand improved

* tests(bridge): Doctrine connection setUp() improved

* tests(transport): LongTailTransport improved

* refactor(core): psalm notices improved

* refactor(core): improvements

* refactor(policy): uasort improved

* refactor(core): rector

* build(composer): extra deps removed

* refactor(core): doc & expression definition improved

Author: Guikingone

CHANGELOG.md

@@ -9,6 +9,7 @@ CHANGELOG
 * `Scheduler::yieldTask()` introduced (see https://github.com/Guikingone/SchedulerBundle/pull/19)
 * `scheduler:yield` command added (see https://github.com/Guikingone/SchedulerBundle/pull/19)
 * Documentation improvements (see https://github.com/Guikingone/SchedulerBundle/pull/19)
+* "Fluent" expressions (see https://github.com/Guikingone/SchedulerBundle/pull/26)
 
 0.2.0
 -----

README.md

@@ -76,6 +76,7 @@ When a task is configured, time to execute it, two approaches can be used:
 ## Documentation
 
 * [Usage](doc/usage.md)
+* [Best practices](doc/best_practices.md)
 * [Tasks](doc/tasks.md)
 * [Transports](doc/transport.md)
 * [Commands](doc/command.md)

composer.json

@@ -107,6 +107,7 @@
         "phpstan/phpstan-doctrine": "^0.12.19",
         "phpstan/phpstan-phpunit": "^0.12",
         "phpstan/phpstan-symfony": "^0.12.19",
+        "psalm/plugin-symfony": "^2.1",
         "phpunit/phpunit": "^9.5",
         "psalm/plugin-phpunit": "^0.15",
         "psr/cache": "^1.0",

doc/best_practices.md

@@ -0,0 +1,21 @@
+# Best practices
+
+- [Transports](#Transports)
+- [External ressources](#external-ressources)
+
+## Transports
+
+When using transports that rely on network calls, you must keep in mind that these transports
+can fail to retrieve/create and so on, it could be a good idea to use the fail over or round robin
+transport to prevent any errors:
+
+```yaml
+scheduler_bundle:
+    transport:
+        dsn: 'failover://(doctrine://... || fs://last_in_first_out)'
+```
+
+## External ressources
+
+Consider exploring this [article](https://www.endpoint.com/blog/2008/12/08/best-practices-for-cron)
+to have a better idea of general approaches related to repetitive tasks.

doc/scheduler.md

@@ -82,4 +82,26 @@ final class Foo
         $scheduler->yieldTask('foo', true);
     }
 }
-```
+```
+
+### Pausing task
+
+_Introduced in `0.3`_
+
+Pausing a task using the asynchronous approach requires to use the method second argument:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use SchedulerBundle\SchedulerInterface;
+
+final class Foo
+{
+    public function __invoke(SchedulerInterface $scheduler): void
+    {
+        $scheduler->pause('foo', true);
+    }
+}
+```

doc/tasks.md

@@ -2,20 +2,21 @@
 
 This bundle provides multiple type of tasks:
 
-- [ShellTask](tasks.md#ShellTask)
-- [CommandTask](tasks.md#CommandTask)
-- [ChainedTask](tasks.md#ChainedTask)
-- [CallbackTask](tasks.md#CallbackTask)
+- [ShellTask](#ShellTask)
+- [CommandTask](#CommandTask)
+- [ChainedTask](#ChainedTask)
+- [CallbackTask](#CallbackTask)
 - HttpTask
 - MessengerTask
-- [NotificationTask](tasks.md#NotificationTask)
-- [NullTask](tasks.md#NullTask)
+- [NotificationTask](#NotificationTask)
+- [NullTask](#NullTask)
 
 ## Extra
 
-- [Task callbacks](tasks.md#Callbacks)
-- [Task notifications](tasks.md#Notifications)
-- [Options](tasks.md#Options)
+- [Task callbacks](#Callbacks)
+- [Task notifications](#Notifications)
+- [Options](#Options)
+- [Fluent Expression](#fluent-expressions)
 
 ## ShellTask
 
@@ -180,3 +181,73 @@ Each task can define a set of notification:
 ## Options
 
 Each task has its own set of options, the full list is documented in [AbstractTask](../src/Task/AbstractTask.php).
+
+## Fluent expressions
+
+_Introduced in `0.3`_
+
+This bundle supports defining tasks expression via basic cron syntax:
+
+```bash
+* * * * *
+```
+
+Even if this approach is mostly recommended, you may need to use a more "user-friendly" syntax, to do so,
+this bundle allows you to use "fluent" expressions thanks to [strtotime](https://www.php.net/manual/fr/function.strtotime) and "computed" expressions:
+
+### Strtotime
+
+Scheduling a task with a "fluent" expression is as easy as it sounds:
+
+```yaml
+scheduler_bundle:
+  # ...
+  tasks:
+    foo:
+      type: 'shell'
+      command: ['ls', '-al']
+      expression: 'next monday 10:00'
+```
+
+Every expression supported by [strtotime](https://www.php.net/manual/fr/function.strtotime) is allowed.
+
+_Note: Keep in mind that using a fluent expression does not lock the amount of execution of the task, 
+if it should only run once, you must consider using the `single_run` option._
+
+_Note: If you need to generate the expression thanks to a specific timezone, the `timezone` option can be used:_
+
+```yaml
+scheduler_bundle:
+  # ...
+  tasks:
+    foo:
+      type: 'shell'
+      command: ['ls', '-al']
+      expression: 'next monday 10:00'
+      timezone: 'Europe/Paris'
+```
+
+*The default value is `UTC`*
+
+### Computed expressions
+
+A "computed" expression is a special expression that use `#` for specific parts of the expression:
+
+```yaml
+scheduler_bundle:
+  # ...
+  tasks:
+    foo:
+      type: 'shell'
+      command: ['ls', '-al']
+      expression: '# * * * *'
+```
+
+The final expression will contain an integer 0 and 59 in the minute field of the expression 
+as described in the [man page](https://crontab.guru/crontab.5.html).
+
+_Note: `#` can be used in multiple parts of the expression at the same time._
+
+### Notices
+
+Both computed and fluent expressions cannot be used *outside* of the configuration definition.

psalm.xml

@@ -14,5 +14,5 @@
     </projectFiles>
     <plugins>
         <pluginClass class="Psalm\PhpUnitPlugin\Plugin"/>
-    </plugins>
+        <pluginClass class="Psalm\SymfonyPsalmPlugin\Plugin"/></plugins>
 </psalm>

src/Command/ConsumeTasksCommand.php

@@ -36,7 +36,7 @@ final class ConsumeTasksCommand extends Command
     private WorkerInterface $worker;
 
     /**
-     * @var string|mixed
+     * @var string|null
      */
     protected static $defaultName = 'scheduler:consume';
 
@@ -162,6 +162,10 @@ private function registerOutputSubscriber(SymfonyStyle $style): void
     {
         $this->eventDispatcher->addListener(TaskExecutedEvent::class, function (TaskExecutedEvent $event) use ($style): void {
             $output = $event->getOutput();
+            if (null === $output) {
+                return;
+            }
+
             if (null === $output->getOutput()) {
                 return;
             }

src/Command/ListFailedTasksCommand.php

@@ -24,7 +24,7 @@ final class ListFailedTasksCommand extends Command
     private WorkerInterface $worker;
 
     /**
-     * @var string
+     * @var string|null
      */
     protected static $defaultName = 'scheduler:list:failed';
 

src/Command/ListTasksCommand.php

@@ -28,7 +28,7 @@ final class ListTasksCommand extends Command
     private SchedulerInterface $scheduler;
 
     /**
-     * @var string
+     * @var string|null
      */
     protected static $defaultName = 'scheduler:list';