From a8ee53bb6ef9d82ba39bb20bd3d36cf4a7732279 Mon Sep 17 00:00:00 2001
From: Maximilien <maximiliendelangle@gmail.com>
Date: Wed, 12 Jun 2024 14:43:29 +0200
Subject: [PATCH] docs/readmeV2

---
 README.md          |  10 ++-
 docs/README.md     | 110 ++++++++++----------------------
 docs/README_old.md | 152 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 190 insertions(+), 82 deletions(-)
 create mode 100644 docs/README_old.md

diff --git a/README.md b/README.md
index 13f820c5..cb198ae9 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,10 @@
 
 This repository contains sources for all packages from `yokai/batch` suite.
 
+## Documentation
+
+Every package has its own documentation,
+you should start with [core repository documentation](https://github.com/yokai-php/batch-src/blob/0.x/docs/README.md).
 
 ## Packages
 
@@ -30,12 +34,6 @@ And some special packages :
 - [`yokai/batch-symfony-pack`](https://github.com/yokai-php/batch-symfony-pack): Minimal pack for Symfony Framework
 
 
-## Documentation
-
-Every package has its own documentation,
-you should start with [core repository documentation](https://github.com/yokai-php/batch/blob/0.x/README.md).
-
-
 ## Contribution
 
 Please feel free to open an [issue](https://github.com/yokai-php/batch-src/issues)
diff --git a/docs/README.md b/docs/README.md
index 5bad304e..c7973eb1 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,6 +4,40 @@
 composer require yokai/batch
 ```
 
+## What is Batch and how does it work?
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant SimpleJobLauncher
+    participant JobExecutionAccessor
+    participant JobExecutor
+    participant JobExecutionFactory
+    participant JobInterface
+
+    App-->>SimpleJobLauncher: Give job name and parameters
+    activate SimpleJobLauncher
+    SimpleJobLauncher-->>JobExecutionAccessor:  Give job name and parameters
+    activate JobExecutionAccessor
+    JobExecutionAccessor-->>JobExecutionStorageInterface: Try to find an existing job for name and id
+    JobExecutionAccessor-->>JobExecutionFactory: Ask for JobExecution creation if not found in storage
+    JobExecutionAccessor-->>JobExecutionStorageInterface: Store JobExecution if created
+    JobExecutionAccessor-->>SimpleJobLauncher: Give back a JobExecution
+    deactivate JobExecutionAccessor
+    SimpleJobLauncher-->>JobExecutor: Ask for job execution
+    activate JobExecutor
+    JobExecutor-->>JobExecutor: Ensure job can be executed, change job status
+    JobExecutor-->>JobExecutionStorageInterface: Store JobExecution before job starts
+    JobExecutor-->>JobInterface: Triggers job execution
+    JobInterface-->>JobInterface: Where your code lives
+    JobExecutor-->>JobExecutor: Try/catch all errors and convert to stored failures
+    JobExecutor-->>JobExecutor: Produces events based on end status of JobExecution
+    JobExecutor-->>JobExecutionStorageInterface: Store JobExecution after job ends
+    deactivate JobExecutor
+    SimpleJobLauncher-->>App: Return the JobExecution, executed
+    deactivate SimpleJobLauncher
+```
+
 ## Vocabulary
 
 Because when you start with any library
@@ -20,32 +54,9 @@ as it contains the business logic required for what you wish to achieve.
 
 The only requirement is implementing [`JobInterface`](../src/batch/src/Job/JobInterface.php),
 
-For exemple you can have a job for generate a csv:
-```php
-<?php
-
-declare(strict_types=1);
-
-use Yokai\Batch\JobExecution;
-use Yokai\Batch\Job\JobInterface;
-
-class CsvExportJob implements JobInterface
-{
-    public function execute(JobExecution $jobExecution) : void
-    {
-        $file = fopen('path/to/file.csv', 'w');
-            
-        // your export logic here
-        fputcsv($file, ['column1', 'column2']);
-        
-        fclose($file);
-    }
-}
-```
 #### See More:
 For more information about jobs, see [Job](batch/domain/job.md)
 
-[//]: # (Todo: Maybe we can remove Job.md and put the content here)
 ### Job Launcher
 
 The job launcher is responsible for executing/scheduling every jobs.
@@ -62,62 +73,9 @@ For use a Job Launcher you need to have:
 - **A JobExecutor:** The executor will execute the job.
 - **A JobExecutionAccessor:** The accessor will access the job execution.
 
-#### How to use a Job Launcher ?
-Look here a simple example to use a Job Launcher with the `SimpleJobLauncher`:
-
-```php
-<?php
-
-declare(strict_types=1);
-
-use Yokai\Batch\Factory\JobExecutionFactory;
-use Yokai\Batch\Factory\UniqidJobExecutionIdGenerator;
-use Yokai\Batch\Job\JobExecutionAccessor;
-use Yokai\Batch\Job\JobExecutor;
-use Yokai\Batch\Job\JobInterface;
-use Yokai\Batch\JobExecution;
-use Yokai\Batch\Launcher\SimpleJobLauncher;
-use Yokai\Batch\Registry\JobContainer;
-use Yokai\Batch\Registry\JobRegistry;
-use Yokai\Batch\Storage\NullJobExecutionStorage;
-
-$jobs = new JobContainer([
-    'your.job.name' => new class implements JobInterface {
-        public function execute(JobExecution $jobExecution): void
-        {
-            // your business logic
-        }
-    },
-]);
-$jobExecutionStorage = new NullJobExecutionStorage();
-
-$launcher = new SimpleJobLauncher(
-    new JobExecutionAccessor(new JobExecutionFactory(new UniqidJobExecutionIdGenerator()), $jobExecutionStorage),
-    new JobExecutor(new JobRegistry($jobs), $jobExecutionStorage, null),
-);
-
-$execution = $launcher->launch('your.job.name', ['job' => ['configuration']]);
-```
-
-#### See More:
-- [Job Launcher](batch/domain/job-launcher.md)
-
 ### JobExecution:
 
 A [JobExecution](../src/batch/src/JobExecution.php) is the class that holds information about one execution of a job.
-#### What kind of information does it hold ?
-
-- `JobExecution::$jobName` : The Job name (job id)
-- `JobExecution::$id` : The execution id
-- `JobExecution::$parameters` : Some parameters with which job was executed
-- `JobExecution::$status` : A status (pending, running, stopped, completed, abandoned, failed)
-- `JobExecution::$startTime` : Start time
-- `JobExecution::$endTime` : End time
-- `JobExecution::$failures` : A list of failures (usually exceptions)
-- `JobExecution::$warnings` : A list of warnings (usually skipped items)
-- `JobExecution::$summary` : A summary (can contain any data you wish to store)
-- `JobExecution::$logs` : Some logs
-- `JobExecution::$childExecutions` : Some child execution
 
 ### JobExecutionStorage
 
diff --git a/docs/README_old.md b/docs/README_old.md
new file mode 100644
index 00000000..5bad304e
--- /dev/null
+++ b/docs/README_old.md
@@ -0,0 +1,152 @@
+## Installation
+
+```bash
+composer require yokai/batch
+```
+
+## Vocabulary
+
+Because when you start with any library
+it is important to understand what are the concepts introduced in it.
+
+This is highly recommended that you read this entire page
+before starting to work with this library.
+
+### Job
+A job is the class that is responsible for **what** your code is doing.
+
+This is the class you will have to create (or reuse),
+as it contains the business logic required for what you wish to achieve.
+
+The only requirement is implementing [`JobInterface`](../src/batch/src/Job/JobInterface.php),
+
+For exemple you can have a job for generate a csv:
+```php
+<?php
+
+declare(strict_types=1);
+
+use Yokai\Batch\JobExecution;
+use Yokai\Batch\Job\JobInterface;
+
+class CsvExportJob implements JobInterface
+{
+    public function execute(JobExecution $jobExecution) : void
+    {
+        $file = fopen('path/to/file.csv', 'w');
+            
+        // your export logic here
+        fputcsv($file, ['column1', 'column2']);
+        
+        fclose($file);
+    }
+}
+```
+#### See More:
+For more information about jobs, see [Job](batch/domain/job.md)
+
+[//]: # (Todo: Maybe we can remove Job.md and put the content here)
+### Job Launcher
+
+The job launcher is responsible for executing/scheduling every jobs.
+
+Yeah, executing OR scheduling. There is multiple implementation of a job launcher across bridges.
+Job's execution might be asynchronous, and thus, when you ask the job launcher to "launch" a job,
+you have to check the `JobExecution` status that it had returned to know if the job is already executed.
+
+#### What is needed to use a Job Launcher ?
+
+For use a Job Launcher you need to have:
+- **A Container of Jobs:** A container use any PSR-11 [container implementation](https://packagist.org/providers/psr/container-implementation)
+- **A Storage for Job Executions:** A storage to store the execution of jobs, it can be a database, a file, a cache, etc.
+- **A JobExecutor:** The executor will execute the job.
+- **A JobExecutionAccessor:** The accessor will access the job execution.
+
+#### How to use a Job Launcher ?
+Look here a simple example to use a Job Launcher with the `SimpleJobLauncher`:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Yokai\Batch\Factory\JobExecutionFactory;
+use Yokai\Batch\Factory\UniqidJobExecutionIdGenerator;
+use Yokai\Batch\Job\JobExecutionAccessor;
+use Yokai\Batch\Job\JobExecutor;
+use Yokai\Batch\Job\JobInterface;
+use Yokai\Batch\JobExecution;
+use Yokai\Batch\Launcher\SimpleJobLauncher;
+use Yokai\Batch\Registry\JobContainer;
+use Yokai\Batch\Registry\JobRegistry;
+use Yokai\Batch\Storage\NullJobExecutionStorage;
+
+$jobs = new JobContainer([
+    'your.job.name' => new class implements JobInterface {
+        public function execute(JobExecution $jobExecution): void
+        {
+            // your business logic
+        }
+    },
+]);
+$jobExecutionStorage = new NullJobExecutionStorage();
+
+$launcher = new SimpleJobLauncher(
+    new JobExecutionAccessor(new JobExecutionFactory(new UniqidJobExecutionIdGenerator()), $jobExecutionStorage),
+    new JobExecutor(new JobRegistry($jobs), $jobExecutionStorage, null),
+);
+
+$execution = $launcher->launch('your.job.name', ['job' => ['configuration']]);
+```
+
+#### See More:
+- [Job Launcher](batch/domain/job-launcher.md)
+
+### JobExecution:
+
+A [JobExecution](../src/batch/src/JobExecution.php) is the class that holds information about one execution of a job.
+#### What kind of information does it hold ?
+
+- `JobExecution::$jobName` : The Job name (job id)
+- `JobExecution::$id` : The execution id
+- `JobExecution::$parameters` : Some parameters with which job was executed
+- `JobExecution::$status` : A status (pending, running, stopped, completed, abandoned, failed)
+- `JobExecution::$startTime` : Start time
+- `JobExecution::$endTime` : End time
+- `JobExecution::$failures` : A list of failures (usually exceptions)
+- `JobExecution::$warnings` : A list of warnings (usually skipped items)
+- `JobExecution::$summary` : A summary (can contain any data you wish to store)
+- `JobExecution::$logs` : Some logs
+- `JobExecution::$childExecutions` : Some child execution
+
+### JobExecutionStorage
+
+Whenever a job is launched, whether is starts immediately or not, an execution is stored for it.
+The execution are stored to allow you to keep an eye on what is happening.
+This persistence is on the responsibility of the job execution storage.
+- [Job Execution Storage](batch/domain/job-execution-storage.md)
+
+
+## Next steps
+- [Getting Started (Nom de l'exemple)](getting-started.md)
+- Framework:
+  - [Symfony](symfony.md)
+- Bridge:
+  - Doctrine:
+    - [Dbal](batch-doctrine-dbal/job-execution-storage.md)
+    - [ORM](batch-doctrine-orm/entity-item-reader.md)
+    - [Persistence](batch-doctrine-persistence/object-registry.md)
+
+[//]: # (    Todo: link object-item-writer.md ?)
+- [Flysystem bridge](flysystem.md)
+- [Box OpenSpout bridge](openspout.md)
+
+[//]: # (Todo: La partie symfony est-elle vraiment utile ? Ou peut être que l'on peut la mettre dans une catégorie a pat entiére ?)
+- Symfony:
+  - [Console](batch-symfony-console/command.md)
+  - [Messenger](batch-symfony-messenger/job-launcher.md)
+  - [Serializer](batch-symfony-serializer/job-execution-serializer.md)
+  - [Validator](batch-symfony-validator/skip-invalid-item-processor.md)
+
+[//]: # (Idée d'exemple pour le getting started:)
+[//]: # (- Un import like Cizeta sans symfony)