Rewrite simpler Symfony framework doc (#94)

Author: yann-eugone

docs/getting-started.md

@@ -10,6 +10,11 @@ return [
 ];
 ```
 
+There is few things that can be configured in the bundle at the moment.
+But the most important one will be the `JobExecution` storage:
+- `filesystem` will create a file for each `JobExecution` in `%kernel.project_dir%/var/batch/{execution.jobName}/{execution.id}.json`
+- `dbal` will create a row in a table for each `JobExecution`
+
 ```yaml
 # config/packages/yokai_batch.yaml
 yokai_batch:
@@ -19,115 +24,88 @@ yokai_batch:
         # dbal: ~
 ```
 
-## Job Example
-
-Let say you have a Doctrine ORM entity `App\Entity\User`,
-and a [JSON Lines](https://jsonlines.org/) file with information about these entities.
-
-Your goal is to import this file in the database.
+> **note**: the default storage is `filesystem`, because it only requires a writeable filesystem.
+> But if you already have `doctrine/dbal` in your project, it is highly recommended to use it instead.
+> Because querying `JobExecution` in a filesystem might be slow, specially if you are planing to add UIs on top.
 
-### Job in YAML
+As Symfony supports registering all classes in `src/` as a service,
+we can leverage this behaviour to register all jobs in `src/`.
+We will add a tag to every found class in `src/` that implements `Yokai\Batch\Job\JobInterface`:
 
 ```yaml
-# config/packages/yokai_batch.yaml (or anywhere else)
+# config/services.yaml
 services:
-  job.import_users:
-    class: Yokai\Batch\Job\Item\ItemJob
-    tags: ['yokai_batch.job']
-    arguments:
-      $batchSize: 500
-      $reader: !service
-        class: Yokai\Batch\Job\Item\Reader\Filesystem\JsonLinesReader
-        arguments:
-          $filePath: !service
-            class: Yokai\Batch\Job\Parameters\DefaultParameterAccessor
-            arguments:
-              $accessor: !service
-                class: Yokai\Batch\Job\Parameters\JobExecutionParameterAccessor
-                arguments: ['importFile']
-              $default: '%kernel.project_dir%/var/import/users.jsonl'
-      $processor: !service
-        class: Yokai\Batch\Bridge\Symfony\Serializer\DenormalizeItemProcessor
-        arguments:
-          $denormalizer: '@serializer'
-          $type: App\Entity\User
-      $writer: '@yokai_batch.item_writer.doctrine_orm_object_writer'
+  _defaults:
+    _instanceof:
+      Yokai\Batch\Job\JobInterface:
+        tags: ['yokai_batch.job']
 ```
 
-Then the job will be triggered with its service id:
+## Your first job
+
+In a Symfony project, we will prefer using one class per job, because service discovery is so easy to use.
+But also because it will be very far easier to configure your job using PHP than any other format.
+For instance, there is components that uses `Closure`, has static constructors, ...
+But keep in mind you can register your jobs with any other format of your choice.
 
 ```php
-/** @var \Yokai\Batch\Launcher\JobLauncherInterface $launcher */
-$launcher->launch('job.import_users');
-```
+<?php
 
-### Job in sources
+namespace App\NamespaceOfYourChoice;
 
-Although it is 100% possible to register jobs via a YAML file it can become very tedious.
+use Yokai\Batch\Bridge\Symfony\Framework\JobWithStaticNameInterface;
+use Yokai\Batch\Job\JobInterface;
 
-As Symfony supports registering all classes in `src/` as a service,
-we can leverage this behaviour to register all jobs in `src/`.
+final class NameOfYourJob implements JobInterface, JobWithStaticNameInterface
+{
+    public static function getJobName(): string
+    {
+        return 'job.name';
+    }
 
-```yaml
-# config/services.yaml
-services:
-  _defaults:
-    _instanceof:
-      Yokai\Batch\Job\JobInterface:
-        tags: ['yokai_batch.job']
+    public function execute(JobExecution $jobExecution): void
+    {
+        // your logic here
+    }
+}
 ```
 
+> **note**: when registering jobs with dedicated class, you can use the
+> [JobWithStaticNameInterface](../src/JobWithStaticNameInterface.php) interface
+> to be able to specify the job name of your service.
+> Otherwise, the service id will be used, and in that case, the service id is the FQCN.
+
+### Triggering the job
+Then the job will be triggered with its name (or service id when not specified):
+
 ```php
 <?php
 
-namespace App\Job;
-
-use App\Entity\User;
-use Doctrine\Persistence\ManagerRegistry;
-use Symfony\Component\HttpKernel\KernelInterface;
-use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
-use Yokai\Batch\Bridge\Doctrine\Persistence\ObjectWriter;
-use Yokai\Batch\Bridge\Symfony\Serializer\DenormalizeItemProcessor;
-use Yokai\Batch\Job\AbstractDecoratedJob;
-use Yokai\Batch\Job\Item\ItemJob;
-use Yokai\Batch\Job\Item\Reader\Filesystem\JsonLinesReader;
-use Yokai\Batch\Job\Parameters\DefaultParameterAccessor;
-use Yokai\Batch\Job\Parameters\JobExecutionParameterAccessor;
+namespace App\MyNamespace;
+
 use Yokai\Batch\Storage\JobExecutionStorageInterface;
 
-final class ImportUsersJob extends AbstractDecoratedJob
+final class MyClass
 {
     public function __construct(
-        JobExecutionStorageInterface $executionStorage,
-        ManagerRegistry $doctrine,
-        DenormalizerInterface $denormalizer,
-        KernelInterface $kernel,
+        private JobLauncherInterface $executionStorage,
     ) {
-        parent::__construct(
-            new ItemJob(
-                500,
-                new JsonLinesReader(
-                    new DefaultParameterAccessor(
-                        new JobExecutionParameterAccessor('importFile'),
-                        $kernel->getProjectDir() . '/var/import/users.jsonl'
-                    )
-                ),
-                new DenormalizeItemProcessor($denormalizer, User::class),
-                new ObjectWriter($doctrine),
-                $executionStorage
-            )
-        );
+    }
+
+    public function method(): void
+    {
+        $this->launcher->launch('job.import_users');
     }
 }
 ```
 
-Then the job will be triggered with its service id:
+The job launcher that will be injected depends on the packages you have installed, order matter:
+- if `yokai/batch-symfony-messenger` is installed, you will receive a `Yokai\Batch\Bridge\Symfony\Messenger\DispatchMessageJobLauncher`
+- if `yokai/batch-symfony-console` is installed, you will receive a `Yokai\Batch\Bridge\Symfony\Console\RunCommandJobLauncher`
+- otherwise you will receive a `Yokai\Batch\Launcher\SimpleJobLauncher`
 
-```php
-/** @var \Yokai\Batch\Launcher\JobLauncherInterface $launcher */
-$launcher->launch(\App\Job\ImportUsersJob::class);
-```
+## On the same subject
 
-> **note**: when registering jobs with dedicated class, you can use the
-> [JobWithStaticNameInterface](../src/JobWithStaticNameInterface.php) interface
-> to be able to specify the job name of your service.
+- [What is a job execution storage ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job-execution-storage.md)
+- [What is a job ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job.md)
+- [What is a job launcher ?](https://github.com/yokai-php/batch/blob/0.x/docs/domain/job-launcher.md)