Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\image;
Chris@0: 
Chris@0: use Drupal\Core\Config\Entity\ConfigEntityInterface;
Chris@0: 
Chris@0: /**
Chris@0:  * Provides an interface defining an image style entity.
Chris@0:  */
Chris@0: interface ImageStyleInterface extends ConfigEntityInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the replacement ID.
Chris@0:    *
Chris@0:    * @return string|null
Chris@0:    *   The replacement image style ID or NULL if no replacement has been
Chris@0:    *   selected.
Chris@0:    *
Chris@0:    * @deprecated in Drupal 8.0.x, will be removed before Drupal 9.0.x. Use
Chris@0:    *   \Drupal\image\ImageStyleStorageInterface::getReplacementId() instead.
Chris@0:    *
Chris@0:    * @see \Drupal\image\ImageStyleStorageInterface::getReplacementId()
Chris@0:    */
Chris@0:   public function getReplacementID();
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the image style.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The name of the image style.
Chris@0:    */
Chris@0:   public function getName();
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets the name of the image style.
Chris@0:    *
Chris@0:    * @param string $name
Chris@0:    *   The name of the image style.
Chris@0:    *
Chris@0:    * @return \Drupal\image\ImageStyleInterface
Chris@0:    *   The class instance this method is called on.
Chris@0:    */
Chris@0:   public function setName($name);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the URI of this image when using this style.
Chris@0:    *
Chris@0:    * The path returned by this function may not exist. The default generation
Chris@0:    * method only creates images when they are requested by a user's browser.
Chris@0:    * Modules may implement this method to decide where to place derivatives.
Chris@0:    *
Chris@0:    * @param string $uri
Chris@0:    *   The URI or path to the original image.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The URI to the image derivative for this style.
Chris@0:    */
Chris@0:   public function buildUri($uri);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the URL of this image derivative for an original image path or URI.
Chris@0:    *
Chris@0:    * @param string $path
Chris@0:    *   The path or URI to the original image.
Chris@0:    * @param mixed $clean_urls
Chris@0:    *   (optional) Whether clean URLs are in use.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The absolute URL where a style image can be downloaded, suitable for use
Chris@0:    *   in an <img> tag. Requesting the URL will cause the image to be created.
Chris@0:    *
Chris@0:    * @see \Drupal\image\Controller\ImageStyleDownloadController::deliver()
Chris@0:    * @see file_url_transform_relative()
Chris@0:    */
Chris@0:   public function buildUrl($path, $clean_urls = NULL);
Chris@0: 
Chris@0:   /**
Chris@0:    * Generates a token to protect an image style derivative.
Chris@0:    *
Chris@0:    * This prevents unauthorized generation of an image style derivative,
Chris@0:    * which can be costly both in CPU time and disk space.
Chris@0:    *
Chris@0:    * @param string $uri
Chris@0:    *   The URI of the original image of this style.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   An eight-character token which can be used to protect image style
Chris@0:    *   derivatives against denial-of-service attacks.
Chris@0:    */
Chris@0:   public function getPathToken($uri);
Chris@0: 
Chris@0:   /**
Chris@0:    * Flushes cached media for this style.
Chris@0:    *
Chris@0:    * @param string $path
Chris@0:    *   (optional) The original image path or URI. If it's supplied, only this
Chris@0:    *   image derivative will be flushed.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function flush($path = NULL);
Chris@0: 
Chris@0:   /**
Chris@0:    * Creates a new image derivative based on this image style.
Chris@0:    *
Chris@0:    * Generates an image derivative applying all image effects and saving the
Chris@0:    * resulting image.
Chris@0:    *
Chris@0:    * @param string $original_uri
Chris@0:    *   Original image file URI.
Chris@0:    * @param string $derivative_uri
Chris@0:    *   Derivative image file URI.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if an image derivative was generated, or FALSE if the image
Chris@0:    *   derivative could not be generated.
Chris@0:    */
Chris@0:   public function createDerivative($original_uri, $derivative_uri);
Chris@0: 
Chris@0:   /**
Chris@0:    * Determines the dimensions of this image style.
Chris@0:    *
Chris@0:    * Stores the dimensions of this image style into $dimensions associative
Chris@0:    * array. Implementations have to provide at least values to next keys:
Chris@0:    * - width: Integer with the derivative image width.
Chris@0:    * - height: Integer with the derivative image height.
Chris@0:    *
Chris@0:    * @param array $dimensions
Chris@0:    *   Associative array passed by reference. Implementations have to store the
Chris@0:    *   resulting width and height, in pixels.
Chris@0:    * @param string $uri
Chris@0:    *   Original image file URI. It is passed in to allow effects to
Chris@0:    *   optionally use this information to retrieve additional image metadata
Chris@0:    *   to determine dimensions of the styled image.
Chris@0:    *   ImageStyleInterface::transformDimensions key objective is to calculate
Chris@0:    *   styled image dimensions without performing actual image operations, so
Chris@0:    *   be aware that performing IO on the URI may lead to decrease in
Chris@0:    *   performance.
Chris@0:    *
Chris@0:    * @see ImageEffectInterface::transformDimensions
Chris@0:    */
Chris@0:   public function transformDimensions(array &$dimensions, $uri);
Chris@0: 
Chris@0:   /**
Chris@0:    * Determines the extension of the derivative without generating it.
Chris@0:    *
Chris@0:    * @param string $extension
Chris@0:    *   The file extension of the original image.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The extension the derivative image will have, given the extension of the
Chris@0:    *   original.
Chris@0:    */
Chris@0:   public function getDerivativeExtension($extension);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns a specific image effect.
Chris@0:    *
Chris@0:    * @param string $effect
Chris@0:    *   The image effect ID.
Chris@0:    *
Chris@0:    * @return \Drupal\image\ImageEffectInterface
Chris@0:    *   The image effect object.
Chris@0:    */
Chris@0:   public function getEffect($effect);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the image effects for this style.
Chris@0:    *
Chris@0:    * @return \Drupal\image\ImageEffectPluginCollection|\Drupal\image\ImageEffectInterface[]
Chris@0:    *   The image effect plugin collection.
Chris@0:    */
Chris@0:   public function getEffects();
Chris@0: 
Chris@0:   /**
Chris@0:    * Saves an image effect for this style.
Chris@0:    *
Chris@0:    * @param array $configuration
Chris@0:    *   An array of image effect configuration.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The image effect ID.
Chris@0:    */
Chris@0:   public function addImageEffect(array $configuration);
Chris@0: 
Chris@0:   /**
Chris@0:    * Deletes an image effect from this style.
Chris@0:    *
Chris@0:    * @param \Drupal\image\ImageEffectInterface $effect
Chris@0:    *   The image effect object.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function deleteImageEffect(ImageEffectInterface $effect);
Chris@0: 
Chris@0:   /**
Chris@0:    * Determines if this style can be applied to a given image.
Chris@0:    *
Chris@0:    * @param string $uri
Chris@0:    *   The URI of the image.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the image is supported, FALSE otherwise.
Chris@0:    */
Chris@0:   public function supportsUri($uri);
Chris@0: 
Chris@0: }