image.module

Same filename and directory in other branches
  1. 7.x modules/image/image.module
  2. 9 core/modules/image/image.module
  3. 8.9.x core/modules/image/image.module
  4. 10 core/modules/image/image.module

File

core/modules/image/image.module

View source
<?php


/**
 * @file
 */

use Drupal\image\Entity\ImageStyle;

/**
 * The name of the query parameter for image derivative tokens.
 */
define('IMAGE_DERIVATIVE_TOKEN', 'itok');

/**
 * Clears cached versions of a specific file in all styles.
 *
 * @param string $path
 *   The Drupal file path to the original image.
 */
function image_path_flush($path) : void {
  $styles = ImageStyle::loadMultiple();
  foreach ($styles as $style) {
    $style->flush($path);
  }
}

/**
 * Gets an array of image styles suitable for using as select list options.
 *
 * @param bool $include_empty
 *   If TRUE a '- None -' option will be inserted in the options array.
 *
 * @return string[]
 *   Array of image styles both key and value are set to style name.
 */
function image_style_options($include_empty = TRUE) : array {
  $styles = ImageStyle::loadMultiple();
  $options = [];
  if ($include_empty && !empty($styles)) {
    $options[''] = t('- None -');
  }
  foreach ($styles as $name => $style) {
    $options[$name] = $style->label();
  }
  if (empty($options)) {
    $options[''] = t('No defined styles');
  }
  return $options;
}

/**
 * Prepares variables for image style templates.
 *
 * Default template: image-style.html.twig.
 *
 * @param array $variables
 *   An associative array containing:
 *   - width: The width of the image.
 *   - height: The height of the image.
 *   - style_name: The name of the image style to be applied.
 *   - uri: URI of the source image before styling.
 *   - alt: The alternative text for text-based browsers. HTML 4 and XHTML 1.0
 *     always require an alt attribute. The HTML 5 draft allows the alt
 *     attribute to be omitted in some cases. Therefore, this variable defaults
 *     to an empty string, but can be set to NULL for the attribute to be
 *     omitted. Usually, neither omission nor an empty string satisfies
 *     accessibility requirements, so it is strongly encouraged for code using
 *     '#theme' => 'image_style' to pass a meaningful value for this variable.
 *     - https://www.w3.org/TR/REC-html40/struct/objects.html#h-13.8
 *     - https://www.w3.org/TR/xhtml1/dtds.html
 *     - http://dev.w3.org/html5/spec/Overview.html#alt
 *   - title: The title text is displayed when the image is hovered in some
 *     popular browsers.
 *   - attributes: Associative array of additional attributes to be placed in
 *     the img tag.
 */
function template_preprocess_image_style(&$variables) : void {
  $style = ImageStyle::load($variables['style_name']);
  // Determine the dimensions of the styled image.
  $dimensions = [
    'width' => $variables['width'],
    'height' => $variables['height'],
  ];
  $style->transformDimensions($dimensions, $variables['uri']);
  $variables['image'] = [
    '#theme' => 'image',
    '#width' => $dimensions['width'],
    '#height' => $dimensions['height'],
    '#attributes' => $variables['attributes'],
    '#style_name' => $variables['style_name'],
  ];
  // If the current image toolkit supports this file type, prepare the URI for
  // the derivative image. If not, just use the original image resized to the
  // dimensions specified by the style.
  if ($style->supportsUri($variables['uri'])) {
    $variables['image']['#uri'] = $style->buildUrl($variables['uri']);
  }
  else {
    $variables['image']['#uri'] = $variables['uri'];
    // Don't render the image by default, but allow other preprocess functions
    // to override that if they need to.
    $variables['image']['#access'] = FALSE;
    // Inform the site builders why their image didn't work.
    \Drupal::logger('image')->warning('Could not apply @style image style to @uri because the style does not support it.', [
      '@style' => $style->label(),
      '@uri' => $variables['uri'],
    ]);
  }
  if (\array_key_exists('alt', $variables)) {
    $variables['image']['#alt'] = $variables['alt'];
  }
  if (\array_key_exists('title', $variables)) {
    $variables['image']['#title'] = $variables['title'];
  }
}

/**
 * Returns the offset in pixels from the anchor.
 *
 * @param string $anchor
 *   The anchor ('top', 'left', 'bottom', 'right', 'center').
 * @param int $current_size
 *   The current size, in pixels.
 * @param int $new_size
 *   The new size, in pixels.
 *
 * @return int|string
 *   The offset from the anchor, in pixels, or the anchor itself, if its value
 *   isn't one of the accepted values.
 *
 * @deprecated in drupal:11.1.0 and is removed from drupal:12.0.0. Use
 *   \Drupal\Component\Utility\Image::getKeywordOffset() instead.
 *
 * @see https://www.drupal.org/node/3268441
 */
function image_filter_keyword($anchor, $current_size, $new_size) {
  @trigger_error('image_filter_keyword() is deprecated in drupal:11.1.0 and is removed from drupal:12.0.0. Use \\Drupal\\Component\\Utility\\Image::getKeywordOffset() instead. See https://www.drupal.org/node/3268441', E_USER_DEPRECATED);
  switch ($anchor) {
    case 'top':
    case 'left':
      return 0;
    case 'bottom':
    case 'right':
      return $current_size - $new_size;
    case 'center':
      return $current_size / 2 - $new_size / 2;
    default:
      return $anchor;
  }
}

Functions

Title Deprecated Summary
image_filter_keyword

in drupal:11.1.0 and is removed from drupal:12.0.0. Use \Drupal\Component\Utility\Image::getKeywordOffset() instead.

Returns the offset in pixels from the anchor.
image_path_flush Clears cached versions of a specific file in all styles.
image_style_options Gets an array of image styles suitable for using as select list options.
template_preprocess_image_style Prepares variables for image style templates.

Constants

Title Deprecated Summary
IMAGE_DERIVATIVE_TOKEN The name of the query parameter for image derivative tokens.

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.