From fae7ee8e0f1bbf53b5a2ed0fa2b61da81c5dbcbb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yann=20Eugon=C3=A9?= Date: Mon, 20 Jun 2022 09:43:05 +0200 Subject: [PATCH] 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 | 3 ++ src/Event/PostExecuteEvent.php | 4 +++ src/Event/PreExecuteEvent.php | 6 ++++ src/Exception/ExceptionInterface.php | 3 ++ src/Exception/UndefinedJobException.php | 6 ++-- src/Factory/JobExecutionFactory.php | 5 ++++ .../JobExecutionIdGeneratorInterface.php | 3 ++ src/Factory/UniqidJobExecutionIdGenerator.php | 4 +++ src/Failure.php | 2 ++ src/Job/Item/Processor/CallbackProcessor.php | 12 ++++---- src/Job/JobExecutionAccessor.php | 2 ++ src/Job/JobExecutionAwareInterface.php | 5 ++++ src/Job/JobExecutionAwareTrait.php | 3 ++ src/Job/JobExecutor.php | 3 ++ src/Job/JobParametersAwareInterface.php | 5 ++++ src/Job/JobWithChildJobs.php | 4 +++ .../JobParameterAccessorInterface.php | 2 ++ src/Job/SummaryAwareInterface.php | 5 ++++ src/JobExecution.php | 18 ++++++++++++ src/JobExecutionLogs.php | 3 ++ src/JobParameters.php | 4 +++ src/Registry/JobRegistry.php | 23 +++++++++++---- src/Serializer/JsonJobExecutionSerializer.php | 5 ++++ src/Storage/FilesystemJobExecutionStorage.php | 2 +- .../ListableJobExecutionStorageInterface.php | 2 ++ src/Storage/Query.php | 8 +++--- src/Storage/QueryBuilder.php | 21 ++++++++------ .../QueryableJobExecutionStorageInterface.php | 2 ++ src/Summary.php | 20 +++++++++++++ .../SequenceJobExecutionIdGenerator.php | 4 +++ .../Job/Item/Processor/TestDebugProcessor.php | 5 ++++ src/Test/Job/Item/Reader/TestDebugReader.php | 5 ++++ src/Test/Job/Item/TestDebugComponent.php | 28 +++++++++++++++++++ src/Test/Job/Item/Writer/InMemoryWriter.php | 6 ++++ src/Test/Job/Item/Writer/TestDebugWriter.php | 5 ++++ src/Test/Launcher/BufferingJobLauncher.php | 5 ++++ .../Storage/InMemoryJobExecutionStorage.php | 5 ++++ .../Storage/JobExecutionStorageTestTrait.php | 3 ++ src/Trigger/Scheduler/SchedulerInterface.php | 2 ++ src/Trigger/Scheduler/TimeScheduler.php | 2 +- src/Trigger/TriggerScheduledJobsJob.php | 2 +- 41 files changed, 229 insertions(+), 28 deletions(-) diff --git a/src/Event/JobEvent.php b/src/Event/JobEvent.php index 0e4f7d6..1797e6a 100644 --- a/src/Event/JobEvent.php +++ b/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( diff --git a/src/Event/PostExecuteEvent.php b/src/Event/PostExecuteEvent.php index 48f45cb..02586e6 100644 --- a/src/Event/PostExecuteEvent.php +++ b/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 { } diff --git a/src/Event/PreExecuteEvent.php b/src/Event/PreExecuteEvent.php index 23457f8..5274a1e 100644 --- a/src/Event/PreExecuteEvent.php +++ b/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 { } diff --git a/src/Exception/ExceptionInterface.php b/src/Exception/ExceptionInterface.php index b81414a..2a7c6ee 100644 --- a/src/Exception/ExceptionInterface.php +++ b/src/Exception/ExceptionInterface.php @@ -6,6 +6,9 @@ use Throwable; +/** + * Interface for all exceptions triggered by this library. + */ interface ExceptionInterface extends Throwable { } diff --git a/src/Exception/UndefinedJobException.php b/src/Exception/UndefinedJobException.php index b3ae221..ba985c3 100644 --- a/src/Exception/UndefinedJobException.php +++ b/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); } } diff --git a/src/Factory/JobExecutionFactory.php b/src/Factory/JobExecutionFactory.php index e65e113..a63b104 100644 --- a/src/Factory/JobExecutionFactory.php +++ b/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 $configuration */ public function create(string $name, array $configuration = []): JobExecution diff --git a/src/Factory/JobExecutionIdGeneratorInterface.php b/src/Factory/JobExecutionIdGeneratorInterface.php index 6e32459..e2c0615 100644 --- a/src/Factory/JobExecutionIdGeneratorInterface.php +++ b/src/Factory/JobExecutionIdGeneratorInterface.php @@ -11,5 +11,8 @@ */ interface JobExecutionIdGeneratorInterface { + /** + * Generate and return a new id for the {@see JobExecution}. + */ public function generate(): string; } diff --git a/src/Factory/UniqidJobExecutionIdGenerator.php b/src/Factory/UniqidJobExecutionIdGenerator.php index e72feda..bb8e8c5 100644 --- a/src/Factory/UniqidJobExecutionIdGenerator.php +++ b/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 { /** diff --git a/src/Failure.php b/src/Failure.php index 88e7e23..063ecfb 100644 --- a/src/Failure.php +++ b/src/Failure.php @@ -38,6 +38,8 @@ public function __construct( } /** + * Static constructor from an exception. + * * @phpstan-param array $parameters */ public static function fromException(Throwable $exception, array $parameters = []): self diff --git a/src/Job/Item/Processor/CallbackProcessor.php b/src/Job/Item/Processor/CallbackProcessor.php index a149890..6830d77 100644 --- a/src/Job/Item/Processor/CallbackProcessor.php +++ b/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 diff --git a/src/Job/JobExecutionAccessor.php b/src/Job/JobExecutionAccessor.php index 3fbbcc1..24d83c6 100644 --- a/src/Job/JobExecutionAccessor.php +++ b/src/Job/JobExecutionAccessor.php @@ -23,6 +23,8 @@ public function __construct( } /** + * Retrieve or create a {@see JobExecution}. + * * @param array $configuration */ public function get(string $name, array $configuration): JobExecution diff --git a/src/Job/JobExecutionAwareInterface.php b/src/Job/JobExecutionAwareInterface.php index 59fcfda..fc1c6aa 100644 --- a/src/Job/JobExecutionAwareInterface.php +++ b/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; } diff --git a/src/Job/JobExecutionAwareTrait.php b/src/Job/JobExecutionAwareTrait.php index ce17b56..870153d 100644 --- a/src/Job/JobExecutionAwareTrait.php +++ b/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(); diff --git a/src/Job/JobExecutor.php b/src/Job/JobExecutor.php index 5426922..5c67e82 100644 --- a/src/Job/JobExecutor.php +++ b/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(); diff --git a/src/Job/JobParametersAwareInterface.php b/src/Job/JobParametersAwareInterface.php index 85a5879..f04fb12 100644 --- a/src/Job/JobParametersAwareInterface.php +++ b/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; } diff --git a/src/Job/JobWithChildJobs.php b/src/Job/JobWithChildJobs.php index c0f2692..6312d67 100644 --- a/src/Job/JobWithChildJobs.php +++ b/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( diff --git a/src/Job/Parameters/JobParameterAccessorInterface.php b/src/Job/Parameters/JobParameterAccessorInterface.php index 1ea7483..c0f7f62 100644 --- a/src/Job/Parameters/JobParameterAccessorInterface.php +++ b/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 diff --git a/src/Job/SummaryAwareInterface.php b/src/Job/SummaryAwareInterface.php index ebbc7ae..7c8b8e5 100644 --- a/src/Job/SummaryAwareInterface.php +++ b/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; } diff --git a/src/JobExecution.php b/src/JobExecution.php index f9d76f0..3974f60 100644 --- a/src/JobExecution.php +++ b/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 $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; diff --git a/src/JobExecutionLogs.php b/src/JobExecutionLogs.php index 2b23f7e..5cb2639 100644 --- a/src/JobExecutionLogs.php +++ b/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; diff --git a/src/JobParameters.php b/src/JobParameters.php index 673d4db..7e1bf85 100644 --- a/src/JobParameters.php +++ b/src/JobParameters.php @@ -30,6 +30,8 @@ public function __construct( } /** + * Get all parameter values. + * * @phpstan-return array */ 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 diff --git a/src/Registry/JobRegistry.php b/src/Registry/JobRegistry.php index c914fdc..1974319 100644 --- a/src/Registry/JobRegistry.php +++ b/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 $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; } } diff --git a/src/Serializer/JsonJobExecutionSerializer.php b/src/Serializer/JsonJobExecutionSerializer.php index 85d3b17..468a602 100644 --- a/src/Serializer/JsonJobExecutionSerializer.php +++ b/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 { /** diff --git a/src/Storage/FilesystemJobExecutionStorage.php b/src/Storage/FilesystemJobExecutionStorage.php index a2f5e14..b7804a0 100644 --- a/src/Storage/FilesystemJobExecutionStorage.php +++ b/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(); diff --git a/src/Storage/ListableJobExecutionStorageInterface.php b/src/Storage/ListableJobExecutionStorageInterface.php index 3ef7666..6f8d0fa 100644 --- a/src/Storage/ListableJobExecutionStorageInterface.php +++ b/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; diff --git a/src/Storage/Query.php b/src/Storage/Query.php index e1ec643..2ac17b0 100644 --- a/src/Storage/Query.php +++ b/src/Storage/Query.php @@ -24,7 +24,7 @@ public function __construct( /** * @var string[] */ - private array $jobNames, + private array $jobs, /** * @var string[] */ @@ -33,7 +33,7 @@ public function __construct( * @var int[] */ private array $statuses, - private ?string $sortBy, + private ?string $sort, private int $limit, private int $offset = 0, ) { @@ -44,7 +44,7 @@ public function __construct( */ public function jobs(): array { - return $this->jobNames; + return $this->jobs; } /** @@ -65,7 +65,7 @@ public function statuses(): array public function sort(): ?string { - return $this->sortBy; + return $this->sort; } public function limit(): int diff --git a/src/Storage/QueryBuilder.php b/src/Storage/QueryBuilder.php index 9e2c73d..afa0ccf 100644 --- a/src/Storage/QueryBuilder.php +++ b/src/Storage/QueryBuilder.php @@ -70,9 +70,9 @@ final class QueryBuilder private int $offset = 0; /** - * @param string[] $names + * Filter executions that are for one of the given job names. * - * @return $this + * @param string[] $names */ public function jobs(array $names): self { @@ -89,9 +89,9 @@ public function jobs(array $names): self } /** - * @param string[] $ids + * Filter executions that are one of given ids. * - * @return $this + * @param string[] $ids */ public function ids(array $ids): self { @@ -108,9 +108,9 @@ public function ids(array $ids): self } /** - * @param int[] $statuses + * Filter executions that are on given status. * - * @return $this + * @param int[] $statuses Any of {@see BatchStatus::*} */ public function statuses(array $statuses): self { @@ -127,7 +127,9 @@ public function statuses(array $statuses): self } /** - * @return $this + * Sort executions. + * + * @param string $by One of {@see QueryBuilder::SORT_BY_*} */ public function sort(string $by): self { @@ -141,7 +143,7 @@ public function sort(string $by): self } /** - * @return $this + * Limit query to a certain amount of executions. */ public function limit(int $limit, int $offset): self { @@ -158,6 +160,9 @@ public function limit(int $limit, int $offset): self return $this; } + /** + * Build query from criteria in this builder. + */ public function getQuery(): Query { return new Query($this->jobNames, $this->ids, $this->statuses, $this->sortBy, $this->limit, $this->offset); diff --git a/src/Storage/QueryableJobExecutionStorageInterface.php b/src/Storage/QueryableJobExecutionStorageInterface.php index 29aa232..50f798f 100644 --- a/src/Storage/QueryableJobExecutionStorageInterface.php +++ b/src/Storage/QueryableJobExecutionStorageInterface.php @@ -12,6 +12,8 @@ interface QueryableJobExecutionStorageInterface extends ListableJobExecutionStorageInterface { /** + * Execute query against stored job executions, and return the matching list. + * * @return iterable|JobExecution[] */ public function query(Query $query): iterable; diff --git a/src/Summary.php b/src/Summary.php index 514eb27..eee26df 100644 --- a/src/Summary.php +++ b/src/Summary.php @@ -31,16 +31,25 @@ public function __construct( ) { } + /** + * Set value. + */ public function set(string $key, mixed $info): void { $this->values[$key] = $info; } + /** + * Handle a numeric value by incrementing value of it. + */ public function increment(string $key, float|int $increment = 1): void { $this->values[$key] = ($this->values[$key] ?? 0) + $increment; } + /** + * Handle an array value by appending a new value to it. + */ public function append(string $key, mixed $value): void { $this->values[$key] ??= []; @@ -51,17 +60,25 @@ public function append(string $key, mixed $value): void $this->values[$key][] = $value; } + /** + * Get a value, or null if not set. + */ public function get(string $key): mixed { return $this->values[$key] ?? null; } + /** + * Whether a value was set. + */ public function has(string $key): bool { return array_key_exists($key, $this->values); } /** + * Get all values. + * * @phpstan-return array */ public function all(): array @@ -69,6 +86,9 @@ public function all(): array return $this->values; } + /** + * Clear all values. + */ public function clear(): void { $this->values = []; diff --git a/src/Test/Factory/SequenceJobExecutionIdGenerator.php b/src/Test/Factory/SequenceJobExecutionIdGenerator.php index 04dd60a..22a016d 100644 --- a/src/Test/Factory/SequenceJobExecutionIdGenerator.php +++ b/src/Test/Factory/SequenceJobExecutionIdGenerator.php @@ -6,6 +6,10 @@ use Yokai\Batch\Factory\JobExecutionIdGeneratorInterface; +/** + * This {@see JobExecutionIdGeneratorInterface} should be used in test to generate predictable ids. + * Sequence is provided at construction and items will be + */ final class SequenceJobExecutionIdGenerator implements JobExecutionIdGeneratorInterface { /** diff --git a/src/Test/Job/Item/Processor/TestDebugProcessor.php b/src/Test/Job/Item/Processor/TestDebugProcessor.php index bab9967..41667b9 100644 --- a/src/Test/Job/Item/Processor/TestDebugProcessor.php +++ b/src/Test/Job/Item/Processor/TestDebugProcessor.php @@ -7,6 +7,11 @@ use Yokai\Batch\Job\Item\ItemProcessorInterface; use Yokai\Batch\Test\Job\Item\TestDebugComponent; +/** + * This {@see ItemProcessorInterface} should be used in test + * for components working with generic {@see ItemProcessorInterface}. + * It provides convenient assertion methods to ensure your processor was used correctly. + */ final class TestDebugProcessor extends TestDebugComponent implements ItemProcessorInterface { private ItemProcessorInterface $decorated; diff --git a/src/Test/Job/Item/Reader/TestDebugReader.php b/src/Test/Job/Item/Reader/TestDebugReader.php index ce84248..c1fed39 100644 --- a/src/Test/Job/Item/Reader/TestDebugReader.php +++ b/src/Test/Job/Item/Reader/TestDebugReader.php @@ -7,6 +7,11 @@ use Yokai\Batch\Job\Item\ItemReaderInterface; use Yokai\Batch\Test\Job\Item\TestDebugComponent; +/** + * This {@see ItemReaderInterface} should be used in test + * for components working with generic {@see ItemReaderInterface}. + * It provides convenient assertion methods to ensure your reader was used correctly. + */ final class TestDebugReader extends TestDebugComponent implements ItemReaderInterface { private ItemReaderInterface $decorated; diff --git a/src/Test/Job/Item/TestDebugComponent.php b/src/Test/Job/Item/TestDebugComponent.php index a62ab19..533b14b 100644 --- a/src/Test/Job/Item/TestDebugComponent.php +++ b/src/Test/Job/Item/TestDebugComponent.php @@ -15,6 +15,10 @@ use Yokai\Batch\JobParameters; use Yokai\Batch\Summary; +/** + * This base contains all "runtime" interfaces handled by the lib. + * It provides convenient assertion methods to ensure your component was used correctly. + */ abstract class TestDebugComponent implements InitializableInterface, FlushableInterface, @@ -36,6 +40,10 @@ public function __construct( ) { } + /** + * @internal + * Utility method to simulate configuration from a {@see JobExecution}. + */ public function configure(JobExecution $jobExecution): void { $this->setJobExecution($jobExecution); @@ -59,6 +67,12 @@ public function setSummary(Summary $summary): void $this->summaryProvided = true; } + /** + * Assert that component was provided with *Aware interfaces: + * - {@see JobExecutionAwareInterface} + * - {@see JobParametersAwareInterface} + * - {@see SummaryAwareInterface} + */ public function assertWasConfigured(): void { Assert::assertTrue($this->jobExecutionProvided, 'Job execution was configured'); @@ -66,6 +80,12 @@ public function assertWasConfigured(): void Assert::assertTrue($this->summaryProvided, 'Summary was configured'); } + /** + * Assert that component was not provided with *Aware interfaces: + * - {@see JobExecutionAwareInterface} + * - {@see JobParametersAwareInterface} + * - {@see SummaryAwareInterface} + */ public function assertWasNotConfigured(): void { Assert::assertFalse($this->jobExecutionProvided, 'Job execution was not configured'); @@ -86,6 +106,10 @@ public function flush(): void $this->flushElement($this->decorated); } + /** + * Assert that component was used (depends on extending class). + * Also ensure that component was initialized & flushed. + */ public function assertWasUsed(): void { Assert::assertTrue($this->initialized, 'Element was initialized'); @@ -93,6 +117,10 @@ public function assertWasUsed(): void Assert::assertTrue($this->flushed, 'Element was flushed'); } + /** + * Assert that component was not used (depends on extending class). + * Also ensure that component was (or was not) initialized & flushed. + */ public function assertWasNotUsed(bool $initialized = false, bool $flushed = false): void { Assert::assertSame( diff --git a/src/Test/Job/Item/Writer/InMemoryWriter.php b/src/Test/Job/Item/Writer/InMemoryWriter.php index 0e1a5d4..d4d3ff4 100644 --- a/src/Test/Job/Item/Writer/InMemoryWriter.php +++ b/src/Test/Job/Item/Writer/InMemoryWriter.php @@ -7,6 +7,12 @@ use Yokai\Batch\Job\Item\InitializableInterface; use Yokai\Batch\Job\Item\ItemWriterInterface; +/** + * This {@see ItemWriterInterface} should be used in test + * for components working with generic {@see ItemWriterInterface}. + * It provides convenient methods retrieve written items along execution + * and perform assertions on these. + */ final class InMemoryWriter implements ItemWriterInterface, InitializableInterface { /** diff --git a/src/Test/Job/Item/Writer/TestDebugWriter.php b/src/Test/Job/Item/Writer/TestDebugWriter.php index f267011..e8077c2 100644 --- a/src/Test/Job/Item/Writer/TestDebugWriter.php +++ b/src/Test/Job/Item/Writer/TestDebugWriter.php @@ -7,6 +7,11 @@ use Yokai\Batch\Job\Item\ItemWriterInterface; use Yokai\Batch\Test\Job\Item\TestDebugComponent; +/** + * This {@see ItemWriterInterface} should be used in test + * for components working with generic {@see ItemWriterInterface}. + * It provides convenient assertion methods to ensure your writer was used correctly. + */ final class TestDebugWriter extends TestDebugComponent implements ItemWriterInterface { private ItemWriterInterface $decorated; diff --git a/src/Test/Launcher/BufferingJobLauncher.php b/src/Test/Launcher/BufferingJobLauncher.php index f6e959f..61dc100 100644 --- a/src/Test/Launcher/BufferingJobLauncher.php +++ b/src/Test/Launcher/BufferingJobLauncher.php @@ -9,6 +9,11 @@ use Yokai\Batch\JobParameters; use Yokai\Batch\Launcher\JobLauncherInterface; +/** + * This {@see JobLauncherInterface} should be used in test. + * It will remember launched executions + * and will allow you to fetch these for assertions. + */ final class BufferingJobLauncher implements JobLauncherInterface { /** diff --git a/src/Test/Storage/InMemoryJobExecutionStorage.php b/src/Test/Storage/InMemoryJobExecutionStorage.php index 2bcdce0..e0b8e2a 100644 --- a/src/Test/Storage/InMemoryJobExecutionStorage.php +++ b/src/Test/Storage/InMemoryJobExecutionStorage.php @@ -9,6 +9,11 @@ use Yokai\Batch\JobExecution; use Yokai\Batch\Storage\JobExecutionStorageInterface; +/** + * This {@see JobExecutionStorageInterface} should be used in test. + * It will store executions in memory + * and will allow you to fetch these for assertions. + */ final class InMemoryJobExecutionStorage implements JobExecutionStorageInterface { /** diff --git a/src/Test/Storage/JobExecutionStorageTestTrait.php b/src/Test/Storage/JobExecutionStorageTestTrait.php index 0ae9b1a..21c09d5 100644 --- a/src/Test/Storage/JobExecutionStorageTestTrait.php +++ b/src/Test/Storage/JobExecutionStorageTestTrait.php @@ -7,6 +7,9 @@ use PHPUnit\Framework\Assert; use Yokai\Batch\JobExecution; +/** + * Handy methods for JobExecution storage test classes. + */ trait JobExecutionStorageTestTrait { private static function assertExecutions(array $expectedCouples, iterable $executions): void diff --git a/src/Trigger/Scheduler/SchedulerInterface.php b/src/Trigger/Scheduler/SchedulerInterface.php index 2335aab..404b4d1 100644 --- a/src/Trigger/Scheduler/SchedulerInterface.php +++ b/src/Trigger/Scheduler/SchedulerInterface.php @@ -12,6 +12,8 @@ interface SchedulerInterface { /** + * Get list of job to schedule. + * * @return ScheduledJob[] * @phpstan-return iterable */ diff --git a/src/Trigger/Scheduler/TimeScheduler.php b/src/Trigger/Scheduler/TimeScheduler.php index ae49182..ad6b449 100644 --- a/src/Trigger/Scheduler/TimeScheduler.php +++ b/src/Trigger/Scheduler/TimeScheduler.php @@ -10,7 +10,7 @@ /** * This scheduler implementation uses constructor settings to compute schedules. - * The main setting is a @see DateTimeInterface that will be converted to a closure, + * The main setting is a {@see DateTimeInterface} that will be converted to a closure, * if that date is before job execution start time, the associated job schedule will be triggered. * * Example : diff --git a/src/Trigger/TriggerScheduledJobsJob.php b/src/Trigger/TriggerScheduledJobsJob.php index 78bc715..1e4833c 100644 --- a/src/Trigger/TriggerScheduledJobsJob.php +++ b/src/Trigger/TriggerScheduledJobsJob.php @@ -11,7 +11,7 @@ /** * This job is able to automatically trigger other jobs when you decide it. - * It rely on a list of @see SchedulerInterface that tells this job what jobs to trigger. + * It rely on a list of {@see SchedulerInterface} that tells this job what jobs to trigger. * * This job can be launched using a crontab, so the jobs you scheduled will be evaluated at each crontab rotation. */