annotate core/lib/Drupal/Core/ImageToolkit/ImageToolkitOperationBase.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 4c8ae668cc8c
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\Core\ImageToolkit;
Chris@0 4
Chris@0 5 use Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException;
Chris@0 6 use Drupal\Core\Plugin\PluginBase;
Chris@0 7 use Psr\Log\LoggerInterface;
Chris@0 8
Chris@0 9 /**
Chris@0 10 * Provides a base class for image toolkit operation plugins.
Chris@0 11 *
Chris@0 12 * @see \Drupal\Core\ImageToolkit\Annotation\ImageToolkitOperation
Chris@0 13 * @see \Drupal\Core\ImageToolkit\ImageToolkitOperationInterface
Chris@0 14 * @see \Drupal\Core\ImageToolkit\ImageToolkitOperationManager
Chris@0 15 * @see plugin_api
Chris@0 16 */
Chris@0 17 abstract class ImageToolkitOperationBase extends PluginBase implements ImageToolkitOperationInterface {
Chris@0 18
Chris@0 19 /**
Chris@0 20 * The image toolkit.
Chris@0 21 *
Chris@0 22 * @var \Drupal\Core\ImageToolkit\ImageToolkitInterface
Chris@0 23 */
Chris@0 24 protected $toolkit;
Chris@0 25
Chris@0 26 /**
Chris@0 27 * A logger instance.
Chris@0 28 *
Chris@0 29 * @var \Psr\Log\LoggerInterface
Chris@0 30 */
Chris@0 31 protected $logger;
Chris@0 32
Chris@0 33 /**
Chris@0 34 * Constructs an image toolkit operation plugin.
Chris@0 35 *
Chris@0 36 * @param array $configuration
Chris@0 37 * A configuration array containing information about the plugin instance.
Chris@0 38 * @param string $plugin_id
Chris@0 39 * The plugin_id for the plugin instance.
Chris@0 40 * @param array $plugin_definition
Chris@0 41 * The plugin implementation definition.
Chris@0 42 * @param \Drupal\Core\ImageToolkit\ImageToolkitInterface $toolkit
Chris@0 43 * The image toolkit.
Chris@0 44 * @param \Psr\Log\LoggerInterface $logger
Chris@0 45 * A logger instance.
Chris@0 46 */
Chris@0 47 public function __construct(array $configuration, $plugin_id, array $plugin_definition, ImageToolkitInterface $toolkit, LoggerInterface $logger) {
Chris@0 48 parent::__construct($configuration, $plugin_id, $plugin_definition);
Chris@0 49 $this->toolkit = $toolkit;
Chris@0 50 $this->logger = $logger;
Chris@0 51 }
Chris@0 52
Chris@0 53 /**
Chris@0 54 * Returns the image toolkit instance for this operation.
Chris@0 55 *
Chris@0 56 * Image toolkit implementers should provide a toolkit operation base class
Chris@0 57 * that overrides this method to correctly document the return type of this
Chris@0 58 * getter. This provides better DX (code checking and code completion) for
Chris@0 59 * image toolkit operation developers.
Chris@0 60 *
Chris@0 61 * @return \Drupal\Core\ImageToolkit\ImageToolkitInterface
Chris@0 62 */
Chris@0 63 protected function getToolkit() {
Chris@0 64 return $this->toolkit;
Chris@0 65 }
Chris@0 66
Chris@0 67 /**
Chris@0 68 * Returns the definition of the operation arguments.
Chris@0 69 *
Chris@0 70 * Image toolkit operation implementers must implement this method to
Chris@0 71 * "document" their operation, thus also if no arguments are expected.
Chris@0 72 *
Chris@0 73 * @return array
Chris@0 74 * An array whose keys are the names of the arguments (e.g. "width",
Chris@0 75 * "degrees") and each value is an associative array having the following
Chris@0 76 * keys:
Chris@0 77 * - description: A string with the argument description. This is used only
Chris@0 78 * internally for documentation purposes, so it does not need to be
Chris@0 79 * translatable.
Chris@0 80 * - required: (optional) A boolean indicating if this argument should be
Chris@0 81 * provided or not. Defaults to TRUE.
Chris@0 82 * - default: (optional) When the argument is set to "required" = FALSE,
Chris@0 83 * this must be set to a default value. Ignored for "required" = TRUE
Chris@0 84 * arguments.
Chris@0 85 */
Chris@0 86 abstract protected function arguments();
Chris@0 87
Chris@0 88 /**
Chris@0 89 * Checks if required arguments are passed in and adds defaults for non passed
Chris@0 90 * in optional arguments.
Chris@0 91 *
Chris@0 92 * Image toolkit operation implementers should not normally need to override
Chris@0 93 * this method as they should place their own validation in validateArguments.
Chris@0 94 *
Chris@0 95 * @param array $arguments
Chris@0 96 * An associative array of arguments to be used by the toolkit operation.
Chris@0 97 *
Chris@0 98 * @return array
Chris@0 99 * The prepared arguments array.
Chris@0 100 *
Chris@0 101 * @throws \InvalidArgumentException.
Chris@0 102 * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException.
Chris@0 103 */
Chris@0 104 protected function prepareArguments(array $arguments) {
Chris@0 105 foreach ($this->arguments() as $id => $argument) {
Chris@0 106 $argument += ['required' => TRUE];
Chris@0 107 // Check if the argument is required and, if so, has been provided.
Chris@0 108 if ($argument['required']) {
Chris@0 109 if (!array_key_exists($id, $arguments)) {
Chris@0 110 // If the argument is required throw an exception.
Chris@0 111 throw new \InvalidArgumentException("Argument '$id' expected by plugin '{$this->getPluginId()}' but not passed");
Chris@0 112 }
Chris@0 113 }
Chris@0 114 else {
Chris@0 115 // Optional arguments require a 'default' value.
Chris@0 116 // We check this even if the argument is provided by the caller, as we
Chris@0 117 // want to fail fast here, i.e. at development time.
Chris@0 118 if (!array_key_exists('default', $argument)) {
Chris@0 119 // The plugin did not define a default, so throw a plugin exception,
Chris@0 120 // not an invalid argument exception.
Chris@0 121 throw new InvalidPluginDefinitionException("Default for argument '$id' expected by plugin '{$this->getPluginId()}' but not defined");
Chris@0 122 }
Chris@0 123
Chris@0 124 // Use the default value if the argument is not passed in.
Chris@0 125 if (!array_key_exists($id, $arguments)) {
Chris@0 126 $arguments[$id] = $argument['default'];
Chris@0 127 }
Chris@0 128 }
Chris@0 129 }
Chris@0 130 return $arguments;
Chris@0 131 }
Chris@0 132
Chris@0 133 /**
Chris@0 134 * Validates the arguments.
Chris@0 135 *
Chris@0 136 * Image toolkit operation implementers should place any argument validation
Chris@0 137 * in this method, throwing an InvalidArgumentException when an error is
Chris@0 138 * encountered.
Chris@0 139 *
Chris@0 140 * Validation typically includes things like:
Chris@0 141 * - Checking that width and height are not negative.
Chris@0 142 * - Checking that a color value is indeed a color.
Chris@0 143 *
Chris@0 144 * But validation may also include correcting the arguments, e.g:
Chris@0 145 * - Casting arguments to the correct type.
Chris@0 146 * - Rounding pixel values to an integer.
Chris@0 147 *
Chris@0 148 * This base implementation just returns the array of arguments and thus does
Chris@0 149 * not need to be called by overriding methods.
Chris@0 150 *
Chris@0 151 * @param array $arguments
Chris@0 152 * An associative array of arguments to be used by the toolkit operation.
Chris@0 153 *
Chris@0 154 * @return array
Chris@0 155 * The validated and corrected arguments array.
Chris@0 156 *
Chris@0 157 * @throws \InvalidArgumentException
Chris@0 158 * If one or more of the arguments are not valid.
Chris@0 159 * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
Chris@0 160 * If the plugin does not define a default for an optional argument.
Chris@0 161 */
Chris@0 162 protected function validateArguments(array $arguments) {
Chris@0 163 return $arguments;
Chris@0 164 }
Chris@0 165
Chris@0 166 /**
Chris@0 167 * {@inheritdoc}
Chris@0 168 */
Chris@0 169 final public function apply(array $arguments) {
Chris@0 170 $arguments = $this->prepareArguments($arguments);
Chris@0 171 $arguments = $this->validateArguments($arguments);
Chris@0 172 return $this->execute($arguments);
Chris@0 173 }
Chris@0 174
Chris@0 175 /**
Chris@0 176 * Performs the actual manipulation on the image.
Chris@0 177 *
Chris@0 178 * Image toolkit operation implementers must implement this method. This
Chris@0 179 * method is responsible for actually performing the operation on the image.
Chris@0 180 * When this method gets called, the implementer may assume all arguments,
Chris@0 181 * also the optional ones, to be available, validated and corrected.
Chris@0 182 *
Chris@0 183 * @param array $arguments
Chris@0 184 * An associative array of arguments to be used by the toolkit operation.
Chris@0 185 *
Chris@0 186 * @return bool
Chris@0 187 * TRUE if the operation was performed successfully, FALSE otherwise.
Chris@0 188 */
Chris@0 189 abstract protected function execute(array $arguments);
Chris@0 190
Chris@0 191 }