Extending Symelo Image Optimizations

For add-on developers. Symelo Image Optimizations optimizes images with PHP's image libraries (Imagick and GD). Add-ons can register more engines (encoders for JPEG, PNG, WebP, AVIF, PDF or resizing), add cards and tabs to the plugin screen, and add warnings, notes, system information and status fields. This document is the contract: everything listed here keeps working within API version 1.x.

Contents:

1. Versioning
2. Loading an add-on
3. Hooks
4. Engines
5. Background speed
6. Admin screen
7. Status, Site Health and system information
8. Files, options and cleanup
9. Security rules
10. Public classes

Versioning

SYMELO_IMAGES_API_VERSION is a major.minor string, currently 1.0. It is defined only when the plugin actually runs (PHP 7.4 or newer), before symelo_images_loaded fires.

• Minor versions (1.1, 1.2, …) only add: new hooks, new parameters at the end of a hook, new public methods, new methods with a default in AbstractEngine, new Job properties, new tasks in Settings::TASKS, new keys in arrays (status, profiles, system information sections), new CSS classes.
• Major versions (2.0) may break. Breaking changes are: removing or renaming a hook, a public class, method or constant listed here; changing a hook's or a method's parameters or return type; changing what a Job property, a task name or a profile key means; adding a method to EngineInterface; removing a CSS class or data- attribute listed in Admin screen.
• EngineInterface doesn't change within 1.x. Optional engine features added later come as methods of AbstractEngine with a default, so engines that extend it keep working. Implementing EngineInterface directly is allowed but gets none of those defaults.
• Everything not listed in this document (other classes, private and internal methods, the settings option layout, database tables, the symelo_images_* admin-post actions and nonces) is internal and may change in any version.

Check the version before using anything:

function my_addon_api_ok(): bool {
	if ( ! defined( 'SYMELO_IMAGES_API_VERSION' ) ) {
		return false; // Not installed, not active, or PHP too old.
	}
	$version = (string) SYMELO_IMAGES_API_VERSION;
	return 1 === (int) $version && version_compare( $version, '1.0', '>=' ); // Major 1, at least 1.0.
}

Loading an add-on

• Add Requires Plugins: symelo-image-optimizations to the add-on's header. WordPress 6.5 and newer then won't activate the add-on without the plugin, and won't deactivate the plugin while the add-on is active. Still guard everything: on WordPress 6.4, or when files are removed by hand, the add-on loads without the plugin.
• Plugins load in alphabetical order of their folder, and network-activated plugins load before the site's, so the add-on may load before or after Symelo Image Optimizations. Attach like this:

if ( did_action( 'symelo_images_loaded' ) ) {
	my_addon_start( \Symelo\Images\Plugin::instance() );
} else {
	add_action( 'symelo_images_loaded', 'my_addon_start' );
}
// Still not started once every plugin is loaded: show an admin notice.
add_action( 'plugins_loaded', 'my_addon_check', 20 );

• In my_addon_start(), check the API version first. Load nothing that extends or implements a class of the plugin (engines, for example) before that: without the plugin, PHP would stop with a fatal error. The add-on's main file, its autoloader and its bootstrap code must work without the plugin.
• Deactivating Symelo Image Optimizations must never break the site: the add-on then only shows a notice ("Install and activate Symelo Image Optimizations").

Hooks

Actions

Filters

Site Health tests: use core's site_status_tests filter with test IDs of your own prefix; nothing from this plugin is needed.

Engines

An engine encodes files for one or more tasks: jpeg (JPEG compression), png (PNG compression), webp (WebP copies), avif (AVIF copies), pdf (PDF compression) and resize (scaling and rotating, also used to prepare copies for engines that can't). Settings::TASKS lists them. The plugin brings imagick and gd; no built-in engine handles pdf.

Registering

use Symelo\Images\Engines\AbstractEngine;
use Symelo\Images\Engines\EngineException;
use Symelo\Images\Engines\EngineManager;
use Symelo\Images\Engines\Job;

final class My_Webp_Engine extends AbstractEngine {

	public function id(): string {
		return 'my-webp';
	}

	public function label(): string {
		return 'My WebP encoder';
	}

	public function tasks(): array {
		return array( 'webp' => $this->works() ? true : __( 'The encoder is missing.', 'my-addon' ) );
	}

	public function rank( string $task ): int {
		return 10; // Before Imagick (50) and GD (60).
	}

	public function accepts( Job $job ): bool {
		return $this->can( $job->task ) && in_array( $job->info->format, array( 'jpeg', 'png' ), true ) && ! $job->needs_preparing();
	}

	public function run( Job $job, string $dest ): void {
		if ( ! my_encode( $job->source(), $dest, $job->quality ) ) {
			throw new EngineException( esc_html__( 'My encoder failed.', 'my-addon' ) );
		}
	}

	private function works(): bool {
		return true;
	}
}

add_action(
	'symelo_images_register_engines',
	static function ( EngineManager $engines ) {
		$engines->add( new My_Webp_Engine() );
	}
);

EngineManager::add() replaces an engine with the same ID; remove( $id ) removes one. IDs must be what sanitize_key() returns (lowercase letters, digits, _, -) and not auto. Make them distinctive: prefix them unless they are the name of a well-known program (cwebp).

EngineInterface

AbstractEngine implements everything except id(), label(), tasks() and run(): no origin, version or note, rank static::RANK (100), not explicit-only, can't transform, accepts() = can( $job->task ). It adds can( string $task ): bool (the task is true in tasks()). EngineManager::can( $engine, $task ) does the same for any engine.

Ranks and the automatic order

For a task, the order is built from every registered engine whose tasks() has that task (usable here or not):

1. sorted by rank( $task ), lower first; equal ranks keep the order of registration (Imagick, GD, then add-ons in the order they called add());
2. passed through symelo_images_engine_order ($ids, $task), which may reorder or remove IDs.

That order is what the Engines tab lists. To optimize a file, the plugin tries, in turn:

1. the engine the admin chose for the task (Engine for each job), if it is still registered and works here;
2. every other engine in the order, except explicit-only ones;

and uses the first one whose tasks() has the task as true and whose accepts() returns true. If run() fails, the next one is tried. The engine shown as Automatic (…) is the first one that works for the task in general (EngineManager::preferred()).

The choice per task is validated against the registered engines: saving an engine that is registered but can't do the task here gives "engine can't do that job on this server, so Automatic is used instead." A stored choice for an engine that is no longer registered (the add-on was deactivated) silently counts as Automatic (EngineManager::choice() returns auto) and is dropped the next time the Engines tab is saved.

Job

Job describes one piece of work. Engines read its properties and never change them (the plugin hands the same job to the next engine).

Prepared copies

Engines that can't rotate or scale return false from can_transform() and decline (accepts() → false) jobs that needs_preparing(). The plugin then makes a lossless PNG that is already rotated and scaled (with the engine for resize, Imagick or GD) and calls accepts() again with $job->with_source( $prepared ). An engine that doesn't decode pixels (a lossless JPEG optimizer that keeps the EXIF orientation, for example) may accept rotated JPEGs as long as $resize is null.

Errors and results

• run() writes the result to $dest, a new path (overwrite it if it exists). During optimization it is a fresh file in the plugin's private temporary folder, which the plugin deletes afterwards; the delivery self-test writes test copies in uploads/symelo-images/public/. Don't write anywhere else except temporary files of your own in Paths::temp_dir(), and delete those before returning, also on failure.
• On failure throw EngineException with a message for admins, escaped like every exception message in WordPress: new EngineException( esc_html__( '…', 'my-addon' ) ) or esc_html( sprintf( … ) ). The plugin stores $e->plain_message(), which undoes that escaping, and escapes again wherever it prints it. The message is shown with the file, and the next engine is tried.
• When the engine worked but the result can't be smaller, throw EngineException::no_gain(): the plugin stops trying other engines for that job and keeps what it has.
• After run(), the plugin checks the output: its content must be the expected format (sniffed from the bytes), same-format results are kept only when meaningfully smaller (1 KB or 1%, unless resized), WebP and AVIF copies only when smaller than the file (an AVIF also smaller than the WebP), and PDFs only when the output is a PDF and smaller. Writing in place is atomic, and the original is backed up first.
• PDF engines check Image\PdfInfo::read( $job->source() ) (encrypted, signed, forms): signed PDFs must never be rewritten.

Background speed

Queue\Pace holds the speed profiles of Advanced → Background speed (fast, normal, gentle).

• Pace::current(): array is the profile in effect (with the symelo_images_pace filter applied). An engine that starts encoder programs reads nice and idle_io from it for every run, and its thread count from Job::$threads.
• Pace::profile( string $speed ): array returns one profile; Pace::SPEEDS lists the speeds.
• Pace::busy( array $profile ): bool, Pace::load_per_core(): ?float and Pace::cpu_count(): int tell whether the server is busy, for background work of your own.
• Uploads and explicit runs ("Optimize now", WP-CLI without --paced, the REST API) don't wait for pauses or load, but still use the profile's priority and threads.

Admin screen

The screen is Media → Image Optimizations (page slug Admin\Admin::PAGE, symelo-images; screen ID media_page_symelo-images). Every tab is printed on each page load and switches in the browser, so cards must be cheap to render.

• Engines tab cards: print them on symelo_images_engines_tab.
• Tabs: add slug => label with symelo_images_tabs, then print the panel's content on symelo_images_tab_{$slug}. The plugin wraps it in <div class="symelo-panel" data-panel="{slug}">. Admin\Ui::url( array( 'tab' => $slug ) ) links to it; links with data-tab-link="{slug}" switch tabs in place.
• Assets: the plugin's assets/admin.css and assets/admin.js are loaded on the screen. Load your own only on that screen (admin_enqueue_scripts, $hook_suffix contains symelo-images), with your own handle.

Markup and helpers to reuse (stable within 1.x):

Forms and handlers:

• Post to admin-post.php with an action of your own prefix (admin_post_{your_prefix}_{action}). Never post to the plugin's symelo_images_* actions or use its nonces.
• In the handler: check current_user_can( \Symelo\Images\Plugin::capability() ) first (stop with wp_die( …, 403 )), then check_admin_referer( '{your_prefix}_{action}' ), then sanitize every field. Redirect back with wp_safe_redirect( Ui::url( array( 'tab' => 'tools' ) ) ); exit;.
• After changing anything that affects engines, call Plugin::instance()->reset_engines() so the next use rebuilds the engine list.
• REST routes: a namespace of your own, permission_callback checking Plugin::capability(), argument schemas for every input.

Status, Site Health and system information

• symelo_images_warnings / symelo_images_notes: plain-text strings (see Filters). Warnings are for things the admin should fix (an encoder with known security holes); notes are calm information. The plugin's own Site Health test "Image libraries are up to date" only covers its libraries; add your own Site Health tests with core's site_status_tests.
• symelo_images_system_info: $sections['My Add-on'] = array( 'Version' => '1.2.3', … ). Values are plain text.
• symelo_images_rest_status: $status['my_addon'] = array( … ).

Files, options and cleanup

• The plugin owns uploads/symelo-images/ (backups/, tmp/, public/) and deletes uploads/symelo-images/tools/ (a folder of pre-release versions) when it is installed or updated. Keep add-on files in a folder of your own, for example uploads/{your-slug}/, protected like the plugin's (index.php, .htaccess with Require all denied, web.config).
• Support\Paths::temp_dir() is the plugin's private temporary folder, for short-lived files of engines. Files older than a day are deleted daily; delete yours right away.
• Keep settings in an option of your own. Never write symelo_images_settings, the plugin's table or its other options.
• When the plugin is deleted, it removes transients whose names start with symelo_images_, so add-on transients named like that are caches only.
• Clean up on your own uninstall (uninstall.php), without loading the plugin.

Security rules

Add-ons should keep the plugin's rules:

• PHP 7.4 syntax and WordPress 6.4 APIs, unless the add-on requires more.
• Capability, then nonce, in every handler; sanitize input, escape output, $wpdb->prepare() every query.
• Never accept a file path or program path from a request or a setting; work only on Job::source(), $dest and folders you own.
• Run programs only with argument arrays (no shell), a minimal environment and time limits, and refuse versions with known security holes.
• Messages in EngineException are escaped where thrown.

Public classes

Stable within API 1.x (namespace Symelo\Images):