Add conventions around PHP code in the project (#68)

* Add convention tests over packages definitions

* Add conventions around classes docblocks

* Add conventions around public method docblocks

Author: yann-eugone

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/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/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/Exception/ExceptionInterface.php

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

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/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/Factory/JobExecutionIdGeneratorInterface.php

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

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/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/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