Chris@0
|
1 <?php
|
Chris@0
|
2
|
Chris@0
|
3 namespace Drupal\image;
|
Chris@0
|
4
|
Chris@0
|
5 use Drupal\Core\Config\Entity\ConfigEntityInterface;
|
Chris@0
|
6
|
Chris@0
|
7 /**
|
Chris@0
|
8 * Provides an interface defining an image style entity.
|
Chris@0
|
9 */
|
Chris@0
|
10 interface ImageStyleInterface extends ConfigEntityInterface {
|
Chris@0
|
11
|
Chris@0
|
12 /**
|
Chris@0
|
13 * Returns the replacement ID.
|
Chris@0
|
14 *
|
Chris@0
|
15 * @return string|null
|
Chris@0
|
16 * The replacement image style ID or NULL if no replacement has been
|
Chris@0
|
17 * selected.
|
Chris@0
|
18 *
|
Chris@0
|
19 * @deprecated in Drupal 8.0.x, will be removed before Drupal 9.0.x. Use
|
Chris@0
|
20 * \Drupal\image\ImageStyleStorageInterface::getReplacementId() instead.
|
Chris@0
|
21 *
|
Chris@0
|
22 * @see \Drupal\image\ImageStyleStorageInterface::getReplacementId()
|
Chris@0
|
23 */
|
Chris@0
|
24 public function getReplacementID();
|
Chris@0
|
25
|
Chris@0
|
26 /**
|
Chris@0
|
27 * Returns the image style.
|
Chris@0
|
28 *
|
Chris@0
|
29 * @return string
|
Chris@0
|
30 * The name of the image style.
|
Chris@0
|
31 */
|
Chris@0
|
32 public function getName();
|
Chris@0
|
33
|
Chris@0
|
34 /**
|
Chris@0
|
35 * Sets the name of the image style.
|
Chris@0
|
36 *
|
Chris@0
|
37 * @param string $name
|
Chris@0
|
38 * The name of the image style.
|
Chris@0
|
39 *
|
Chris@0
|
40 * @return \Drupal\image\ImageStyleInterface
|
Chris@0
|
41 * The class instance this method is called on.
|
Chris@0
|
42 */
|
Chris@0
|
43 public function setName($name);
|
Chris@0
|
44
|
Chris@0
|
45 /**
|
Chris@0
|
46 * Returns the URI of this image when using this style.
|
Chris@0
|
47 *
|
Chris@0
|
48 * The path returned by this function may not exist. The default generation
|
Chris@0
|
49 * method only creates images when they are requested by a user's browser.
|
Chris@0
|
50 * Modules may implement this method to decide where to place derivatives.
|
Chris@0
|
51 *
|
Chris@0
|
52 * @param string $uri
|
Chris@0
|
53 * The URI or path to the original image.
|
Chris@0
|
54 *
|
Chris@0
|
55 * @return string
|
Chris@0
|
56 * The URI to the image derivative for this style.
|
Chris@0
|
57 */
|
Chris@0
|
58 public function buildUri($uri);
|
Chris@0
|
59
|
Chris@0
|
60 /**
|
Chris@0
|
61 * Returns the URL of this image derivative for an original image path or URI.
|
Chris@0
|
62 *
|
Chris@0
|
63 * @param string $path
|
Chris@0
|
64 * The path or URI to the original image.
|
Chris@0
|
65 * @param mixed $clean_urls
|
Chris@0
|
66 * (optional) Whether clean URLs are in use.
|
Chris@0
|
67 *
|
Chris@0
|
68 * @return string
|
Chris@0
|
69 * The absolute URL where a style image can be downloaded, suitable for use
|
Chris@0
|
70 * in an <img> tag. Requesting the URL will cause the image to be created.
|
Chris@0
|
71 *
|
Chris@0
|
72 * @see \Drupal\image\Controller\ImageStyleDownloadController::deliver()
|
Chris@0
|
73 * @see file_url_transform_relative()
|
Chris@0
|
74 */
|
Chris@0
|
75 public function buildUrl($path, $clean_urls = NULL);
|
Chris@0
|
76
|
Chris@0
|
77 /**
|
Chris@0
|
78 * Generates a token to protect an image style derivative.
|
Chris@0
|
79 *
|
Chris@0
|
80 * This prevents unauthorized generation of an image style derivative,
|
Chris@0
|
81 * which can be costly both in CPU time and disk space.
|
Chris@0
|
82 *
|
Chris@0
|
83 * @param string $uri
|
Chris@0
|
84 * The URI of the original image of this style.
|
Chris@0
|
85 *
|
Chris@0
|
86 * @return string
|
Chris@0
|
87 * An eight-character token which can be used to protect image style
|
Chris@0
|
88 * derivatives against denial-of-service attacks.
|
Chris@0
|
89 */
|
Chris@0
|
90 public function getPathToken($uri);
|
Chris@0
|
91
|
Chris@0
|
92 /**
|
Chris@0
|
93 * Flushes cached media for this style.
|
Chris@0
|
94 *
|
Chris@0
|
95 * @param string $path
|
Chris@0
|
96 * (optional) The original image path or URI. If it's supplied, only this
|
Chris@0
|
97 * image derivative will be flushed.
|
Chris@0
|
98 *
|
Chris@0
|
99 * @return $this
|
Chris@0
|
100 */
|
Chris@0
|
101 public function flush($path = NULL);
|
Chris@0
|
102
|
Chris@0
|
103 /**
|
Chris@0
|
104 * Creates a new image derivative based on this image style.
|
Chris@0
|
105 *
|
Chris@0
|
106 * Generates an image derivative applying all image effects and saving the
|
Chris@0
|
107 * resulting image.
|
Chris@0
|
108 *
|
Chris@0
|
109 * @param string $original_uri
|
Chris@0
|
110 * Original image file URI.
|
Chris@0
|
111 * @param string $derivative_uri
|
Chris@0
|
112 * Derivative image file URI.
|
Chris@0
|
113 *
|
Chris@0
|
114 * @return bool
|
Chris@0
|
115 * TRUE if an image derivative was generated, or FALSE if the image
|
Chris@0
|
116 * derivative could not be generated.
|
Chris@0
|
117 */
|
Chris@0
|
118 public function createDerivative($original_uri, $derivative_uri);
|
Chris@0
|
119
|
Chris@0
|
120 /**
|
Chris@0
|
121 * Determines the dimensions of this image style.
|
Chris@0
|
122 *
|
Chris@0
|
123 * Stores the dimensions of this image style into $dimensions associative
|
Chris@0
|
124 * array. Implementations have to provide at least values to next keys:
|
Chris@0
|
125 * - width: Integer with the derivative image width.
|
Chris@0
|
126 * - height: Integer with the derivative image height.
|
Chris@0
|
127 *
|
Chris@0
|
128 * @param array $dimensions
|
Chris@0
|
129 * Associative array passed by reference. Implementations have to store the
|
Chris@0
|
130 * resulting width and height, in pixels.
|
Chris@0
|
131 * @param string $uri
|
Chris@0
|
132 * Original image file URI. It is passed in to allow effects to
|
Chris@0
|
133 * optionally use this information to retrieve additional image metadata
|
Chris@0
|
134 * to determine dimensions of the styled image.
|
Chris@0
|
135 * ImageStyleInterface::transformDimensions key objective is to calculate
|
Chris@0
|
136 * styled image dimensions without performing actual image operations, so
|
Chris@0
|
137 * be aware that performing IO on the URI may lead to decrease in
|
Chris@0
|
138 * performance.
|
Chris@0
|
139 *
|
Chris@0
|
140 * @see ImageEffectInterface::transformDimensions
|
Chris@0
|
141 */
|
Chris@0
|
142 public function transformDimensions(array &$dimensions, $uri);
|
Chris@0
|
143
|
Chris@0
|
144 /**
|
Chris@0
|
145 * Determines the extension of the derivative without generating it.
|
Chris@0
|
146 *
|
Chris@0
|
147 * @param string $extension
|
Chris@0
|
148 * The file extension of the original image.
|
Chris@0
|
149 *
|
Chris@0
|
150 * @return string
|
Chris@0
|
151 * The extension the derivative image will have, given the extension of the
|
Chris@0
|
152 * original.
|
Chris@0
|
153 */
|
Chris@0
|
154 public function getDerivativeExtension($extension);
|
Chris@0
|
155
|
Chris@0
|
156 /**
|
Chris@0
|
157 * Returns a specific image effect.
|
Chris@0
|
158 *
|
Chris@0
|
159 * @param string $effect
|
Chris@0
|
160 * The image effect ID.
|
Chris@0
|
161 *
|
Chris@0
|
162 * @return \Drupal\image\ImageEffectInterface
|
Chris@0
|
163 * The image effect object.
|
Chris@0
|
164 */
|
Chris@0
|
165 public function getEffect($effect);
|
Chris@0
|
166
|
Chris@0
|
167 /**
|
Chris@0
|
168 * Returns the image effects for this style.
|
Chris@0
|
169 *
|
Chris@0
|
170 * @return \Drupal\image\ImageEffectPluginCollection|\Drupal\image\ImageEffectInterface[]
|
Chris@0
|
171 * The image effect plugin collection.
|
Chris@0
|
172 */
|
Chris@0
|
173 public function getEffects();
|
Chris@0
|
174
|
Chris@0
|
175 /**
|
Chris@0
|
176 * Saves an image effect for this style.
|
Chris@0
|
177 *
|
Chris@0
|
178 * @param array $configuration
|
Chris@0
|
179 * An array of image effect configuration.
|
Chris@0
|
180 *
|
Chris@0
|
181 * @return string
|
Chris@0
|
182 * The image effect ID.
|
Chris@0
|
183 */
|
Chris@0
|
184 public function addImageEffect(array $configuration);
|
Chris@0
|
185
|
Chris@0
|
186 /**
|
Chris@0
|
187 * Deletes an image effect from this style.
|
Chris@0
|
188 *
|
Chris@0
|
189 * @param \Drupal\image\ImageEffectInterface $effect
|
Chris@0
|
190 * The image effect object.
|
Chris@0
|
191 *
|
Chris@0
|
192 * @return $this
|
Chris@0
|
193 */
|
Chris@0
|
194 public function deleteImageEffect(ImageEffectInterface $effect);
|
Chris@0
|
195
|
Chris@0
|
196 /**
|
Chris@0
|
197 * Determines if this style can be applied to a given image.
|
Chris@0
|
198 *
|
Chris@0
|
199 * @param string $uri
|
Chris@0
|
200 * The URI of the image.
|
Chris@0
|
201 *
|
Chris@0
|
202 * @return bool
|
Chris@0
|
203 * TRUE if the image is supported, FALSE otherwise.
|
Chris@0
|
204 */
|
Chris@0
|
205 public function supportsUri($uri);
|
Chris@0
|
206
|
Chris@0
|
207 }
|