Convert BatchStatus and sort constants to PHP 8.1 backed enums

UPGRADE-1.0.md

@@ -214,6 +214,107 @@ composition instead. Extending `final` classes or `readonly` classes is a PHP co
 
 ---
 
+### `BatchStatus` is now a backed enum (BREAKING)
+
+`BatchStatus` has been converted from a `readonly class` with integer constants to a PHP 8.1
+`backed int enum`.
+
+#### Before / After
+
+```diff
+-use Yokai\Batch\BatchStatus;
+
+-$status = new BatchStatus(BatchStatus::PENDING);
+-$status->getValue(); // int
+-(string) $status;    // "PENDING"
+
++$status = BatchStatus::Pending;
++$status->value;  // int (1)
++$status->name;   // "Pending"
+```
+
+#### Removed
+
+| Removed | Replacement |
+|---------|-------------|
+| `BatchStatus::PENDING` (int constant) | `BatchStatus::Pending` (enum case) |
+| `BatchStatus::RUNNING` | `BatchStatus::Running` |
+| `BatchStatus::STOPPED` | `BatchStatus::Stopped` |
+| `BatchStatus::COMPLETED` | `BatchStatus::Completed` |
+| `BatchStatus::ABANDONED` | `BatchStatus::Abandoned` |
+| `BatchStatus::FAILED` | `BatchStatus::Failed` |
+| `BatchStatus::__construct(int $value)` | — |
+| `BatchStatus::getValue(): int` | `BatchStatus->value` (enum property) |
+| `BatchStatus::is(int $value): bool` | `=== BatchStatus::CaseName` |
+| `BatchStatus::isOneOf(int ...$values): bool` | `in_array($status, [...], true)` |
+| `BatchStatus::__toString()` | `BatchStatus->name` |
+
+#### Signature changes
+
+```diff
+-JobExecution::setStatus(BatchStatus $status)   // was: setStatus(int $value)
+-ExceptionEvent::getStatus(): BatchStatus       // was: getStatus(): int (via BatchStatus object)
+-ExceptionEvent::setStatus(BatchStatus $status) // was: setStatus(int $value)
+
+// QueryBuilder / Query
+-QueryBuilder::statuses(int ...$statuses): self
++QueryBuilder::statuses(BatchStatus ...$statuses): self
+
+-Query::statuses(): int[]
++Query::statuses(): BatchStatus[]
+```
+
+#### Usage example
+
+```php
+use Yokai\Batch\Storage\QueryBuilder;
+use Yokai\Batch\BatchStatus;
+
+$storage->purge(
+    (new QueryBuilder())
+        ->statuses(BatchStatus::Failed, BatchStatus::Abandoned)
+        ->getQuery()
+);
+```
+
+---
+
+### `SortDirection` is now a backed enum (BREAKING)
+
+The `SORT_BY_*` string constants on `Query` have been removed and replaced by the
+`SortDirection` backed string enum.
+
+#### Before / After
+
+```diff
+-use Yokai\Batch\Storage\Query;
++use Yokai\Batch\Storage\SortDirection;
+
+-(new QueryBuilder())->sort(Query::SORT_BY_END_DESC);
++(new QueryBuilder())->sort(SortDirection::EndDesc);
+```
+
+#### Removed
+
+| Removed | Replacement |
+|---------|-------------|
+| `Query::SORT_BY_START_ASC` | `SortDirection::StartAsc` |
+| `Query::SORT_BY_START_DESC` | `SortDirection::StartDesc` |
+| `Query::SORT_BY_END_ASC` | `SortDirection::EndAsc` |
+| `Query::SORT_BY_END_DESC` | `SortDirection::EndDesc` |
+
+#### Signature changes
+
+```diff
+-QueryBuilder::sort(string $by): self  // threw UnexpectedValueException on invalid values
++QueryBuilder::sort(SortDirection $by): self
+
+-Query::sort(): string|null
++Query::sort(): SortDirection|null
+```
+
+---
+
 ### New method: `QueryableJobExecutionStorageInterface::purge()` (BREAKING for custom implementations)
 
 A new method has been added to `QueryableJobExecutionStorageInterface`:
@@ -236,7 +337,7 @@ use Yokai\Batch\Storage\QueryBuilder;
 $storage->purge(
     (new QueryBuilder())
         ->jobs(['import'])
-        ->statuses([BatchStatus::FAILED])
+        ->statuses(BatchStatus::Failed)
         ->getQuery()
 );
 ```

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

@@ -19,6 +19,8 @@
 use Doctrine\DBAL\Types\Types;
 use Doctrine\Persistence\ConnectionRegistry;
 use Generator;
+use Yokai\Batch\BatchStatus;
+use Yokai\Batch\Storage\SortDirection;
 use Yokai\Batch\Exception\CannotRemoveJobExecutionException;
 use Yokai\Batch\Factory\JobExecutionLoggerFactoryInterface;
 use Yokai\Batch\Exception\CannotStoreJobExecutionException;
@@ -154,23 +156,13 @@ public function query(Query $query): iterable
 
         [$queryParameters, $queryTypes] = $this->addWheres($query, $qb);
 
-        switch ($query->sort()) {
-            case Query::SORT_BY_START_ASC:
-                $qb->orderBy('start_time', 'asc');
-                break;
-
-            case Query::SORT_BY_START_DESC:
-                $qb->orderBy('start_time', 'desc');
-                break;
-
-            case Query::SORT_BY_END_ASC:
-                $qb->orderBy('end_time', 'asc');
-                break;
-
-            case Query::SORT_BY_END_DESC:
-                $qb->orderBy('end_time', 'desc');
-                break;
-        }
+        match ($query->sort()) {
+            SortDirection::StartAsc  => $qb->orderBy('start_time', 'asc'),
+            SortDirection::StartDesc => $qb->orderBy('start_time', 'desc'),
+            SortDirection::EndAsc    => $qb->orderBy('end_time', 'asc'),
+            SortDirection::EndDesc   => $qb->orderBy('end_time', 'desc'),
+            default => null,
+        };
 
         $qb->setMaxResults($query->limit());
         $qb->setFirstResult($query->offset());
@@ -374,7 +366,7 @@ private function addWheres(Query $query, QueryBuilder $qb): array
         $statuses = $query->statuses();
         if ($statuses !== []) {
             $qb->andWhere($qb->expr()->in('status', ':statuses'));
-            $queryParameters['statuses'] = $statuses;
+            $queryParameters['statuses'] = \array_map(fn(BatchStatus $s) => $s->value, $statuses);
             $queryTypes['statuses'] = ArrayParameterType::INTEGER;
         }
 

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

@@ -64,7 +64,7 @@ public function toRow(JobExecution $jobExecution): array
         return [
             'id' => $jobExecution->getId(),
             'job_name' => $jobExecution->getJobName(),
-            'status' => $jobExecution->getStatus()->getValue(),
+            'status' => $jobExecution->getStatus()->value,
             'parameters' => \iterator_to_array($jobExecution->getParameters()),
             'start_time' => $jobExecution->getStartTime(),
             'end_time' => $jobExecution->getEndTime(),
@@ -85,7 +85,7 @@ public function toRow(JobExecution $jobExecution): array
     public function fromRow(array $data, JobExecution|null $parent = null): JobExecution
     {
         $name = $data['job_name'];
-        $status = new BatchStatus((int)$data['status']);
+        $status = BatchStatus::from((int)$data['status']);
         $parameters = new JobParameters($this->jsonFromString($data['parameters']));
         $summary = new Summary($this->jsonFromString($data['summary']));
 
@@ -137,7 +137,7 @@ private function toChildRow(JobExecution $jobExecution): array
     {
         return [
             'job_name' => $jobExecution->getJobName(),
-            'status' => $jobExecution->getStatus()->getValue(),
+            'status' => $jobExecution->getStatus()->value,
             'parameters' => \iterator_to_array($jobExecution->getParameters()),
             'start_time' => $this->toDateString($jobExecution->getStartTime()),
             'end_time' => $this->toDateString($jobExecution->getEndTime()),

src/batch-doctrine-dbal/tests/DoctrineDBALJobExecutionStorageTest.php

@@ -21,6 +21,7 @@
 use Yokai\Batch\JobExecution;
 use Yokai\Batch\Storage\Query;
 use Yokai\Batch\Storage\QueryBuilder;
+use Yokai\Batch\Storage\SortDirection;
 use Yokai\Batch\Test\Storage\JobExecutionStorageTestTrait;
 use Yokai\Batch\Warning;
 
@@ -108,7 +109,7 @@ public function testStoreInsert(): void
         $storage = $this->createStorage();
         $storage->setup();
 
-        $export = JobExecution::createRoot('123', 'export', new BatchStatus(BatchStatus::RUNNING));
+        $export = JobExecution::createRoot('123', 'export', BatchStatus::Running);
         $export->setStartTime(new DateTimeImmutable('2021-09-23 11:05:00'));
         $export->setLaunchedAt(new DateTimeImmutable('2021-09-23 11:04:55'));
         $export->addChildExecution($extract = JobExecution::createChild($export, 'extract'));
@@ -124,7 +125,7 @@ public function testStoreInsert(): void
         self::assertSame('2021-09-23 11:05:00', $retrievedExport->getStartTime()->format('Y-m-d H:i:s'));
         self::assertNull($retrievedExport->getEndTime());
         self::assertSame('2021-09-23 11:04:55', $retrievedExport->getLaunchedAt()->format('Y-m-d H:i:s'));
-        self::assertSame(BatchStatus::RUNNING, $retrievedExport->getStatus()->getValue());
+        self::assertSame(BatchStatus::Running, $retrievedExport->getStatus());
         $retrievedExtract = $retrievedExport->getChildExecution('extract');
         self::assertNotNull($retrievedExtract);
         self::assertSame('2021-09-23 11:05:01', $retrievedExtract->getStartTime()->format('Y-m-d H:i:s'));
@@ -146,13 +147,13 @@ public function testStoreUpdate(): void
         $storage = $this->createStorage();
         $storage->setup();
         $storage->store($execution = JobExecution::createRoot('123', 'export'));
-        $execution->setStatus(BatchStatus::COMPLETED);
+        $execution->setStatus(BatchStatus::Completed);
         $storage->store($execution);
 
         $retrievedExecution = $storage->retrieve('export', '123');
         self::assertSame('export', $retrievedExecution->getJobName());
         self::assertSame('123', $retrievedExecution->getId());
-        self::assertSame(BatchStatus::COMPLETED, $retrievedExecution->getStatus()->getValue());
+        self::assertSame(BatchStatus::Completed, $retrievedExecution->getStatus());
     }
 
     public function testStoreFailing(): void
@@ -228,7 +229,7 @@ public function testRetrieveInvalid(array $data, Throwable $error): void
 
         $data['id'] = '123';
         $data['job_name'] = 'export';
-        $data['status'] ??= BatchStatus::COMPLETED;
+        $data['status'] ??= BatchStatus::Completed->value;
         $data['parameters'] ??= '[]';
         $data['summary'] ??= '[]';
         $data['failures'] ??= '[]';
@@ -315,14 +316,14 @@ public static function queries(): Generator
         ];
         yield 'Filter statuses' => [
             (new QueryBuilder())
-                ->statuses([BatchStatus::FAILED]),
+                ->statuses([BatchStatus::Failed]),
             [
                 ['import', '456'],
             ],
         ];
         yield 'Order by start ASC' => [
             (new QueryBuilder())
-                ->sort(Query::SORT_BY_START_ASC),
+                ->sort(SortDirection::StartAsc),
             [
                 ['import', '987'],
                 ['import', '789'],
@@ -332,7 +333,7 @@ public static function queries(): Generator
         ];
         yield 'Order by start DESC' => [
             (new QueryBuilder())
-                ->sort(Query::SORT_BY_START_DESC),
+                ->sort(SortDirection::StartDesc),
             [
                 ['import', '456'],
                 ['export', '123'],
@@ -342,7 +343,7 @@ public static function queries(): Generator
         ];
         yield 'Order by end ASC' => [
             (new QueryBuilder())
-                ->sort(Query::SORT_BY_END_ASC),
+                ->sort(SortDirection::EndAsc),
             [
                 ['import', '789'],
                 ['import', '987'],
@@ -352,7 +353,7 @@ public static function queries(): Generator
         ];
         yield 'Order by end DESC' => [
             (new QueryBuilder())
-                ->sort(Query::SORT_BY_END_DESC),
+                ->sort(SortDirection::EndDesc),
             [
                 ['import', '456'],
                 ['export', '123'],
@@ -473,27 +474,27 @@ private static function assertExecutions(array $expectedCouples, iterable $execu
     private function loadFixtures(DoctrineDBALJobExecutionStorage $storage): void
     {
         // completed export started at 2019-07-01 13:00 and ended at 2019-07-01 13:30
-        $completedExport = JobExecution::createRoot('123', 'export', new BatchStatus(BatchStatus::COMPLETED));
+        $completedExport = JobExecution::createRoot('123', 'export', BatchStatus::Completed);
         $completedExport->setStartTime(\DateTimeImmutable::createFromFormat(DATE_ISO8601, '2019-07-01T13:00:00+0200'));
         $completedExport->setEndTime(\DateTimeImmutable::createFromFormat(DATE_ISO8601, '2019-07-01T13:30:00+0200'));
         $storage->store($completedExport);
 
         // failed import started at 2019-07-01 17:30 and ended at 2019-07-01 18:30
-        $failedImport = JobExecution::createRoot('456', 'import', new BatchStatus(BatchStatus::FAILED));
+        $failedImport = JobExecution::createRoot('456', 'import', BatchStatus::Failed);
         $failedImport->setStartTime(\DateTimeImmutable::createFromFormat(DATE_ISO8601, '2019-07-01T17:30:00+0200'));
         $failedImport->setEndTime(\DateTimeImmutable::createFromFormat(DATE_ISO8601, '2019-07-01T18:30:00+0200'));
         $storage->store($failedImport);
 
         // running import started at 2019-06-30 22:00 and not ended
-        $runningImport = JobExecution::createRoot('789', 'import', new BatchStatus(BatchStatus::RUNNING));
+        $runningImport = JobExecution::createRoot('789', 'import', BatchStatus::Running);
         $runningImport->setStartTime(\DateTimeImmutable::createFromFormat(DATE_ISO8601, '2019-06-30T22:00:00+0200'));
         $runningImport->getLogger()->debug('Importing things');
         $runningImport->getLogger()->info('Thing imported');
         $runningImport->getLogger()->warning('Weird thing imported');
         $storage->store($runningImport);
 
         // pending import not started and not ended
-        $pendingImport = JobExecution::createRoot('987', 'import', new BatchStatus(BatchStatus::PENDING));
+        $pendingImport = JobExecution::createRoot('987', 'import', BatchStatus::Pending);
         $storage->store($pendingImport);
     }
 }

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

@@ -32,7 +32,7 @@ public function launch(string $name, array $configuration = []): JobExecution
     {
         $jobExecution = $this->jobExecutionFactory->create($name, $configuration);
         $configuration['_id'] ??= $jobExecution->getId();
-        $jobExecution->setStatus(BatchStatus::PENDING);
+        $jobExecution->setStatus(BatchStatus::Pending);
         $this->jobExecutionStorage->store($jobExecution);
 
         $this->commandRunner->runAsync(

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

@@ -61,7 +61,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
     private function guessExecutionExitCode(JobExecution $jobExecution): int
     {
-        if ($jobExecution->getStatus()->is(BatchStatus::COMPLETED)) {
+        if ($jobExecution->getStatus() === BatchStatus::Completed) {
             if ($jobExecution->getAllWarnings() === []) {
                 return self::EXIT_SUCCESS_CODE;
             }
@@ -75,7 +75,7 @@ private function guessExecutionExitCode(JobExecution $jobExecution): int
     private function outputExecution(JobExecution $jobExecution, OutputInterface $output): void
     {
         $jobName = $jobExecution->getJobName();
-        if ($jobExecution->getStatus()->is(BatchStatus::COMPLETED)) {
+        if ($jobExecution->getStatus() === BatchStatus::Completed) {
             $warnings = $jobExecution->getAllWarnings();
             if ($warnings !== []) {
                 foreach ($warnings as $warning) {

src/batch-symfony-console/tests/RunCommandJobLauncherTest.php

@@ -46,7 +46,7 @@ public function testLaunch(): void
 
         self::assertSame('testing', $jobExecutionFromStorage->getJobName());
         self::assertSame('123456789', $jobExecutionFromStorage->getId());
-        self::assertSame(BatchStatus::PENDING, $jobExecutionFromStorage->getStatus()->getValue());
+        self::assertSame(BatchStatus::Pending, $jobExecutionFromStorage->getStatus());
         self::assertSame(['bar'], $jobExecutionFromStorage->getParameters()->get('foo'));
     }
 }

src/batch-symfony-framework/src/Resources/views/bootstrap4/_status.html.twig

@@ -2,13 +2,13 @@
 
 {# @var execution \Yokai\Batch\JobExecution #}
 {% set classMap = {
-    (constant('PENDING', execution.status)): 'light',
-    (constant('RUNNING', execution.status)): 'warning',
-    (constant('STOPPED', execution.status)): 'info',
-    (constant('COMPLETED', execution.status)): 'success',
-    (constant('ABANDONED', execution.status)): 'info',
-    (constant('FAILED', execution.status)): 'danger',
+    'Pending': 'light',
+    'Running': 'warning',
+    'Stopped': 'info',
+    'Completed': 'success',
+    'Abandoned': 'info',
+    'Failed': 'danger',
 } %}
-<span class="badge badge-{{ classMap[execution.status.value] }}">
-    {{ ('job.status.'~execution.status|lower)|trans }}
+<span class="badge badge-{{ classMap[execution.status.name] }}">
+    {{ ('job.status.'~execution.status.name|lower)|trans }}
 </span>

src/batch-symfony-framework/src/Resources/views/sonata/_status.html.twig

@@ -2,13 +2,13 @@
 
 {# @var execution \Yokai\Batch\JobExecution #}
 {% set classMap = {
-    (constant('PENDING', execution.status)): 'default',
-    (constant('RUNNING', execution.status)): 'warning',
-    (constant('STOPPED', execution.status)): 'info',
-    (constant('COMPLETED', execution.status)): 'success',
-    (constant('ABANDONED', execution.status)): 'info',
-    (constant('FAILED', execution.status)): 'danger',
+    'Pending': 'default',
+    'Running': 'warning',
+    'Stopped': 'info',
+    'Completed': 'success',
+    'Abandoned': 'info',
+    'Failed': 'danger',
 } %}
-<span class="label label-{{ classMap[execution.status.value] }}">
-    {{ ('job.status.'~execution.status|lower)|trans }}
+<span class="label label-{{ classMap[execution.status.name] }}">
+    {{ ('job.status.'~execution.status.name|lower)|trans }}
 </span>