Developers guide

Glossary

• Pipeline - can be applied to an image to remove all the extra metadata, or to recompress the image etc. Made up from a number of configured processors.
• Processor - Applies a specific optimization to an image.

Writing a processor plugin

• Processors plugins must be in namespace subdirectory Plugin\ImageAPIOptimizeProcessor under the namespace of the module that defines them. In other words, if your module is called 'mymodule', the process plugins must be located in mymodule/src/Plugin/ImageAPIOptimizeProcessor directory.
• Process plugins implement \Drupal\imageapi_optimize\ImageAPIOptimizeProcessorInterface and usually extend \Drupal\imageapi_optimize\ConfigurableImageAPIOptimizeProcessorBase or \Drupal\imageapi_optimize\ImageAPIOptimizeProcessorBase.
• Processor plugins are annotated with \Drupal\imageapi_optimize\Annotation\ImageAPIOptimizeProcessor ;annotation.
• Processor plugins are managed by the \Drupal\imageapi_optimize\ImageAPIOptimizeProcessorManager class.

Example

In your module module_example create SuperWebservice processor plugin.

First, we will create plugin placeholder in our module

mkdir -p src/Plugin/ImageAPIOptimizeProcessor
touch src/Plugin/ImageAPIOptimizeProcessor/SuperWebservice.php

In SuperWebservice.php let's define namespace

<?php

namespace Drupal\module_example\Plugin\ImageAPIOptimizeProcessor;

add SuperWebservice class

<?php

namespace Drupal\module_example\Plugin\ImageAPIOptimizeProcessor;

use Drupal\imageapi_optimize\ConfigurableImageAPIOptimizeProcessorBase;

final class SuperWebservice extends ConfigurableImageAPIOptimizeProcessorBase {

}

and add annotation

<?php

namespace Drupal\module_example\Plugin\ImageAPIOptimizeProcessor;

use Drupal\imageapi_optimize\ConfigurableImageAPIOptimizeProcessorBase;

/**
 * Uses the Super webservice to optimize an image.
 *
 * @ImageAPIOptimizeProcessor(
 *   id = "super_webservice",
 *   label = @Translation("Super Webservice"),
 *   description = @Translation("Uses the Super Web Service to optimize images.")
 * )
 */
final class SuperWebservice extends ConfigurableImageAPIOptimizeProcessorBase {

}

We should then implement a applyToImage method that will process a given image to apply the actual optimizations.

<?php

namespace Drupal\module_example\Plugin\ImageAPIOptimizeProcessor;

use Drupal\imageapi_optimize\ConfigurableImageAPIOptimizeProcessorBase;

/**
 * Uses the Super webservice to optimize an image.
 *
 * @ImageAPIOptimizeProcessor(
 *   id = "super_webservice",
 *   label = @Translation("Super Webservice"),
 *   description = @Translation("Uses the Super Web Service to optimize images.")
 * )
 */
final class SuperWebservice extends ConfigurableImageAPIOptimizeProcessorBase {

  /**
   * {@inheritdoc}
   */
  public function applyToImage($image_uri) {
    if ($optimized_image = super_webservice_apply($image_uri)) {
      // Replace the passed in image with our optimized image.
      file_unmanaged_save_data($optimized_image, $image_uri, FILE_EXISTS_REPLACE);
      // Indicate that our processing was successful.
      return TRUE;
    }
    else {
      return FALSE;
    }
  }

}

Our super web service requires an API key for full functionality, we can capture and use that easily by implementing a few more methods.

<?php

namespace Drupal\module_example\Plugin\ImageAPIOptimizeProcessor;

use Drupal\imageapi_optimize\ConfigurableImageAPIOptimizeProcessorBase;
use Drupal\Core\Form\FormStateInterface;

/**
 * Uses the Super webservice to optimize an image.
 *
 * @ImageAPIOptimizeProcessor(
 *   id = "super_webservice",
 *   label = @Translation("Super Webservice"),
 *   description = @Translation("Uses the Super Web Service to optimize images.")
 * )
 */
final class SuperWebservice extends ConfigurableImageAPIOptimizeProcessorBase {

  /**
   * {@inheritdoc}
   */
  public function applyToImage($image_uri) {
    $api_key = $this->configuration['api_key'];
    if ($optimized_image = super_webservice_apply_with_key($api_key, $image_uri)) {
      // Replace the passed in image with our optimized image.
      file_unmanaged_save_data($optimized_image, $image_uri, FILE_EXISTS_REPLACE);
      // Indicate that our processing was successful.
      return TRUE;
    }
    else {
      return FALSE;
    }
  }

/**
   * {@inheritdoc}
   */
  public function defaultConfiguration() {
    return [
      'api_key' => NULL,
    ];
  }

  /**
   * {@inheritdoc}
   */
  public function buildConfigurationForm(array $form, FormStateInterface $form_state) {
    $form['api_key'] = array(
      '#type' => 'textfield',
      '#title' => $this->t('Super Webservice API key'),
      '#description' => $this->t('Enter required Super Webservice API key. Get your API key from <a href="https://example.com" target="_blank">https://example.com</a>'),
      '#default_value' => $this->configuration['api_key'],
      '#size' => 256,
      '#required' => TRUE
    );
    return $form;
  }

  /**
   * {@inheritdoc}
   */
  public function submitConfigurationForm(array &$form, FormStateInterface $form_state) {
    parent::submitConfigurationForm($form, $form_state);

    $this->configuration['api_key'] = $form_state->getValue('api_key');
  }

}

That's it for the processor class, but if you do provide configuration you should declare those configuration items to the Drupal config schema system:

mkdir -p config/schema
touch config/schema/module_example.schema.yml

In module_example.schema.yml define our configuration schema/metadata.

# Schema for configuration files of the module example module.
#
# Note that this is an extension to the root image_optimize schema namespace.
# Further note that the last element of the key is the processor ID
# defined in the processor annotation.

imageapi_optimize.processor.super_webservice:
  type: mapping
  mapping:
    api_key:
      label: 'API Key'
      type: string