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

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

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/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/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();

src/Job/JobExecutor.php

@@ -33,6 +33,9 @@ public function __construct(
     ) {
     }
 
+    /**
+     * Execute job and respect rules around it.
+     */
     public function execute(JobExecution $jobExecution): void
     {
         $logger = $jobExecution->getLogger();

src/Job/JobParametersAwareInterface.php

@@ -13,8 +13,13 @@
  *
  * Parameters can also be accessed by implementing {@see JobExecutionAwareInterface}
  * and calling {@see JobExecution::getParameters} on the provided execution.
+ *
+ * Default implementation from {@see JobParametersAwareTrait} can be used.
  */
 interface JobParametersAwareInterface
 {
+    /**
+     * Set parameters to the job component.
+     */
     public function setJobParameters(JobParameters $parameters): void;
 }

src/Job/JobWithChildJobs.php

@@ -8,6 +8,10 @@
 use Yokai\Batch\JobExecution;
 use Yokai\Batch\Storage\JobExecutionStorageInterface;
 
+/**
+ * This {@see JobInterface} will execute by triggering child jobs.
+ * If a child job fails, following child jobs won't be executed.
+ */
 class JobWithChildJobs implements JobInterface
 {
     public function __construct(

src/Job/Parameters/JobParameterAccessorInterface.php

@@ -14,6 +14,8 @@
 interface JobParameterAccessorInterface
 {
     /**
+     * Get the parameter value from job execution.
+     *
      * @param JobExecution $execution A job execution (for context)
      *
      * @return mixed The requested value

src/Job/SummaryAwareInterface.php

@@ -12,8 +12,13 @@
  *
  * Summary can also be accessed by implementing {@see JobExecutionAwareInterface}
  * and calling {@see JobExecution::getSummary} on the provided execution.
+ *
+ * Default implementation from {@see SummaryAwareTrait} can be used.
  */
 interface SummaryAwareInterface
 {
+    /**
+     * Set summary to the job component.
+     */
     public function setSummary(Summary $summary): void;
 }

src/JobExecution.php

@@ -176,6 +176,10 @@ public function getEndTime(): ?DateTimeInterface
         return $this->endTime;
     }
 
+    /**
+     * Build a {@see DateInterval}
+     * from {@see JobExecution::$startTime} to {@see JobExecution::$endTime}.
+     */
     public function getDuration(): DateInterval
     {
         $now = new DateTime();
@@ -248,6 +252,9 @@ public function getChildExecutions(): array
         return array_values($this->childExecutions);
     }
 
+    /**
+     * Add a child execution.
+     */
     public function addChildExecution(JobExecution $execution): void
     {
         $this->childExecutions[$execution->getJobName()] = $execution;
@@ -267,6 +274,9 @@ public function getParameters(): JobParameters
         return $this->parameters;
     }
 
+    /**
+     * Get a parameter value.
+     */
     public function getParameter(string $name): mixed
     {
         return $this->parameters->get($name);
@@ -280,6 +290,9 @@ public function getFailures(): array
         return $this->failures;
     }
 
+    /**
+     * Add a failure to the execution.
+     */
     public function addFailure(Failure $failure, bool $log = true): void
     {
         $this->failures[] = $failure;
@@ -289,6 +302,8 @@ public function addFailure(Failure $failure, bool $log = true): void
     }
 
     /**
+     * Add a failure, build from exception, to the execution.
+     *
      * @phpstan-param array<string, string> $parameters
      */
     public function addFailureException(Throwable $exception, array $parameters = [], bool $log = true): void
@@ -324,6 +339,9 @@ public function getWarnings(): array
         return $this->warnings;
     }
 
+    /**
+     * Add a warning to the execution.
+     */
     public function addWarning(Warning $warning, bool $log = true): void
     {
         $this->warnings[] = $warning;

src/JobExecutionLogs.php

@@ -22,6 +22,9 @@ public function __toString(): string
         return $this->logs;
     }
 
+    /**
+     * Append message to logs.
+     */
     public function log(string $message): void
     {
         $this->logs .= $message . PHP_EOL;

src/JobParameters.php

@@ -30,6 +30,8 @@ public function __construct(
     }
 
     /**
+     * Get all parameter values.
+     *
      * @phpstan-return array<string, mixed>
      */
     public function all(): array
@@ -46,6 +48,8 @@ public function has(string $name): bool
     }
 
     /**
+     * Get a parameter value.
+     *
      * @throws UndefinedJobParameterException If parameter is not defined
      */
     public function get(string $name): mixed

src/Registry/JobRegistry.php

@@ -4,10 +4,17 @@
 
 namespace Yokai\Batch\Registry;
 
+use Psr\Container\ContainerExceptionInterface;
 use Psr\Container\ContainerInterface;
 use Yokai\Batch\Exception\UndefinedJobException;
 use Yokai\Batch\Job\JobInterface;
 
+/**
+ * This class is a wrapper around a {@see ContainerInterface},
+ * responsible for accessing jobs in a typed maner.
+ * It can be registered as a global registry,
+ * but it can be also created with a subset of jobs if required.
+ */
 final class JobRegistry
 {
     public function __construct(
@@ -16,6 +23,8 @@ public function __construct(
     }
 
     /**
+     * Static constructor with indexed array of jobs.
+     *
      * @param array<string, JobInterface> $jobs
      */
     public static function fromJobArray(array $jobs): JobRegistry
@@ -24,17 +33,19 @@ public static function fromJobArray(array $jobs): JobRegistry
     }
 
     /**
-     * @throws UndefinedJobException
+     * Get a job from its name.
+     *
+     * @throws UndefinedJobException if the job is not defined
      */
     public function get(string $name): JobInterface
     {
-        if (!$this->jobs->has($name)) {
-            throw new UndefinedJobException($name);
+        try {
+            /** @var JobInterface $job */
+            $job = $this->jobs->get($name);
+        } catch (ContainerExceptionInterface $exception) {
+            throw new UndefinedJobException($name, $exception);
         }
 
-        /** @var JobInterface $job */
-        $job = $this->jobs->get($name);
-
         return $job;
     }
 }

src/Serializer/JsonJobExecutionSerializer.php

@@ -15,9 +15,14 @@
 use Yokai\Batch\JobExecution;
 use Yokai\Batch\JobExecutionLogs;
 use Yokai\Batch\JobParameters;
+use Yokai\Batch\Storage\JobExecutionStorageInterface;
 use Yokai\Batch\Summary;
 use Yokai\Batch\Warning;
 
+/**
+ * This {@see JobExecutionStorageInterface} will (un)serialise any {@see JobExecution} to/from json,
+ * using internal (de)normalisation and PHP {@see json_encode} and {@see json_decode} functions.
+ */
 final class JsonJobExecutionSerializer implements JobExecutionSerializerInterface
 {
     /**

src/Storage/FilesystemJobExecutionStorage.php

@@ -154,7 +154,7 @@ public function query(Query $query): iterable
         return array_slice($candidates, $query->offset(), $query->limit());
     }
 
-    public function buildFilePath(string $jobName, string $executionId): string
+    private function buildFilePath(string $jobName, string $executionId): string
     {
         return implode(DIRECTORY_SEPARATOR, [$this->directory, $jobName, $executionId]) .
             '.' . $this->serializer->extension();

src/Storage/ListableJobExecutionStorageInterface.php

@@ -12,6 +12,8 @@
 interface ListableJobExecutionStorageInterface extends JobExecutionStorageInterface
 {
     /**
+     * List all job executions that are for the given job.
+     *
      * @return iterable|JobExecution[]
      */
     public function list(string $jobName): iterable;