#64 - Throw exceptions implementing ProcessExceptionInterface instead of raw SPL exceptions

CHANGELOG.md

@@ -2,6 +2,7 @@ Latest
 ------
 
 ### Changes
+* [#64](https://github.com/cleverage/doctrine-process-bundle/issues/64) The bundle throws exceptions implementing `ProcessExceptionInterface` of the process bundle instead of raw SPL exceptions (as [cleverage/process-bundle#317](https://github.com/cleverage/process-bundle/issues/317)): new `Exception\UnexpectedValueException` and `Exception\RuntimeException`, extending the SPL exceptions thrown before (same messages, the existing `catch` keep working). Add tests.
 * [#62](https://github.com/cleverage/doctrine-process-bundle/issues/62) Composer: require PHP `^8.2` instead of `>=8.2` (PHP 9 is no longer accepted before being tested), remove the authorization of the `symfony/flex` plugin, which is not required (the CI installs it globally), as [cleverage/process-bundle#319](https://github.com/cleverage/process-bundle/issues/319).
 * [#58](https://github.com/cleverage/doctrine-process-bundle/issues/58) `DoctrineReaderTask` (`order_by` option): pass the `\SortDirection` enum to `QueryBuilder::addOrderBy()` when doctrine/orm accepts it (3.7 or later, where a string direction is deprecated), the string otherwise (same query). Require `psr/log` `^2 || ^3`: process-bundle does not work with psr/log 1. The tests fail on deprecations and boot a kernel with process-bundle and DoctrineBundle.
 * [#57](https://github.com/cleverage/doctrine-process-bundle/issues/57) Define the public API (Symfony BC promise, as [cleverage/process-bundle#279](https://github.com/cleverage/process-bundle/issues/279)): the concrete tasks (`DatabaseReaderTask`, `DatabaseUpdaterTask`, `DoctrineReaderTask`, `DoctrineWriterTask`, `DoctrineBatchWriterTask`, `DoctrineCleanerTask`, `DoctrineDetacherTask`, `DoctrineRefresherTask`, `DoctrineRemoverTask`, `ClearEntityManagerTask`) and `CleverAgeDoctrineProcessBundle` are marked `@final since 3.3`, they will be `final` in 4.0: extending them triggers a deprecation with the Symfony `DebugClassLoader`. `AbstractDoctrineTask` and `AbstractDoctrineQueryTask` stay open. `CleverAgeDoctrineProcessExtension` is marked `@internal`.

src/Exception/RuntimeException.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the CleverAge/DoctrineProcessBundle package.
+ *
+ * Copyright (c) Clever-Age
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace CleverAge\DoctrineProcessBundle\Exception;
+
+use CleverAge\ProcessBundle\Exception\ProcessExceptionInterface;
+
+/**
+ * Thrown by the bundle, can be caught with the ProcessExceptionInterface of the process bundle.
+ */
+class RuntimeException extends \RuntimeException implements ProcessExceptionInterface
+{
+}

src/Exception/UnexpectedValueException.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the CleverAge/DoctrineProcessBundle package.
+ *
+ * Copyright (c) Clever-Age
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace CleverAge\DoctrineProcessBundle\Exception;
+
+use CleverAge\ProcessBundle\Exception\ProcessExceptionInterface;
+
+/**
+ * Thrown by the bundle, can be caught with the ProcessExceptionInterface of the process bundle.
+ */
+class UnexpectedValueException extends \UnexpectedValueException implements ProcessExceptionInterface
+{
+}

src/Task/Database/DatabaseReaderTask.php

@@ -13,6 +13,7 @@
 
 namespace CleverAge\DoctrineProcessBundle\Task\Database;
 
+use CleverAge\DoctrineProcessBundle\Exception\UnexpectedValueException;
 use CleverAge\ProcessBundle\Model\AbstractConfigurableTask;
 use CleverAge\ProcessBundle\Model\FinalizableTaskInterface;
 use CleverAge\ProcessBundle\Model\IterableTaskInterface;
@@ -155,7 +156,7 @@ protected function initializeStatement(ProcessState $state): Result
         $inputAsParams = $state->getInput();
         $params = $options['input_as_params'] ? $inputAsParams : $options['params'];
         if (!\is_array($params)) {
-            throw new \UnexpectedValueException('Expecting an array of params');
+            throw new UnexpectedValueException('Expecting an array of params');
         }
 
         /** @var array<string, mixed> $params */

src/Task/Database/DatabaseUpdaterTask.php

@@ -13,6 +13,7 @@
 
 namespace CleverAge\DoctrineProcessBundle\Task\Database;
 
+use CleverAge\DoctrineProcessBundle\Exception\UnexpectedValueException;
 use CleverAge\ProcessBundle\Model\AbstractConfigurableTask;
 use CleverAge\ProcessBundle\Model\ProcessState;
 use Doctrine\DBAL\ArrayParameterType;
@@ -67,7 +68,7 @@ protected function initializeStatement(ProcessState $state): int
         $inputAsParams = $state->getInput();
         $params = $options['input_as_params'] ? $inputAsParams : $options['params'];
         if (!\is_array($params)) {
-            throw new \UnexpectedValueException('Expecting an array of params');
+            throw new UnexpectedValueException('Expecting an array of params');
         }
 
         /** @var array<string, mixed> $params */

src/Task/EntityManager/AbstractDoctrineQueryTask.php

@@ -13,6 +13,7 @@
 
 namespace CleverAge\DoctrineProcessBundle\Task\EntityManager;
 
+use CleverAge\DoctrineProcessBundle\Exception\UnexpectedValueException;
 use Doctrine\ORM\EntityRepository;
 use Doctrine\ORM\QueryBuilder;
 use Psr\Log\LogLevel;
@@ -83,7 +84,7 @@ protected function getQueryBuilder(
         $qb = $repository->createQueryBuilder('e');
         foreach ($criteria as $field => $value) {
             if (preg_match('/[^a-zA-Z0-9]/', $field)) {
-                throw new \UnexpectedValueException("Forbidden field name '{$field}'");
+                throw new UnexpectedValueException("Forbidden field name '{$field}'");
             }
             $parameterName = 'param_'.bin2hex(random_bytes(4));
             if (null === $value) {

src/Task/EntityManager/AbstractDoctrineTask.php

@@ -13,6 +13,7 @@
 
 namespace CleverAge\DoctrineProcessBundle\Task\EntityManager;
 
+use CleverAge\DoctrineProcessBundle\Exception\UnexpectedValueException;
 use CleverAge\ProcessBundle\Model\AbstractConfigurableTask;
 use CleverAge\ProcessBundle\Model\ProcessState;
 use Doctrine\ORM\EntityManagerInterface;
@@ -59,7 +60,7 @@ protected function getEntityManager(ProcessState $state, string $class): EntityM
             ? $this->doctrine->getManagerForClass($class)
             : $this->doctrine->getManager($entityManagerName);
         if (!$entityManager instanceof EntityManagerInterface) {
-            throw new \UnexpectedValueException("No manager found for class {$class}");
+            throw new UnexpectedValueException("No manager found for class {$class}");
         }
 
         return $entityManager;

src/Task/EntityManager/DoctrineCleanerTask.php

@@ -13,6 +13,7 @@
 
 namespace CleverAge\DoctrineProcessBundle\Task\EntityManager;
 
+use CleverAge\DoctrineProcessBundle\Exception\RuntimeException;
 use CleverAge\ProcessBundle\Model\ProcessState;
 use Doctrine\Common\Util\ClassUtils;
 
@@ -27,7 +28,7 @@ public function execute(ProcessState $state): void
     {
         $entity = $state->getInput();
         if (null === $entity) {
-            throw new \RuntimeException('DoctrineCleanerTask does not allow null input');
+            throw new RuntimeException('DoctrineCleanerTask does not allow null input');
         }
         /** @var object $entity */
         $class = ClassUtils::getClass($entity);

src/Task/EntityManager/DoctrineDetacherTask.php

@@ -13,6 +13,7 @@
 
 namespace CleverAge\DoctrineProcessBundle\Task\EntityManager;
 
+use CleverAge\DoctrineProcessBundle\Exception\RuntimeException;
 use CleverAge\ProcessBundle\Model\ProcessState;
 use Doctrine\Common\Util\ClassUtils;
 
@@ -27,7 +28,7 @@ public function execute(ProcessState $state): void
     {
         $entity = $state->getInput();
         if (null === $entity) {
-            throw new \RuntimeException('DoctrineDetacherTask does not allow null input');
+            throw new RuntimeException('DoctrineDetacherTask does not allow null input');
         }
         /** @var object $entity */
         $class = ClassUtils::getClass($entity);

src/Task/EntityManager/DoctrineRefresherTask.php

@@ -13,6 +13,7 @@
 
 namespace CleverAge\DoctrineProcessBundle\Task\EntityManager;
 
+use CleverAge\DoctrineProcessBundle\Exception\RuntimeException;
 use CleverAge\ProcessBundle\Model\ProcessState;
 use Doctrine\Common\Util\ClassUtils;
 
@@ -27,7 +28,7 @@ public function execute(ProcessState $state): void
     {
         $entity = $state->getInput();
         if (null === $entity) {
-            throw new \RuntimeException('DoctrineRefresherTask does not allow null input');
+            throw new RuntimeException('DoctrineRefresherTask does not allow null input');
         }
         /** @var object $entity */
         $class = ClassUtils::getClass($entity);

src/Task/EntityManager/DoctrineRemoverTask.php

@@ -13,6 +13,7 @@
 
 namespace CleverAge\DoctrineProcessBundle\Task\EntityManager;
 
+use CleverAge\DoctrineProcessBundle\Exception\RuntimeException;
 use CleverAge\ProcessBundle\Model\ProcessState;
 use Doctrine\Common\Util\ClassUtils;
 
@@ -27,7 +28,7 @@ public function execute(ProcessState $state): void
     {
         $entity = $state->getInput();
         if (null === $entity) {
-            throw new \RuntimeException('DoctrineRemoverTask does not allow null input');
+            throw new RuntimeException('DoctrineRemoverTask does not allow null input');
         }
         /** @var object $entity */
         $class = ClassUtils::getClass($entity);

src/Task/EntityManager/DoctrineWriterTask.php

@@ -13,6 +13,7 @@
 
 namespace CleverAge\DoctrineProcessBundle\Task\EntityManager;
 
+use CleverAge\DoctrineProcessBundle\Exception\RuntimeException;
 use CleverAge\ProcessBundle\Model\ProcessState;
 use Doctrine\Common\Util\ClassUtils;
 
@@ -35,7 +36,7 @@ protected function writeEntity(ProcessState $state): mixed
         $entity = $state->getInput();
 
         if (null === $entity) {
-            throw new \RuntimeException('DoctrineWriterTask does not allow null input');
+            throw new RuntimeException('DoctrineWriterTask does not allow null input');
         }
         $class = ClassUtils::getClass($entity);
         $entityManager = $this->getEntityManager($state, $class);

tests/Exception/SplExceptionsTest.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the CleverAge/DoctrineProcessBundle package.
+ *
+ * Copyright (c) Clever-Age
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace CleverAge\DoctrineProcessBundle\Tests\Exception;
+
+use CleverAge\DoctrineProcessBundle\Exception\RuntimeException;
+use CleverAge\DoctrineProcessBundle\Exception\UnexpectedValueException;
+use CleverAge\ProcessBundle\Exception\ProcessExceptionInterface;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * The exceptions thrown by the bundle can be caught as ProcessExceptionInterface, and still as the SPL exceptions they
+ * were before.
+ */
+#[CoversClass(UnexpectedValueException::class)]
+#[CoversClass(RuntimeException::class)]
+class SplExceptionsTest extends TestCase
+{
+    /**
+     * @return iterable<string, array{class-string<\Throwable>, class-string<\Throwable>}>
+     */
+    public static function provideExceptions(): iterable
+    {
+        yield 'UnexpectedValueException' => [UnexpectedValueException::class, \UnexpectedValueException::class];
+        yield 'RuntimeException' => [RuntimeException::class, \RuntimeException::class];
+    }
+
+    /**
+     * @param class-string<\Throwable> $class
+     * @param class-string<\Throwable> $splClass
+     */
+    #[DataProvider('provideExceptions')]
+    public function testExtendsTheSplExceptionAndImplementsTheInterface(string $class, string $splClass): void
+    {
+        $exception = new $class('message', 12);
+
+        self::assertInstanceOf($splClass, $exception);
+        self::assertInstanceOf(ProcessExceptionInterface::class, $exception);
+        self::assertSame(['message', 12], [$exception->getMessage(), $exception->getCode()]);
+    }
+}