Issue #3503179 by slucero, johnle: Add PatternUpdateEvent Subscriber Base Class and Validation Tools

Author: Stephen Lucero

phpstan.neon

@@ -58,9 +58,6 @@ parameters:
         - *Test.php
 
     # Ignore dependency injection warnings for intentional lazy-loader methods.
-    - message: '#^\\Drupal calls should be avoided in classes, use dependency injection instead$#'
-      count: 2
-      path: src/Event/PatternUpdateEvent.php
     - message: '#^\\Drupal calls should be avoided in classes, use dependency injection instead$#'
       count: 1
       path: src/LayoutHelper.php

src/Event/PatternUpdateEvent.php

@@ -4,25 +4,29 @@
 
 use Drupal\Component\EventDispatcher\Event;
 use Drupal\patternkit\Entity\PatternInterface;
-use Drupal\patternkit\Exception\SchemaValidationException;
+use Drupal\patternkit\PatternValidationTrait;
 use Drupal\patternkit\Plugin\Block\PatternkitBlock;
-use Swaggest\JsonSchema\InvalidValue;
 
 /**
  * An event triggered when a pattern in use is being updated.
  *
  * @event
  *
  * @see \Drupal\patternkit\PatternkitEvents::PATTERN_UPDATE
+ * @see \Drupal\patternkit\EventSubscriber\PatternUpdateEventSubscriberBase
  */
 class PatternUpdateEvent extends Event {
 
+  use PatternValidationTrait {
+    validateContent as traitValidateContent;
+  }
+
   /**
    * Content for the pattern instance at the time of updating.
    *
    * @var array
    */
-  protected array $originalContent;
+  protected readonly array $originalContent;
 
   /**
    * Content for the pattern instance that may have been altered.
@@ -38,6 +42,13 @@ class PatternUpdateEvent extends Event {
    */
   protected bool $isAltered = FALSE;
 
+  /**
+   * A flag to track whether the contained pattern content is valid.
+   *
+   * @var bool
+   */
+  protected bool $isValid;
+
   /**
    * Create a new PatternUpdateEvent instance.
    *
@@ -91,24 +102,61 @@ public function isAltered(): bool {
     return $this->isAltered;
   }
 
+  /**
+   * Determine if content for a component is valid for the pattern schema.
+   *
+   * @return bool
+   *   True if the content is valid, false otherwise.
+   */
+  public function isValid(): bool {
+    if (!isset($this->isValid)) {
+      $this->isValid = $this->validateContent($this->getContent());
+    }
+
+    return $this->isValid;
+  }
+
   /**
    * Assign new content for the component.
    *
    * @param array $content
    *   Content values to be assigned to the pattern component.
+   * @param bool $allowInvalid
+   *   (Optional) A flag to allow invalid content to be set and validation to be
+   *   ignored. Defaults to FALSE. The primary use case for this is when
+   *   supporting sequential content updates that may produce invalid content
+   *   along the way, but the final result after all updates have been executed
+   *   is expected to be valid.
    *
    * @throws \Drupal\patternkit\Exception\SchemaValidationException
    *   Throws an exception when the provided content does not validate
-   *   against the updated pattern schema.
+   *   against the updated pattern schema. This is only thrown if $allowInvalid
+   *   remains FALSE.
+   *
+   * @see \Drupal\patternkit\Event\PatternUpdateEvent::getExceptions()
+   *
+   * @return $this
    */
-  public function setContent(array $content): void {
-    if ($this->validateContent($content)) {
+  public function setContent(array $content, bool $allowInvalid = FALSE): self {
+    $isValid = $this->validateContent($content);
+
+    // Only throw the exceptions if invalid content is not allowed.
+    if (!$isValid && !$allowInvalid) {
+      $encountered_exceptions = $this->getExceptions();
+      assert(count($encountered_exceptions) > 0);
+
+      // Throw the exception before content assignment if invalid content is not
+      // allowed.
+      throw $encountered_exceptions[0];
+    }
+
+    if ($isValid || $allowInvalid) {
       $this->content = $content;
       $this->isAltered = TRUE;
+      $this->isValid = $isValid;
     }
-    else {
-      throw new SchemaValidationException('Assigned content does not validate successfully.');
-    }
+
+    return $this;
   }
 
   /**
@@ -121,6 +169,46 @@ public function getPattern(): PatternInterface {
     return $this->newPattern;
   }
 
+  /**
+   * Get the label for the updated pattern entity from schema data.
+   *
+   * @return string
+   *   The label for the updated pattern entity.
+   */
+  public function getPatternName(): string {
+    return $this->newPattern->getName();
+  }
+
+  /**
+   * Get the asset ID for the updated pattern entity.
+   *
+   * @return string
+   *   The pattern asset ID for the updated pattern entity.
+   */
+  public function getPatternAssetId(): string {
+    return $this->newPattern->getAssetId();
+  }
+
+  /**
+   * Get the label for the pre-update pattern entity from schema data.
+   *
+   * @return string
+   *   The label for the pre-update pattern entity.
+   */
+  public function getOriginalPatternName(): string {
+    return $this->oldPattern->getName();
+  }
+
+  /**
+   * Get the asset ID for the pre-update pattern entity.
+   *
+   * @return string
+   *   The pattern asset ID for the pre-update pattern entity.
+   */
+  public function getOriginalPatternAssetId(): string {
+    return $this->oldPattern->getAssetId();
+  }
+
   /**
    * Get the original pattern entity.
    *
@@ -149,28 +237,11 @@ public function getPlugin(): PatternkitBlock {
    *
    * @return bool
    *   True if the content validates successfully. False otherwise.
-   *
-   * @todo Expose this somewhere as a standard validation solution.
    */
-  protected function validateContent(array $content): bool {
-    $schema_string = $this->newPattern->getSchema();
-
-    /** @var \Drupal\patternkit\Schema\SchemaFactory $schema_factory */
-    $schema_factory = \Drupal::service('patternkit.schema.schema_factory');
-    $schema = $schema_factory->createInstance($schema_string);
-
-    /** @var \Drupal\patternkit\Schema\ContextBuilder $context_builder */
-    $context_builder = \Drupal::service('patternkit.schema.context_builder');
-    $context = $context_builder->getDefaultContext();
-
-    try {
-      $schema->in($content, $context);
-    }
-    catch (InvalidValue $exception) {
-      return FALSE;
-    }
-
-    return TRUE;
+  public function validateContent(array $content): bool {
+    // This is overridden for convenience to automatically pass in the updated
+    // pattern for reference.
+    return $this->traitValidateContent($this->newPattern, $content);
   }
 
 }

src/EventSubscriber/PatternUpdateEventSubscriberBase.php

@@ -0,0 +1,88 @@
+<?php
+
+namespace Drupal\patternkit\EventSubscriber;
+
+use Drupal\patternkit\Event\PatternUpdateEvent;
+use Drupal\patternkit\PatternkitEvents;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+
+/**
+ * A base event subscriber class to extend when subscribing to pattern updates.
+ *
+ * @see \Drupal\patternkit\PatternkitEvents::PATTERN_UPDATE
+ * @see \Drupal\patternkit\Event\PatternUpdateEvent
+ */
+abstract class PatternUpdateEventSubscriberBase implements EventSubscriberInterface {
+
+  /**
+   * The event subscriber priority for responding to the pattern update event.
+   *
+   * This may be overridden by inheriting classes to customize the order
+   * subscribers are executed during an update event.
+   */
+  const UPDATE_PRIORITY = 200;
+
+  /**
+   * {@inheritdoc}
+   */
+  public static function getSubscribedEvents(): array {
+    $events[PatternkitEvents::PATTERN_UPDATE] = [
+      'onPatternUpdate',
+      static::UPDATE_PRIORITY,
+    ];
+
+    return $events;
+  }
+
+  /**
+   * React to the pattern update process and log alter text values.
+   *
+   * Unless further customization is needed, inheriting classes should override
+   * the related `isApplicable()` and `doUpdate()` methods instead of this one.
+   *
+   * @param \Drupal\patternkit\Event\PatternUpdateEvent $event
+   *   The pattern update event containing all update information.
+   *
+   * @see static::isApplicable()
+   * @see static::doUpdate()
+   */
+  public function onPatternUpdate(PatternUpdateEvent $event): void {
+    if ($this->isApplicable($event)) {
+      $this->doUpdate($event);
+    }
+  }
+
+  /**
+   * Test whether an update is applicable for the current event.
+   *
+   * Inheriting classes should override this method to apply their own
+   * conditional logic to determine if their subscriber should be applied to
+   * the specific pattern update in progress.
+   *
+   * @param \Drupal\patternkit\Event\PatternUpdateEvent $event
+   *   The pattern update event in progress.
+   *
+   * @return bool
+   *   Returns true if this update subscriber is applicable for the current
+   *   event. Returns false otherwise.
+   *
+   * @see static::onPatternUpdate()
+   */
+  abstract public function isApplicable(PatternUpdateEvent $event): bool;
+
+  /**
+   * Implement update behavior for the active pattern update event.
+   *
+   * Inheriting classes should override this method to apply their own
+   * update logic and applicable changes. This method assumes applicability of
+   * the event has already been confirmed with the `isApplicable()` method.
+   *
+   * @param \Drupal\patternkit\Event\PatternUpdateEvent $event
+   *   The pattern update event in progress.
+   *
+   * @see static::onPatternUpdate()
+   * @see static::isApplicable()
+   */
+  abstract protected function doUpdate(PatternUpdateEvent $event): void;
+
+}

src/PatternValidationTrait.php

@@ -0,0 +1,89 @@
+<?php
+
+namespace Drupal\patternkit;
+
+use Drupal\patternkit\Entity\PatternInterface;
+use Drupal\patternkit\Exception\SchemaValidationException;
+use Drupal\patternkit\Schema\ContextBuilderTrait;
+use Drupal\patternkit\Schema\SchemaFactoryTrait;
+use Swaggest\JsonSchema\InvalidValue;
+
+/**
+ * A supporting trait for validating pattern content.
+ */
+trait PatternValidationTrait {
+
+  use ContextBuilderTrait;
+  use SchemaFactoryTrait;
+
+  /**
+   * An array of any exceptions encountered during validation.
+   *
+   * @var array<\Drupal\patternkit\Exception\SchemaValidationException>
+   */
+  protected array $exceptions = [];
+
+  /**
+   * Validate content being assigned to the pattern component.
+   *
+   * @param \Drupal\patternkit\Entity\PatternInterface $pattern
+   *   The pattern instance for content to be validated against.
+   * @param array $content
+   *   The content values being assigned to the pattern component.
+   *
+   * @return bool
+   *   True if the content validates successfully. False otherwise.
+   */
+  protected function validateContent(PatternInterface $pattern, array $content): bool {
+    // Create a schema object instance with the pattern's saved schema.
+    $schema_string = $pattern->getSchema();
+    $schema = $this->schemaFactory()->createInstance($schema_string);
+
+    // Load the default context for use during validation.
+    $context = $this->contextBuilder()->getDefaultContext();
+
+    try {
+      // Feed the content into the schema object with the default context to
+      // test for validation.
+      $schema->in($content, $context);
+    }
+    catch (InvalidValue $exception) {
+      $exception = new SchemaValidationException(
+        message: 'Assigned content does not validate successfully.',
+        previous: $exception,
+      );
+
+      // Insert exception at the beginning to keep the most recent exceptions
+      // first.
+      array_unshift($this->exceptions, $exception);
+
+      // Return false if a validation error was encountered.
+      return FALSE;
+    }
+
+    // If we got here, no validation error was encountered so the content
+    // should be valid.
+    return TRUE;
+  }
+
+  /**
+   * Tests if exceptions have been encountered during validation.
+   *
+   * @return bool
+   *   Returns TRUE if an exception has been encountered, FALSE otherwise.
+   */
+  public function hasExceptions(): bool {
+    return !empty($this->exceptions);
+  }
+
+  /**
+   * Get an array of all exceptions that have been encountered.
+   *
+   * @return array<\Drupal\patternkit\Exception\SchemaValidationException>
+   *   An array of all validation exceptions that have been encountered.
+   */
+  public function getExceptions(): array {
+    return $this->exceptions;
+  }
+
+}

src/Schema/ContextBuilderTrait.php

@@ -6,6 +6,8 @@
  * A trait for accessing the ContextBuilder service and setting it for use.
  *
  * @see \Drupal\patternkit\Schema\ContextBuilder
+ *
+ * @internal
  */
 trait ContextBuilderTrait {