Issue #3227923 by phenaproxima: Split StageException into more specific types

package_manager/src/Exception/StageException.php

+<?php
+
+namespace Drupal\package_manager\Exception;
+
+/**
+ * Base class for all exceptions related to staging operations.
+ */
+class StageException extends \RuntimeException {
+}

package_manager/src/Exception/StageOwnershipException.php

+<?php
+
+namespace Drupal\package_manager\Exception;
+
+/**
+ * Exception thrown if a stage encounters an ownership or locking error.
+ */
+class StageOwnershipException extends StageException {
+}

package_manager/src/StageException.php → package_manager/src/Exception/StageValidationException.php

 <?php
 
-namespace Drupal\package_manager;
+namespace Drupal\package_manager\Exception;
 
 /**
- * Exception thrown when the staging area encounters an error condition.
+ * Exception thrown if a stage has validation errors.
  */
-class StageException extends \RuntimeException {
+class StageValidationException extends StageException {
 
   /**
    * Any relevant validation results.

package_manager/src/Stage.php

@@ -13,6 +13,9 @@ use Drupal\package_manager\Event\PreCreateEvent;
 use Drupal\package_manager\Event\PreDestroyEvent;
 use Drupal\package_manager\Event\PreRequireEvent;
 use Drupal\package_manager\Event\StageEvent;
+use Drupal\package_manager\Exception\StageException;
+use Drupal\package_manager\Exception\StageOwnershipException;
+use Drupal\package_manager\Exception\StageValidationException;
 use PhpTuf\ComposerStager\Domain\BeginnerInterface;
 use PhpTuf\ComposerStager\Domain\CleanerInterface;
 use PhpTuf\ComposerStager\Domain\CommitterInterface;
@@ -199,7 +202,7 @@ class Stage {
    */
   public function create(): string {
     if (!$this->isAvailable()) {
-      throw new StageException([], 'Cannot create a new stage because one already exists.');
+      throw new StageException('Cannot create a new stage because one already exists.');
     }
     // Mark the stage as unavailable as early as possible, before dispatching
     // the pre-create event. The idea is to prevent a race condition if the
@@ -300,9 +303,9 @@ class Stage {
    * @param \Drupal\package_manager\Event\StageEvent $event
    *   The event object.
    *
-   * @throws \Drupal\package_manager\StageException
+   * @throws \Drupal\package_manager\Exception\StageValidationException
    *   If the event collects any validation errors, or a subscriber throws a
-   *   StageException directly.
+   *   StageValidationException directly.
    * @throws \RuntimeException
    *   If any other sort of error occurs.
    */
@@ -312,7 +315,7 @@ class Stage {
 
       $results = $event->getResults();
       if ($results) {
-        throw new StageException($results);
+        throw new StageValidationException($results);
       }
     }
     catch (\Throwable $error) {
@@ -324,8 +327,8 @@ class Stage {
       }
 
       // Wrap the exception to preserve the backtrace, and re-throw it.
-      if ($error instanceof StageException) {
-        throw new StageException($error->getResults(), $error->getMessage(), $error->getCode(), $error);
+      if ($error instanceof StageValidationException) {
+        throw new StageValidationException($error->getResults(), $error->getMessage(), $error->getCode(), $error);
       }
       else {
         throw new \RuntimeException($error->getMessage(), $error->getCode(), $error);
@@ -373,7 +376,7 @@ class Stage {
    *
    * @return $this
    *
-   * @throws \Drupal\package_manager\StageException
+   * @throws \Drupal\package_manager\Exception\StageException
    *   If the stage cannot be claimed. This can happen if the current user or
    *   session did not originally create the stage, if $unique_id doesn't match
    *   the unique ID that was generated when the stage was created, or the
@@ -383,19 +386,19 @@ class Stage {
    */
   final public function claim(string $unique_id): self {
     if ($this->isAvailable()) {
-      throw new StageException([], 'Cannot claim the stage because no stage has been created.');
+      throw new StageException('Cannot claim the stage because no stage has been created.');
     }
 
     $stored_lock = $this->tempStore->getIfOwner(self::TEMPSTORE_LOCK_KEY);
     if (!$stored_lock) {
-      throw new StageException([], 'Cannot claim the stage because it is not owned by the current user or session.');
+      throw new StageOwnershipException('Cannot claim the stage because it is not owned by the current user or session.');
     }
 
     if ($stored_lock === [$unique_id, static::class]) {
       $this->lock = $stored_lock;
       return $this;
     }
-    throw new StageException([], 'Cannot claim the stage because the current lock does not match the stored lock.');
+    throw new StageOwnershipException('Cannot claim the stage because the current lock does not match the stored lock.');
   }
 
   /**
@@ -403,7 +406,7 @@ class Stage {
    *
    * @throws \LogicException
    *   If ::claim() has not been previously called.
-   * @throws \Drupal\package_manager\StageException
+   * @throws \Drupal\package_manager\Exception\StageOwnershipException
    *   If the current user or session does not own the staging area.
    */
   final protected function checkOwnership(): void {
@@ -413,7 +416,7 @@ class Stage {
 
     $stored_lock = $this->tempStore->getIfOwner(static::TEMPSTORE_LOCK_KEY);
     if ($stored_lock !== $this->lock) {
-      throw new StageException([], 'Stage is not owned by the current user or session.');
+      throw new StageOwnershipException('Stage is not owned by the current user or session.');
     }
   }
 

package_manager/tests/src/Kernel/PackageManagerKernelTestBase.php

@@ -5,8 +5,9 @@ namespace Drupal\Tests\package_manager\Kernel;
 use Drupal\Core\DependencyInjection\ContainerBuilder;
 use Drupal\KernelTests\KernelTestBase;
 use Drupal\package_manager\Event\StageEvent;
+use Drupal\package_manager\Exception\StageException;
+use Drupal\package_manager\Exception\StageValidationException;
 use Drupal\package_manager\Stage;
-use Drupal\package_manager\StageException;
 use Drupal\Tests\package_manager\Traits\ValidationTestTrait;
 
 /**
@@ -84,7 +85,7 @@ abstract class PackageManagerKernelTestBase extends KernelTestBase {
       // If we did not get an exception, ensure we didn't expect any results.
       $this->assertEmpty($expected_results);
     }
-    catch (StageException $e) {
+    catch (StageValidationException $e) {
       $this->assertNotEmpty($expected_results);
       $this->assertValidationResultsEqual($expected_results, $e->getResults());
       // TestStage::dispatch() attaches the event object to the exception so

package_manager/tests/src/Kernel/StageEventsTest.php

@@ -13,8 +13,8 @@ use Drupal\package_manager\Event\PreDestroyEvent;
 use Drupal\package_manager\Event\PreRequireEvent;
 use Drupal\package_manager\Event\StageEvent;
 use Drupal\package_manager\Event\WarningEventInterface;
+use Drupal\package_manager\Exception\StageValidationException;
 use Drupal\package_manager\Stage;
-use Drupal\package_manager\StageException;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
 /**
@@ -158,9 +158,9 @@ class StageEventsTest extends PackageManagerKernelTestBase implements EventSubsc
       $this->stage->apply();
       $this->stage->destroy();
 
-      $this->fail('Expected \Drupal\package_manager\StageException to be thrown.');
+      $this->fail('Expected \Drupal\package_manager\Exception\StageValidationException to be thrown.');
     }
-    catch (StageException $e) {
+    catch (StageValidationException $e) {
       $this->assertCount(1, $e->getResults());
     }
   }

package_manager/tests/src/Kernel/StageOwnershipTest.php

@@ -3,7 +3,8 @@
 namespace Drupal\Tests\package_manager\Kernel;
 
 use Drupal\package_manager\Event\PreCreateEvent;
-use Drupal\package_manager\StageException;
+use Drupal\package_manager\Exception\StageException;
+use Drupal\package_manager\Exception\StageOwnershipException;
 use Drupal\package_manager_test_validation\TestSubscriber;
 use Drupal\Tests\user\Traits\UserCreationTrait;
 
@@ -95,7 +96,7 @@ class StageOwnershipTest extends PackageManagerKernelTestBase {
     try {
       $never_create->claim($stage_id);
     }
-    catch (StageException $exception) {
+    catch (StageOwnershipException $exception) {
       $this->assertSame('Cannot claim the stage because it is not owned by the current user or session.', $exception->getMessage());
     }
 
@@ -159,7 +160,7 @@ class StageOwnershipTest extends PackageManagerKernelTestBase {
       $this->createStage()->claim('not-correct-id');
       $this->fail('Was able to claim an owned stage with an incorrect ID.');
     }
-    catch (StageException $exception) {
+    catch (StageOwnershipException $exception) {
       $this->assertSame('Cannot claim the stage because the current lock does not match the stored lock.', $exception->getMessage());
     }
 
@@ -196,7 +197,7 @@ class StageOwnershipTest extends PackageManagerKernelTestBase {
     try {
       $this->createStage()->claim($new_stage_id);
     }
-    catch (StageException $exception) {
+    catch (StageOwnershipException $exception) {
       $this->assertSame('Cannot claim the stage because it is not owned by the current user or session.', $exception->getMessage());
     }
   }

src/Exception/UpdateException.php

@@ -2,10 +2,10 @@
 
 namespace Drupal\automatic_updates\Exception;
 
-use Drupal\package_manager\StageException;
+use Drupal\package_manager\Exception\StageValidationException;
 
 /**
  * Defines a custom exception for a failure during an update.
  */
-class UpdateException extends StageException {
+class UpdateException extends StageValidationException {
 }

src/Form/UpdateReady.php

@@ -9,7 +9,7 @@ use Drupal\Core\Form\FormBase;
 use Drupal\Core\Form\FormStateInterface;
 use Drupal\Core\Messenger\MessengerInterface;
 use Drupal\Core\State\StateInterface;
-use Drupal\package_manager\StageException;
+use Drupal\package_manager\Exception\StageOwnershipException;
 use Symfony\Component\DependencyInjection\ContainerInterface;
 
 /**
@@ -75,7 +75,7 @@ class UpdateReady extends FormBase {
     try {
       $this->updater->claim($stage_id);
     }
-    catch (StageException $e) {
+    catch (StageOwnershipException $e) {
       $this->messenger()->addError($this->t('Cannot continue the update because another Composer operation is currently in progress.'));
       return $form;
     }

src/Updater.php

@@ -5,8 +5,8 @@ namespace Drupal\automatic_updates;
 use Drupal\automatic_updates\Exception\UpdateException;
 use Drupal\package_manager\ComposerUtility;
 use Drupal\package_manager\Event\StageEvent;
+use Drupal\package_manager\Exception\StageValidationException;
 use Drupal\package_manager\Stage;
-use Drupal\package_manager\StageException;
 
 /**
  * Defines a service to perform updates.
@@ -95,7 +95,7 @@ class Updater extends Stage {
     try {
       parent::dispatch($event);
     }
-    catch (StageException $e) {
+    catch (StageValidationException $e) {
       throw new UpdateException($e->getResults(), $e->getMessage() ?: "Unable to complete the update because of errors.", $e->getCode(), $e);
     }
   }

tests/src/Kernel/ReadinessValidation/StagedProjectsValidatorTest.php

@@ -4,8 +4,8 @@ namespace Drupal\Tests\automatic_updates\Kernel\ReadinessValidation;
 
 use Drupal\Core\DependencyInjection\ContainerBuilder;
 use Drupal\package_manager\Event\PreApplyEvent;
+use Drupal\package_manager\Exception\StageValidationException;
 use Drupal\package_manager\PathLocator;
-use Drupal\package_manager\StageException;
 use Drupal\Tests\automatic_updates\Kernel\AutomaticUpdatesKernelTestBase;
 
 /**
@@ -65,7 +65,7 @@ class StagedProjectsValidatorTest extends AutomaticUpdatesKernelTestBase {
       $updater->apply();
       return [];
     }
-    catch (StageException $e) {
+    catch (StageValidationException $e) {
       return $e->getResults();
     }
   }