image.module

<?php

/**
 * @file
 * Exposes global functionality for creating image styles.
 */

use Drupal\Core\Entity\EntityInterface;
use Drupal\Core\Routing\RouteMatchInterface;
use Drupal\file\Entity\File;
use Drupal\field\FieldStorageConfigInterface;
use Drupal\field\FieldConfigInterface;

/**
 * Image style constant for user presets in the database.
 */
const IMAGE_STORAGE_NORMAL = 1;

/**
 * Image style constant for user presets that override module-defined presets.
 */
const IMAGE_STORAGE_OVERRIDE = 2;

/**
 * Image style constant for module-defined presets in code.
 */
const IMAGE_STORAGE_DEFAULT = 4;

/**
 * Image style constant to represent an editable preset.
 */
define('IMAGE_STORAGE_EDITABLE', IMAGE_STORAGE_NORMAL | IMAGE_STORAGE_OVERRIDE);

/**
 * Image style constant to represent any module-based preset.
 */
define('IMAGE_STORAGE_MODULE', IMAGE_STORAGE_OVERRIDE | IMAGE_STORAGE_DEFAULT);

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

// Load all Field module hooks for Image.
require_once __DIR__ . '/image.field.inc';

/**
 * Implements hook_help().
 */
function image_help($route_name, RouteMatchInterface $route_match) {
  switch ($route_name) {
    case 'help.page.image':
      $output = '';
      $output .= '<h3>' . t('About') . '</h3>';
      $output .= '<p>' . t('The Image module allows you to manipulate images on your website. It exposes a setting for using the <em>Image toolkit</em>, allows you to configure <em>Image styles</em> that can be used for resizing or adjusting images on display, and provides an <em>Image</em> field for attaching images to content. For more information, see the online handbook entry for <a href="@image">Image module</a>.', array('@image' => 'http://drupal.org/documentation/modules/image')) . '</p>';
      $output .= '<h3>' . t('Uses') . '</h3>';
      $output .= '<dl>';
      $output .= '<dt>' . t('Manipulating images') . '</dt>';
      $output .= '<dd>' . t('With the Image module you can scale, crop, resize, rotate and desaturate images without affecting the original image using <a href="@image">image styles</a>. When you change an image style, the module automatically refreshes all created images. Every image style must have a name, which will be used in the URL of the generated images. There are two common approaches to naming image styles (which you use will depend on how the image style is being applied):',array('@image' => \Drupal::url('image.style_list')));
      $output .= '<ul><li>' . t('Based on where it will be used: eg. <em>profile-picture</em>') . '</li>';
      $output .= '<li>' . t('Describing its appearance: eg. <em>square-85x85</em>') . '</li></ul>';
      $output .=  t('After you create an image style, you can add effects: crop, scale, resize, rotate, and desaturate (other contributed modules provide additional effects). For example, by combining effects as crop, scale, and desaturate, you can create square, grayscale thumbnails.') . '<dd>';
      $output .= '<dt>' . t('Attaching images to content as fields') . '</dt>';
      $output .= '<dd>' . t("Image module also allows you to attach images to content as fields. To add an image field to a <a href='@content-type'>content type</a>, go to the content type's <em>manage fields</em> page, and add a new field of type <em>Image</em>. Attaching images to content this way allows image styles to be applied and maintained, and also allows you more flexibility when theming.", array('@content-type' => \Drupal::url('node.overview_types'))) . '</dd>';
      $output .= '<dt>' . t('Configuring image fields for accessibility') . '</dt>';
      $output .= '<dd>' . t('For accessibility and search engine optimization, all images that convey meaning on web sites should have alternate text. Drupal also allows entry of title text for images, but it can lead to confusion for screen reader users and its use is not recommended. Image fields can be configured so that alternate and title text fields are enabled or disabled; if enabled, the fields can be set to be required. The recommended setting is to enable and require alternate text and disable title text.') . '</dd>';
      $output .= '</dl>';
      return $output;

    case 'image.style_list':
      return '<p>' . t('Image styles commonly provide thumbnail sizes by scaling and cropping images, but can also add various effects before an image is displayed. When an image is displayed with a style, a new file is created and the original image is left unchanged.') . '</p>';

    case 'image.effect_add_form':
      $effect = \Drupal::service('plugin.manager.image.effect')->getDefinition($route_match->getParameter('image_effect'));
      return isset($effect['description']) ? ('<p>' . $effect['description'] . '</p>') : NULL;

    case 'image.effect_edit_form':
      $effect = $route_match->getParameter('image_style')->getEffect($route_match->getParameter('image_effect'));
      $effect_definition = $effect->getPluginDefinition();
      return isset($effect_definition['description']) ? ('<p>' . $effect_definition['description'] . '</p>') : NULL;
  }
}

/**
 * Implements hook_theme().
 */
function image_theme() {
  return array(
    // Theme functions in image.module.
    'image_style' => array(
      // 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,
      // default the alt attribute to an empty string, but allow code calling
      // _theme('image_style') to pass explicit NULL for it to be omitted.
      // Usually, neither omission nor an empty string satisfies accessibility
      // requirements, so it is strongly encouraged for code calling
      // _theme('image_style') to pass a meaningful value for the alt variable.
      // - http://www.w3.org/TR/REC-html40/struct/objects.html#h-13.8
      // - http://www.w3.org/TR/xhtml1/dtds.html
      // - http://dev.w3.org/html5/spec/Overview.html#alt
      // The title attribute is optional in all cases, so it is omitted by
      // default.
      'variables' => array(
        'style_name' => NULL,
        'uri' => NULL,
        'width' => NULL,
        'height' => NULL,
        'alt' => '',
        'title' => NULL,
        'attributes' => array(),
      ),
    ),

    // Theme functions in image.admin.inc.
    'image_style_preview' => array(
      'variables' => array('style' => NULL),
      'file' => 'image.admin.inc',
    ),
    'image_anchor' => array(
      'render element' => 'element',
      'file' => 'image.admin.inc',
    ),
    'image_resize_summary' => array(
      'variables' => array('data' => NULL, 'effect' => array()),
    ),
    'image_scale_summary' => array(
      'variables' => array('data' => NULL, 'effect' => array()),
    ),
    'image_crop_summary' => array(
      'variables' => array('data' => NULL, 'effect' => array()),
    ),
    'image_rotate_summary' => array(
      'variables' => array('data' => NULL, 'effect' => array()),
    ),

    // Theme functions in image.field.inc.
    'image_widget' => array(
      'render element' => 'element',
      'file' => 'image.field.inc',
    ),
    'image_formatter' => array(
      'variables' => array('item' => NULL, 'item_attributes' => NULL, 'path' => NULL, 'image_style' => NULL),
      'file' => 'image.field.inc',
    ),
  );
}

/**
 * Implements hook_file_download().
 *
 * Control the access to files underneath the styles directory.
 */
function image_file_download($uri) {
  $path = file_uri_target($uri);

  // Private file access for image style derivatives.
  if (strpos($path, 'styles/') === 0) {
    $args = explode('/', $path);

    // Discard "styles", style name, and scheme from the path
    $args = array_slice($args, 3);

    // Then the remaining parts are the path to the image.
    $original_uri = file_uri_scheme($uri) . '://' . implode('/', $args);

    // Check that the file exists and is an image.
    $image = \Drupal::service('image.factory')->get($uri);
    if ($image->isValid()) {
      // Check the permissions of the original to grant access to this image.
      $headers = \Drupal::moduleHandler()->invokeAll('file_download', array($original_uri));
      // Confirm there's at least one module granting access and none denying access.
      if (!empty($headers) && !in_array(-1, $headers)) {
        return array(
          // Send headers describing the image's size, and MIME-type...
          'Content-Type' => $image->getMimeType(),
          'Content-Length' => $image->getFileSize(),
          // By not explicitly setting them here, this uses normal Drupal
          // Expires, Cache-Control and ETag headers to prevent proxy or
          // browser caching of private images.
        );
      }
    }
    return -1;
  }
}

/**
 * Implements hook_file_move().
 */
function image_file_move(File $file, File $source) {
  // Delete any image derivatives at the original image path.
  image_path_flush($source->getFileUri());
}

/**
 * Implements hook_ENTITY_TYPE_predelete() for file entities.
 */
function image_file_predelete(File $file) {
  // Delete any image derivatives of this image.
  image_path_flush($file->getFileUri());
}

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

/**
 * Gets an array of image styles suitable for using as select list options.
 *
 * @param $include_empty
 *   If TRUE a '- None -' option will be inserted in the options array.
 * @return
 *   Array of image styles both key and value are set to style name.
 */
function image_style_options($include_empty = TRUE) {
  $styles = entity_load_multiple('image_style');
  $options = array();
  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.
 *   - attributes: Additional attributes to apply to the image.
 *   - 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 calling
 *     _theme('image_style') to pass a meaningful value for this variable.
 *     - http://www.w3.org/TR/REC-html40/struct/objects.html#h-13.8
 *     - http://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 attributes to be placed in the img tag.
 */
function template_preprocess_image_style(&$variables) {
  $style = entity_load('image_style', $variables['style_name']);

  // Determine the dimensions of the styled image.
  $dimensions = array(
    'width' => $variables['width'],
    'height' => $variables['height'],
  );

  $style->transformDimensions($dimensions);

  $variables['image'] = array(
    '#theme' => 'image',
    '#width' => $dimensions['width'],
    '#height' => $dimensions['height'],
    '#attributes' => $variables['attributes'],
    '#uri' => $style->buildUrl($variables['uri']),
    '#style_name' => $variables['style_name'],
  );

  if (isset($variables['alt']) || array_key_exists('alt', $variables)) {
    $variables['image']['#alt'] = $variables['alt'];
  }
  if (isset($variables['title']) || array_key_exists('title', $variables)) {
    $variables['image']['#title'] = $variables['title'];
  }

}

/**
 * Accepts a keyword (center, top, left, etc) and returns it as a pixel offset.
 *
 * @param $value
 * @param $current_pixels
 * @param $new_pixels
 */
function image_filter_keyword($value, $current_pixels, $new_pixels) {
  switch ($value) {
    case 'top':
    case 'left':
      return 0;

    case 'bottom':
    case 'right':
      return $current_pixels - $new_pixels;

    case 'center':
      return $current_pixels / 2 - $new_pixels / 2;
  }
  return $value;
}

/**
 * Implements hook_entity_presave().
 *
 * Transforms default image of image field from array into single value at save.
 */
function image_entity_presave(EntityInterface $entity) {
  $field_storage = FALSE;
  $entity_type_id = $entity->getEntityTypeId();
  if ($entity_type_id == 'field_config') {
    $field_storage = $entity->getFieldStorageDefinition();
    $default_settings = \Drupal::service('plugin.manager.field.field_type')->getDefaultFieldSettings('image');
  }
  elseif ($entity_type_id == 'field_storage_config') {
    $field_storage = $entity;
    $default_settings = \Drupal::service('plugin.manager.field.field_type')->getDefaultStorageSettings('image');
  }
  // Exit, if not saving an image field storage or image field entity.
  if (!$field_storage || $field_storage->type != 'image') {
    return;
  }

  if ($field_storage->isSyncing()) {
    return;
  }

  $uuid = $entity->settings['default_image']['uuid'];
  if ($uuid) {
    $original_uuid = isset($entity->original) ? $entity->original->settings['default_image']['uuid'] : NULL;
    if ($uuid != $original_uuid) {
      $file = \Drupal::entityManager()->loadEntityByUuid('file', $uuid);
      if ($file) {
        $image = \Drupal::service('image.factory')->get($file->getFileUri());
        $entity->settings['default_image']['width'] = $image->getWidth();
        $entity->settings['default_image']['height'] = $image->getHeight();
      }
      else {
        $entity->settings['default_image']['uuid'] = NULL;
      }
    }
  }

  $entity->settings['default_image'] += $default_settings['default_image'];
}

/**
 * Implements hook_ENTITY_TYPE_update() for 'field_storage_config'.
 */
function image_field_storage_config_update(FieldStorageConfigInterface $field_storage) {
  if ($field_storage->type != 'image') {
    // Only act on image fields.
    return;
  }

  $prior_field_storage = $field_storage->original;

  // The value of a managed_file element can be an array if #extended == TRUE.
  $uuid_new = $field_storage->settings['default_image']['uuid'];
  $uuid_old = $prior_field_storage->settings['default_image']['uuid'];

  $file_new = $uuid_new ? \Drupal::entityManager()->loadEntityByUuid('file', $uuid_new) : FALSE;

  if ($uuid_new != $uuid_old) {

    // Is there a new file?
    if ($file_new) {
      $file_new->status = FILE_STATUS_PERMANENT;
      $file_new->save();
      \Drupal::service('file.usage')->add($file_new, 'image', 'default_image', $field_storage->uuid());
    }

    // Is there an old file?
    if ($uuid_old && ($file_old = \Drupal::entityManager()->loadEntityByUuid('file', $uuid_old))) {
      \Drupal::service('file.usage')->delete($file_old, 'image', 'default_image', $field_storage->uuid());
    }
  }

  // If the upload destination changed, then move the file.
  if ($file_new && (file_uri_scheme($file_new->getFileUri()) != $field_storage->settings['uri_scheme'])) {
    $directory = $field_storage->settings['uri_scheme'] . '://default_images/';
    file_prepare_directory($directory, FILE_CREATE_DIRECTORY);
    file_move($file_new, $directory . $file_new->filename);
  }
}

/**
 * Implements hook_ENTITY_TYPE_update() for 'field_config'.
 */
function image_field_config_update(FieldConfigInterface $field) {
  $field_storage = $field->getFieldStorageDefinition();
  if ($field_storage->type != 'image') {
    // Only act on image fields.
    return;
  }

  $prior_instance = $field->original;

  $uuid_new = $field->settings['default_image']['uuid'];
  $uuid_old = $prior_instance->settings['default_image']['uuid'];

  // If the old and new files do not match, update the default accordingly.
  $file_new = $uuid_new ? \Drupal::entityManager()->loadEntityByUuid('file', $uuid_new) : FALSE;
  if ($uuid_new != $uuid_old) {
    // Save the new file, if present.
    if ($file_new) {
      $file_new->status = FILE_STATUS_PERMANENT;
      $file_new->save();
      \Drupal::service('file.usage')->add($file_new, 'image', 'default_image', $field->uuid());
    }
    // Delete the old file, if present.
    if ($uuid_old && ($file_old = \Drupal::entityManager()->loadEntityByUuid('file', $uuid_old))) {
      \Drupal::service('file.usage')->delete($file_old, 'image', 'default_image', $field->uuid());
    }
  }

  // If the upload destination changed, then move the file.
  if ($file_new && (file_uri_scheme($file_new->getFileUri()) != $field_storage->settings['uri_scheme'])) {
    $directory = $field_storage->settings['uri_scheme'] . '://default_images/';
    file_prepare_directory($directory, FILE_CREATE_DIRECTORY);
    file_move($file_new, $directory . $file_new->filename);
  }
}

/**
 * Implements hook_ENTITY_TYPE_delete() for 'field_storage_config'.
 */
function image_field_storage_config_delete(FieldStorageConfigInterface $field) {
  if ($field->type != 'image') {
    // Only act on image fields.
    return;
  }

  // The value of a managed_file element can be an array if #extended == TRUE.
  $uuid = $field->settings['default_image']['uuid'];
  if ($uuid && ($file = \Drupal::entityManager()->loadEntityByUuid('file', $uuid))) {
    \Drupal::service('file.usage')->delete($file, 'image', 'default_image', $field->uuid());
  }
}

/**
 * Implements hook_ENTITY_TYPE_delete() for 'field_config'.
 */
function image_field_config_delete(FieldConfigInterface $field) {
  $field_storage = $field->getFieldStorageDefinition();
  if ($field_storage->type != 'image') {
    // Only act on image fields.
    return;
  }

  // The value of a managed_file element can be an array if #extended == TRUE.
  $uuid = $field->settings['default_image']['uuid'];

  // Remove the default image when the instance is deleted.
  if ($uuid && ($file = \Drupal::entityManager()->loadEntityByUuid('file', $uuid))) {
    \Drupal::service('file.usage')->delete($file, 'image', 'default_image', $field->uuid());
  }
}