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 }
|