3 namespace Drupal\image;
5 use Drupal\Core\Config\Entity\ConfigEntityInterface;
8 * Provides an interface defining an image style entity.
10 interface ImageStyleInterface extends ConfigEntityInterface {
13 * Returns the replacement ID.
16 * The replacement image style ID or NULL if no replacement has been
19 * @deprecated in Drupal 8.0.x, will be removed before Drupal 9.0.x. Use
20 * \Drupal\image\ImageStyleStorageInterface::getReplacementId() instead.
22 * @see \Drupal\image\ImageStyleStorageInterface::getReplacementId()
24 public function getReplacementID();
27 * Returns the image style.
30 * The name of the image style.
32 public function getName();
35 * Sets the name of the image style.
38 * The name of the image style.
40 * @return \Drupal\image\ImageStyleInterface
41 * The class instance this method is called on.
43 public function setName($name);
47 * Returns the URI of this image when using this style.
49 * The path returned by this function may not exist. The default generation
50 * method only creates images when they are requested by a user's browser.
51 * Modules may implement this method to decide where to place derivatives.
54 * The URI or path to the original image.
57 * The URI to the image derivative for this style.
59 public function buildUri($uri);
62 * Returns the URL of this image derivative for an original image path or URI.
65 * The path or URI to the original image.
66 * @param mixed $clean_urls
67 * (optional) Whether clean URLs are in use.
70 * The absolute URL where a style image can be downloaded, suitable for use
71 * in an <img> tag. Requesting the URL will cause the image to be created.
73 * @see \Drupal\image\Controller\ImageStyleDownloadController::deliver()
74 * @see file_url_transform_relative()
76 public function buildUrl($path, $clean_urls = NULL);
79 * Generates a token to protect an image style derivative.
81 * This prevents unauthorized generation of an image style derivative,
82 * which can be costly both in CPU time and disk space.
85 * The URI of the original image of this style.
88 * An eight-character token which can be used to protect image style
89 * derivatives against denial-of-service attacks.
91 public function getPathToken($uri);
94 * Flushes cached media for this style.
97 * (optional) The original image path or URI. If it's supplied, only this
98 * image derivative will be flushed.
102 public function flush($path = NULL);
105 * Creates a new image derivative based on this image style.
107 * Generates an image derivative applying all image effects and saving the
110 * @param string $original_uri
111 * Original image file URI.
112 * @param string $derivative_uri
113 * Derivative image file URI.
116 * TRUE if an image derivative was generated, or FALSE if the image
117 * derivative could not be generated.
119 public function createDerivative($original_uri, $derivative_uri);
122 * Determines the dimensions of this image style.
124 * Stores the dimensions of this image style into $dimensions associative
125 * array. Implementations have to provide at least values to next keys:
126 * - width: Integer with the derivative image width.
127 * - height: Integer with the derivative image height.
129 * @param array $dimensions
130 * Associative array passed by reference. Implementations have to store the
131 * resulting width and height, in pixels.
133 * Original image file URI. It is passed in to allow effects to
134 * optionally use this information to retrieve additional image metadata
135 * to determine dimensions of the styled image.
136 * ImageStyleInterface::transformDimensions key objective is to calculate
137 * styled image dimensions without performing actual image operations, so
138 * be aware that performing IO on the URI may lead to decrease in
141 * @see ImageEffectInterface::transformDimensions
143 public function transformDimensions(array &$dimensions, $uri);
146 * Determines the extension of the derivative without generating it.
148 * @param string $extension
149 * The file extension of the original image.
152 * The extension the derivative image will have, given the extension of the
155 public function getDerivativeExtension($extension);
158 * Returns a specific image effect.
160 * @param string $effect
161 * The image effect ID.
163 * @return \Drupal\image\ImageEffectInterface
164 * The image effect object.
166 public function getEffect($effect);
169 * Returns the image effects for this style.
171 * @return \Drupal\image\ImageEffectPluginCollection|\Drupal\image\ImageEffectInterface[]
172 * The image effect plugin collection.
174 public function getEffects();
177 * Saves an image effect for this style.
179 * @param array $configuration
180 * An array of image effect configuration.
183 * The image effect ID.
185 public function addImageEffect(array $configuration);
188 * Deletes an image effect from this style.
190 * @param \Drupal\image\ImageEffectInterface $effect
191 * The image effect object.
195 public function deleteImageEffect(ImageEffectInterface $effect);