Add conventions around PHP code in the project

composer.json

@@ -22,7 +22,10 @@
     "psr/container": "^1.0",
     "psr/event-dispatcher": "^1.0",
     "psr/log": "^1.0|^2.0|^3.0",
+    "symfony/config": "^5.0|^6.0",
     "symfony/console": "^5.0|^6.0",
+    "symfony/dependency-injection": "^5.0|^6.0",
+    "symfony/http-kernel": "^5.0|^6.0",
     "symfony/framework-bundle": "^5.0|^6.0",
     "symfony/messenger": "^5.0|^6.0",
     "symfony/serializer": "^5.0|^6.0",
@@ -45,6 +48,7 @@
     "yokai/batch-doctrine-dbal": "self.version",
     "yokai/batch-doctrine-orm": "self.version",
     "yokai/batch-doctrine-persistence": "self.version",
+    "yokai/batch-flysystem": "self.version",
     "yokai/batch-symfony-console": "self.version",
     "yokai/batch-symfony-framework": "self.version",
     "yokai/batch-symfony-messenger": "self.version",

src/batch-box-spout/src/Reader/HeaderStrategy.php

@@ -75,6 +75,8 @@ public function setHeaders(array $headers): bool
     }
 
     /**
+     * Build the associative item, a combination of headers and values.
+     *
      * @throws InvalidRowSizeException
      *
      * @phpstan-param array<int, string> $row

src/batch-box-spout/src/Reader/Options/SheetFilter.php

@@ -55,6 +55,8 @@ public static function nameIs(string $name, string ...$names): self
     }
 
     /**
+     * Iterate over valid sheets for the provided filter.
+     *
      * @return Generator&SheetInterface[]
      * @phpstan-return Generator<SheetInterface>
      * @internal

src/batch-box-spout/src/Writer/WriteToSheetItem.php

@@ -21,13 +21,18 @@ private function __construct(
     }
 
     /**
+     * Static constructor from array data.
+     *
      * @param array<int|string, mixed> $item
      */
     public static function array(string $sheet, array $item, Style $style = null): self
     {
         return new self($sheet, WriterEntityFactory::createRowFromArray($item, $style));
     }
 
+    /**
+     * Static constructor from {@see Row} object.
+     */
     public static function row(string $sheet, Row $item): self
     {
         return new self($sheet, $item);

src/batch-doctrine-dbal/composer.json

@@ -14,6 +14,7 @@
         "php": "^8.0",
         "ext-json": "*",
         "doctrine/dbal": "^2.11",
+        "doctrine/persistence": "^2.0",
         "yokai/batch": "^0.4.0"
     },
     "autoload": {

src/batch-doctrine-dbal/src/DoctrineDBALJobExecutionStorage.php

@@ -17,9 +17,14 @@
 use Yokai\Batch\Exception\JobExecutionNotFoundException;
 use Yokai\Batch\Exception\RuntimeException;
 use Yokai\Batch\JobExecution;
+use Yokai\Batch\Storage\JobExecutionStorageInterface;
 use Yokai\Batch\Storage\Query;
 use Yokai\Batch\Storage\QueryableJobExecutionStorageInterface;
 
+/**
+ * This {@see JobExecutionStorageInterface} will store
+ * {@see JobExecution} in an SQL database using doctrine/dbal.
+ */
 final class DoctrineDBALJobExecutionStorage implements QueryableJobExecutionStorageInterface
 {
     private const DEFAULT_OPTIONS = [
@@ -46,6 +51,9 @@ public function __construct(ConnectionRegistry $doctrine, array $options)
         $this->connection = $connection;
     }
 
+    /**
+     * Create required table for this storage.
+     */
     public function createSchema(): void
     {
         $assetFilter = $this->connection->getConfiguration()->getSchemaAssetsFilter();

src/batch-doctrine-dbal/src/JobExecutionRowNormalizer.php

@@ -27,6 +27,8 @@ public function __construct(
     }
 
     /**
+     * Convert a {@see JobExecution} object to a row data array.
+     *
      * @phpstan-return array<string, mixed>
      */
     public function toRow(JobExecution $jobExecution): array
@@ -47,6 +49,8 @@ public function toRow(JobExecution $jobExecution): array
     }
 
     /**
+     * Convert a row data array to a {@see JobExecution} object.
+     *
      * @phpstan-param array<string, mixed> $data
      */
     public function fromRow(array $data, JobExecution $parent = null): JobExecution
@@ -97,7 +101,7 @@ public function fromRow(array $data, JobExecution $parent = null): JobExecution
     /**
      * @phpstan-return array<string, mixed>
      */
-    public function toChildRow(JobExecution $jobExecution): array
+    private function toChildRow(JobExecution $jobExecution): array
     {
         return [
             'job_name' => $jobExecution->getJobName(),

src/batch-doctrine-orm/composer.json

@@ -13,6 +13,7 @@
     "require": {
         "php": "^8.0",
         "doctrine/orm": "^2.8",
+        "doctrine/persistence": "^2.0",
         "yokai/batch": "^0.4.0"
     },
     "autoload": {

src/batch-symfony-console/src/CommandRunner.php

@@ -7,6 +7,9 @@
 use Symfony\Component\Console\Input\ArrayInput;
 use Symfony\Component\Process\PhpExecutableFinder;
 
+/**
+ * Utility class that knows how to run command asynchronously.
+ */
 class CommandRunner
 {
     private string $consolePath;
@@ -25,6 +28,8 @@ public function __construct(
     }
 
     /**
+     * Run a command asynchronously.
+     *
      * @phpstan-param array<string, mixed> $arguments
      */
     public function runAsync(string $commandName, string $logFilename, array $arguments = []): void

src/batch-symfony-console/src/RunCommandJobLauncher.php

@@ -13,7 +13,7 @@
 /**
  * This {@see JobLauncherInterface} will execute job via an asynchronous symfony command.
  *
- * Example, if you call {@see RunCommandJobLauncher::launch('import', ['foo'=>'bar'])},
+ * Example, if you call RunCommandJobLauncher::launch('import', ['foo'=>'bar']),
  * this command will run (with absolute pathes) :
  *
  *      php bin/console yokai:batch:run import '{"foo":"bar"}' >> var/log/batch_execute.log 2>&1 &

src/batch-symfony-console/src/RunJobCommand.php

@@ -13,8 +13,12 @@
 use Yokai\Batch\Exception\UnexpectedValueException;
 use Yokai\Batch\Job\JobExecutionAccessor;
 use Yokai\Batch\Job\JobExecutor;
+use Yokai\Batch\Job\JobInterface;
 use Yokai\Batch\JobExecution;
 
+/**
+ * Execute any {@see JobInterface} within your CLI.
+ */
 final class RunJobCommand extends Command
 {
     protected static $defaultName = 'yokai:batch:run';

src/batch-symfony-framework/composer.json

@@ -13,6 +13,9 @@
     "require": {
         "php": "^8.0",
         "composer-runtime-api": "^2.0",
+        "symfony/config": "^5.0|^6.0",
+        "symfony/dependency-injection": "^5.0|^6.0",
+        "symfony/http-kernel": "^5.0|^6.0",
         "symfony/framework-bundle": "^5.0|^6.0",
         "yokai/batch": "^0.4.0"
     },

src/batch-symfony-framework/src/DependencyInjection/CompilerPass/RegisterJobsCompilerPass.php

@@ -10,7 +10,12 @@
 use Symfony\Component\DependencyInjection\Definition;
 use Symfony\Component\DependencyInjection\Reference;
 use Yokai\Batch\Bridge\Symfony\Framework\JobWithStaticNameInterface;
+use Yokai\Batch\Job\JobInterface;
+use Yokai\Batch\Registry\JobRegistry;
 
+/**
+ * Find tagged {@see JobInterface} and register these in {@see JobRegistry}.
+ */
 final class RegisterJobsCompilerPass implements CompilerPassInterface
 {
     /**

src/batch-symfony-framework/src/DependencyInjection/Configuration.php

@@ -8,6 +8,9 @@
 use Symfony\Component\Config\Definition\Builder\TreeBuilder;
 use Symfony\Component\Config\Definition\ConfigurationInterface;
 
+/**
+ * Configuration for yokai/batch Symfony Bundle.
+ */
 final class Configuration implements ConfigurationInterface
 {
     /**

src/batch-symfony-framework/src/DependencyInjection/YokaiBatchExtension.php

@@ -20,6 +20,9 @@
 use Yokai\Batch\Storage\ListableJobExecutionStorageInterface;
 use Yokai\Batch\Storage\QueryableJobExecutionStorageInterface;
 
+/**
+ * Dependency injection extension for yokai/batch Symfony Bundle.
+ */
 final class YokaiBatchExtension extends Extension
 {
     /**

src/batch-symfony-framework/src/JobWithStaticNameInterface.php

@@ -4,6 +4,8 @@
 
 namespace Yokai\Batch\Bridge\Symfony\Framework;
 
+use Yokai\Batch\Registry\JobRegistry;
+
 /**
  * A job that implement this interface can define the associated job name via a static method.
  * This is very useful if you are registering jobs using PSR services registering.
@@ -12,5 +14,8 @@
  */
 interface JobWithStaticNameInterface
 {
+    /**
+     * The job name as it will be registered in the {@see JobRegistry}.
+     */
     public static function getJobName(): string;
 }

src/batch-symfony-framework/src/YokaiBatchBundle.php

@@ -8,6 +8,9 @@
 use Symfony\Component\HttpKernel\Bundle\Bundle;
 use Yokai\Batch\Bridge\Symfony\Framework\DependencyInjection\CompilerPass\RegisterJobsCompilerPass;
 
+/**
+ * yokai/batch Symfony Bundle.
+ */
 final class YokaiBatchBundle extends Bundle
 {
     public function build(ContainerBuilder $container): void

src/batch/src/Event/JobEvent.php

@@ -6,6 +6,9 @@
 
 use Yokai\Batch\JobExecution;
 
+/**
+ * Base class for all job execution related events.
+ */
 class JobEvent
 {
     public function __construct(

src/batch/src/Event/PostExecuteEvent.php

@@ -4,6 +4,10 @@
 
 namespace Yokai\Batch\Event;
 
+/**
+ * This event is triggered by {@see JobExecutor}
+ * whenever a job execution fails or succeed.
+ */
 final class PostExecuteEvent extends JobEvent
 {
 }

src/batch/src/Event/PreExecuteEvent.php

@@ -4,6 +4,12 @@
 
 namespace Yokai\Batch\Event;
 
+use Yokai\Batch\Job\JobExecutor;
+
+/**
+ * This event is triggered by {@see JobExecutor}
+ * whenever a job execution starts.
+ */
 final class PreExecuteEvent extends JobEvent
 {
 }

src/batch/src/Exception/ExceptionInterface.php

@@ -6,6 +6,9 @@
 
 use Throwable;
 
+/**
+ * Interface for all exceptions triggered by this library.
+ */
 interface ExceptionInterface extends Throwable
 {
 }

src/batch/src/Exception/UndefinedJobException.php

@@ -4,10 +4,12 @@
 
 namespace Yokai\Batch\Exception;
 
+use Throwable;
+
 class UndefinedJobException extends InvalidArgumentException
 {
-    public function __construct(string $name)
+    public function __construct(string $name, Throwable $previous = null)
     {
-        parent::__construct(sprintf('Job "%s" is undefined', $name));
+        parent::__construct(sprintf('Job "%s" is undefined', $name), $previous);
     }
 }

src/batch/src/Factory/JobExecutionFactory.php

@@ -7,6 +7,9 @@
 use Yokai\Batch\JobExecution;
 use Yokai\Batch\JobParameters;
 
+/**
+ * Create a {@see JobExecution} from scalar members.
+ */
 final class JobExecutionFactory
 {
     public function __construct(
@@ -15,6 +18,8 @@ public function __construct(
     }
 
     /**
+     * Create a {@see JobExecution}.
+     *
      * @phpstan-param array<string, mixed> $configuration
      */
     public function create(string $name, array $configuration = []): JobExecution

src/batch/src/Factory/JobExecutionIdGeneratorInterface.php

@@ -11,5 +11,8 @@
  */
 interface JobExecutionIdGeneratorInterface
 {
+    /**
+     * Generate and return a new id for the {@see JobExecution}.
+     */
     public function generate(): string;
 }

src/batch/src/Factory/UniqidJobExecutionIdGenerator.php

@@ -4,6 +4,10 @@
 
 namespace Yokai\Batch\Factory;
 
+/**
+ * This {@see JobExecutionIdGeneratorInterface} will use
+ * php {@see uniqid} function to generate job ids.
+ */
 final class UniqidJobExecutionIdGenerator implements JobExecutionIdGeneratorInterface
 {
     /**

src/batch/src/Failure.php

@@ -38,6 +38,8 @@ public function __construct(
     }
 
     /**
+     * Static constructor from an exception.
+     *
      * @phpstan-param array<string, string> $parameters
      */
     public static function fromException(Throwable $exception, array $parameters = []): self

src/batch/src/Job/Item/Processor/CallbackProcessor.php

@@ -7,13 +7,15 @@
 use Closure;
 use Yokai\Batch\Job\Item\ItemProcessorInterface;
 
+/**
+ * This {@see ItemProcessorInterface} will transform every item
+ * with a closure provided at object's construction.
+ */
 final class CallbackProcessor implements ItemProcessorInterface
 {
-    private Closure $callback;
-
-    public function __construct(Closure $callback)
-    {
-        $this->callback = $callback;
+    public function __construct(
+        private Closure $callback,
+    ) {
     }
 
     public function process(mixed $item): mixed

src/batch/src/Job/JobExecutionAccessor.php

@@ -23,6 +23,8 @@ public function __construct(
     }
 
     /**
+     * Retrieve or create a {@see JobExecution}.
+     *
      * @param array<string, mixed> $configuration
      */
     public function get(string $name, array $configuration): JobExecution

src/batch/src/Job/JobExecutionAwareInterface.php

@@ -9,8 +9,13 @@
 /**
  * A class implementing this interface will gain access
  * to current {@see JobExecution}.
+ *
+ * Default implementation from {@see JobExecutionAwareTrait} can be used.
  */
 interface JobExecutionAwareInterface
 {
+    /**
+     * Set execution to the job component.
+     */
     public function setJobExecution(JobExecution $jobExecution): void;
 }

src/batch/src/Job/JobExecutionAwareTrait.php

@@ -21,6 +21,9 @@ public function setJobExecution(JobExecution $jobExecution): void
         $this->jobExecution = $jobExecution;
     }
 
+    /**
+     * Get root execution of current job execution.
+     */
     public function getRootExecution(): JobExecution
     {
         return $this->jobExecution->getRootExecution();