Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\ImageToolkit;
Chris@0: 
Chris@0: use Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException;
Chris@0: use Drupal\Core\Plugin\PluginBase;
Chris@0: use Psr\Log\LoggerInterface;
Chris@0: 
Chris@0: /**
Chris@0:  * Provides a base class for image toolkit operation plugins.
Chris@0:  *
Chris@0:  * @see \Drupal\Core\ImageToolkit\Annotation\ImageToolkitOperation
Chris@0:  * @see \Drupal\Core\ImageToolkit\ImageToolkitOperationInterface
Chris@0:  * @see \Drupal\Core\ImageToolkit\ImageToolkitOperationManager
Chris@0:  * @see plugin_api
Chris@0:  */
Chris@0: abstract class ImageToolkitOperationBase extends PluginBase implements ImageToolkitOperationInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * The image toolkit.
Chris@0:    *
Chris@0:    * @var \Drupal\Core\ImageToolkit\ImageToolkitInterface
Chris@0:    */
Chris@0:   protected $toolkit;
Chris@0: 
Chris@0:   /**
Chris@0:    * A logger instance.
Chris@0:    *
Chris@0:    * @var \Psr\Log\LoggerInterface
Chris@0:    */
Chris@0:   protected $logger;
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs an image toolkit operation plugin.
Chris@0:    *
Chris@0:    * @param array $configuration
Chris@0:    *   A configuration array containing information about the plugin instance.
Chris@0:    * @param string $plugin_id
Chris@0:    *   The plugin_id for the plugin instance.
Chris@0:    * @param array $plugin_definition
Chris@0:    *   The plugin implementation definition.
Chris@0:    * @param \Drupal\Core\ImageToolkit\ImageToolkitInterface $toolkit
Chris@0:    *   The image toolkit.
Chris@0:    * @param \Psr\Log\LoggerInterface $logger
Chris@0:    *   A logger instance.
Chris@0:    */
Chris@0:   public function __construct(array $configuration, $plugin_id, array $plugin_definition, ImageToolkitInterface $toolkit, LoggerInterface $logger) {
Chris@0:     parent::__construct($configuration, $plugin_id, $plugin_definition);
Chris@0:     $this->toolkit = $toolkit;
Chris@0:     $this->logger = $logger;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the image toolkit instance for this operation.
Chris@0:    *
Chris@0:    * Image toolkit implementers should provide a toolkit operation base class
Chris@0:    * that overrides this method to correctly document the return type of this
Chris@0:    * getter. This provides better DX (code checking and code completion) for
Chris@0:    * image toolkit operation developers.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\ImageToolkit\ImageToolkitInterface
Chris@0:    */
Chris@0:   protected function getToolkit() {
Chris@0:     return $this->toolkit;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the definition of the operation arguments.
Chris@0:    *
Chris@0:    * Image toolkit operation implementers must implement this method to
Chris@0:    * "document" their operation, thus also if no arguments are expected.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array whose keys are the names of the arguments (e.g. "width",
Chris@0:    *   "degrees") and each value is an associative array having the following
Chris@0:    *   keys:
Chris@0:    *   - description: A string with the argument description. This is used only
Chris@0:    *     internally for documentation purposes, so it does not need to be
Chris@0:    *     translatable.
Chris@0:    *   - required: (optional) A boolean indicating if this argument should be
Chris@0:    *     provided or not. Defaults to TRUE.
Chris@0:    *   - default: (optional) When the argument is set to "required" = FALSE,
Chris@0:    *     this must be set to a default value. Ignored for "required" = TRUE
Chris@0:    *     arguments.
Chris@0:    */
Chris@0:   abstract protected function arguments();
Chris@0: 
Chris@0:   /**
Chris@0:    * Checks if required arguments are passed in and adds defaults for non passed
Chris@0:    * in optional arguments.
Chris@0:    *
Chris@0:    * Image toolkit operation implementers should not normally need to override
Chris@0:    * this method as they should place their own validation in validateArguments.
Chris@0:    *
Chris@0:    * @param array $arguments
Chris@0:    *   An associative array of arguments to be used by the toolkit operation.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The prepared arguments array.
Chris@0:    *
Chris@0:    * @throws \InvalidArgumentException.
Chris@0:    * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException.
Chris@0:    */
Chris@0:   protected function prepareArguments(array $arguments) {
Chris@0:     foreach ($this->arguments() as $id => $argument) {
Chris@0:       $argument += ['required' => TRUE];
Chris@0:       // Check if the argument is required and, if so, has been provided.
Chris@0:       if ($argument['required']) {
Chris@0:         if (!array_key_exists($id, $arguments)) {
Chris@0:           // If the argument is required throw an exception.
Chris@0:           throw new \InvalidArgumentException("Argument '$id' expected by plugin '{$this->getPluginId()}' but not passed");
Chris@0:         }
Chris@0:       }
Chris@0:       else {
Chris@0:         // Optional arguments require a 'default' value.
Chris@0:         // We check this even if the argument is provided by the caller, as we
Chris@0:         // want to fail fast here, i.e. at development time.
Chris@0:         if (!array_key_exists('default', $argument)) {
Chris@0:           // The plugin did not define a default, so throw a plugin exception,
Chris@0:           // not an invalid argument exception.
Chris@0:           throw new InvalidPluginDefinitionException("Default for argument '$id' expected by plugin '{$this->getPluginId()}' but not defined");
Chris@0:         }
Chris@0: 
Chris@0:         // Use the default value if the argument is not passed in.
Chris@0:         if (!array_key_exists($id, $arguments)) {
Chris@0:           $arguments[$id] = $argument['default'];
Chris@0:         }
Chris@0:       }
Chris@0:     }
Chris@0:     return $arguments;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Validates the arguments.
Chris@0:    *
Chris@0:    * Image toolkit operation implementers should place any argument validation
Chris@0:    * in this method, throwing an InvalidArgumentException when an error is
Chris@0:    * encountered.
Chris@0:    *
Chris@0:    * Validation typically includes things like:
Chris@0:    * - Checking that width and height are not negative.
Chris@0:    * - Checking that a color value is indeed a color.
Chris@0:    *
Chris@0:    * But validation may also include correcting the arguments, e.g:
Chris@0:    * - Casting arguments to the correct type.
Chris@0:    * - Rounding pixel values to an integer.
Chris@0:    *
Chris@0:    * This base implementation just returns the array of arguments and thus does
Chris@0:    * not need to be called by overriding methods.
Chris@0:    *
Chris@0:    * @param array $arguments
Chris@0:    *   An associative array of arguments to be used by the toolkit operation.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The validated and corrected arguments array.
Chris@0:    *
Chris@0:    * @throws \InvalidArgumentException
Chris@0:    *   If one or more of the arguments are not valid.
Chris@0:    * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
Chris@0:    *   If the plugin does not define a default for an optional argument.
Chris@0:    */
Chris@0:   protected function validateArguments(array $arguments) {
Chris@0:     return $arguments;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * {@inheritdoc}
Chris@0:    */
Chris@0:   final public function apply(array $arguments) {
Chris@0:     $arguments = $this->prepareArguments($arguments);
Chris@0:     $arguments = $this->validateArguments($arguments);
Chris@0:     return $this->execute($arguments);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Performs the actual manipulation on the image.
Chris@0:    *
Chris@0:    * Image toolkit operation implementers must implement this method. This
Chris@0:    * method is responsible for actually performing the operation on the image.
Chris@0:    * When this method gets called, the implementer may assume all arguments,
Chris@0:    * also the optional ones, to be available, validated and corrected.
Chris@0:    *
Chris@0:    * @param array $arguments
Chris@0:    *   An associative array of arguments to be used by the toolkit operation.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the operation was performed successfully, FALSE otherwise.
Chris@0:    */
Chris@0:   abstract protected function execute(array $arguments);
Chris@0: 
Chris@0: }