Imagify — Engineering Deep Dive

Entry Point — imagify.php

WordPress loads imagify.php during the plugins_loaded phase. It defines all constants and registers activation/deactivation hooks before delegating to inc/main.php.

// imagify.php — constants defined at plugin load time
define( 'IMAGIFY_VERSION',        '2.2.8' );
define( 'IMAGIFY_SLUG',           'imagify' );
define( 'IMAGIFY_FILE',           __FILE__ );
define( 'IMAGIFY_PATH',           realpath( plugin_dir_path( IMAGIFY_FILE ) ) . '/' );
define( 'IMAGIFY_URL',            plugin_dir_url( IMAGIFY_FILE ) );
define( 'IMAGIFY_ASSETS_IMG_URL', IMAGIFY_URL . 'assets/images/' );
define( 'IMAGIFY_MAX_BYTES',      5242880 );   // 5 MB hard limit per image
define( 'IMAGIFY_INT_MAX',        PHP_INT_MAX - 30 );
define( 'IMAGIFY_SITE_DOMAIN',    'https://imagify.io' );
define( 'IMAGIFY_APP_DOMAIN',     'https://app.imagify.io' );
define( 'IMAGIFY_APP_API_URL',    IMAGIFY_APP_DOMAIN . '/api/' );

Bootstrap Sequence

imagify_init() lives in inc/main.php. It skips execution if DOING_AUTOSAVE is defined. The Plugin class (classes/Plugin.php) receives a League\Container instance and the plugin path, then orchestrates the full init sequence:

// classes/Plugin.php — init sequence (abridged)
public function init( array $providers ): void {
    // 1. Register shared services
    $this->container->addShared( 'event_manager', fn() => new EventManager() );
    $this->container->addShared( 'filesystem',    fn() => new Imagify_Filesystem() );

    // 2. Include procedural files (functions/, common/, 3rd-party/)
    $this->include_files();

    // 3. Init legacy singletons
    Imagify_Auto_Optimization::get_instance()->init();
    Imagify_Options::get_instance()->init();
    Imagify_Data::get_instance()->init();
    Imagify_Folders_DB::get_instance()->init();
    Imagify_Files_DB::get_instance()->init();
    Imagify_Cron_Library_Size::get_instance()->init();
    Imagify_Cron_Rating::get_instance()->init();
    Imagify_Cron_Sync_Files::get_instance()->init();
    Imagify\Auth\Basic::get_instance()->init();
    Imagify\Job\MediaOptimization::get_instance()->init();
    Bulk::get_instance()->init();

    // 4. Admin-only classes
    if ( is_admin() ) { ... }

    // 5. Register PSR-4 service providers + subscribers
    foreach ( $providers as $service_provider ) {
        $this->container->addServiceProvider( new $service_provider() );
        $this->load_subscribers( $provider_instance );
    }

    do_action( 'imagify_loaded', $this );
}

Activation / Deactivation Hooks

Service Providers (config/providers.php)

PSR-4 Autoload Map (composer.json)

Classmap (legacy, non-PSR-4)

inc/classes/ and inc/deprecated/classes/ are loaded via Composer classmap. The convention is class-imagify-{name}.php → Imagify_{Name}. Two files are explicitly excluded from the classmap: class-imagify-plugin.php and class-imagify-requirements-check.php (loaded manually before autoloader is available).

Key classes/ Sub-namespaces

Class Inheritance Chain

ProcessInterface                          // classes/Optimization/Process/ProcessInterface.php
  └── AbstractProcess                    // classes/Optimization/Process/AbstractProcess.php (~2100 lines)
        ├── Process\WP                   // WP Media Library context
        ├── Process\CustomFolders        // Custom Folders context
        └── Process\Noop                 // No-op fallback

DataInterface                             // classes/Optimization/Data/DataInterface.php
  └── AbstractData
        ├── Data\WP                      // stores _imagify_data postmeta
        ├── Data\CustomFolders           // stores in imagify_files table
        └── Data\Noop

MediaInterface                            // classes/Media/MediaInterface.php
  └── AbstractMedia
        ├── Media\WP
        ├── Media\CustomFolders
        └── Media\Noop

ContextInterface                          // classes/Context/ContextInterface.php
  └── AbstractContext
        ├── Context\WP
        ├── Context\CustomFolders
        └── Context\Noop

Context Factory Functions

// inc/functions/common.php
imagify_get_context( string $context ): ContextInterface
imagify_get_optimization_process( int $media_id, string $context ): ProcessInterface

// Context values: 'wp' | 'custom-folders' | 'ngg' (when NGG active)
// Filterable via: imagify_context_class_name, imagify_process_class_name

AbstractProcess — Key Method Signatures

Optimization Call Flow — Single Media

Per-Size Data Structure Stored

// Stored in _imagify_data['sizes'][$size_name] (WP context)
// On success:
[
    'success'        => true,
    'original_size'  => int,   // bytes before optimization
    'optimized_size' => int,   // bytes after optimization
    'percent'        => float, // savings percentage (2 decimal places)
]

// On error:
[
    'success' => false,
    'error'   => string,  // human-readable error message
]

Class: Imagify\Optimization\File — classes/Optimization/File.php (931 lines).

Injected with Imagify_Filesystem::get_instance(). Does not extend anything — purely compositional.

Constructor & Properties

class File {
    protected string             $path;       // absolute path to file
    protected ?bool              $is_image;   // cached result of is_image()
    protected ?object           $file_type;  // {ext, type} from wp_check_filetype()
    protected Imagify_Filesystem $filesystem;
    protected mixed              $editor;    // WP_Image_Editor_Imagick|WP_Image_Editor_GD|WP_Error
    protected array             $options;   // cached get_imagify_option() calls

    public function __construct( string $file_path ) {...}
}

Public Methods

optimize() — Args Array

optimize( [
    'backup'             => true,    // false = skip backup regardless of user setting
    'backup_path'        => null,    // string — explicit backup destination path
    'backup_source'      => null,    // string — source to backup (WP 5.3+ original)
    'optimization_level' => 0,       // 0=normal/lossless, 1=aggressive, 2=ultra
    'convert'            => '',      // 'webp' | 'avif' | '' for original format
    'context'            => 'wp',   // sent to API for logging
    'original_size'      => 0,       // bytes, sent to API
] );

Class: Imagify (legacy classmap) — inc/classes/class-imagify.php. Singleton via InstanceGetterTrait.

Base URL: IMAGIFY_APP_API_URL = https://app.imagify.io/api/

Authentication

// Headers set in __construct() using stored API key
$this->all_headers['Accept']        = 'Accept: application/json';
$this->all_headers['Content-Type']  = 'Content-Type: application/json';
$this->all_headers['Authorization'] = 'Authorization: token ' . $this->api_key;

// upload_image() sends only Authorization header (multipart/form-data via cURL)
// All other endpoints send all three headers

Transport Strategy

The private http_call() method auto-selects transport: if $args['post_data']['image'] is set, it routes to curl_http_call() (direct cURL for multipart file uploads); otherwise uses WordPress wp_remote_request(). A pre_imagify_request filter allows short-circuiting the cURL path.

All Endpoints

Upload Request Body (multipart via cURL)

// $data array passed to upload_image()
[
    'image' => '/absolute/path/to/image.jpg',  // CURLFile in cURL transport
    'data'  => json_encode([
        'normal'        => true/false,  // level === 0
        'aggressive'    => true/false,  // level === 1
        'ultra'         => true/false,  // level === 2
        'keep_exif'     => true,
        'original_size' => int,
        'context'       => string,     // 'wp' | 'custom-folders' | 'ngg'
        'convert'       => string,     // 'webp' | 'avif' — only when converting
    ]),
]

API Response Shape (upload/fetch)

// Success — stdClass
{
    "image": "https://app.imagify.io/...temp_url...",  // URL for download_url()
    "original_size": 123456,
    "new_size": 98765,
    "percent": 19.87,
    // "message" key present when conversion was not possible (falls back to original)
}

// Error — WP_Error with code 'error {http_code}'
// HTTP 401 → invalid API key
// HTTP 413 → file too large
// HTTP 4xx/5xx → $response->detail or $response->image error array

HTTP Response Handling

private function handle_response( string $response, int $http_code, string $error = '' ) {
    $response = json_decode( $response );          // stdClass or null
    if ( 200 !== $http_code && !empty( $response->code ) ) {
        // $response->detail → WP_Error message
        // $response->image  → array of field errors
        return new WP_Error( 'error ' . $http_code, ... );
    }
    if ( ! is_object( $response ) ) {
        return new WP_Error( 'not_valid_json', ... );
    }
    return $response;
}

Primary Metadata Keys (WP Media Library)

All stored on the attachment post (post_type = attachment). Managed by Imagify\Optimization\Data\WP.

_imagify_data Full Schema

// _imagify_data serialized array structure
[
    'sizes'  => [
        'full'      => [ 'success' => true, 'original_size' => int, 'optimized_size' => int, 'percent' => float ],
        'thumbnail' => [ 'success' => true, ... ],
        'medium'    => [ 'success' => false, 'error' => string ],
        // ... one entry per registered image size + any custom sizes
    ],
    'stats'  => [
        'original_size'  => int,    // sum across all successful sizes
        'optimized_size' => int,    // sum across all successful sizes
        'percent'        => float,  // aggregate % (2 decimal places)
    ],
    'message' => string,           // optional message from API (e.g. already optimized)
]

Standard WordPress Keys (also modified by Imagify)

Option name: imagify_settings (single site) or imagify_settings stored via get_site_option (network). Set via get_imagify_option($key) / update_imagify_option($key, $value).

imagify_folders

Class: Imagify_Folders_DB (inc/classes/class-imagify-folders-db.php). Global table in multisite ($wpdb->base_prefix). Table version: 100.

CREATE TABLE `{prefix}imagify_folders` (
    `folder_id`  bigint(20) unsigned NOT NULL auto_increment,
    `path`       varchar(191)        NOT NULL default '',
    `active`     tinyint(1) unsigned NOT NULL default 0,
    PRIMARY KEY  (folder_id),
    UNIQUE KEY   path (path),
    KEY          active (active)
);

imagify_files

Class: Imagify_Files_DB (inc/classes/class-imagify-files-db.php). Global table in multisite. Table version: 102.

CREATE TABLE `{prefix}imagify_files` (
    `file_id`            bigint(20) unsigned  NOT NULL auto_increment,
    `folder_id`          bigint(20) unsigned  NOT NULL default 0,
    `file_date`          datetime             NOT NULL default '0000-00-00 00:00:00',
    `path`               varchar(191)         NOT NULL default '',
    `hash`               varchar(32)          NOT NULL default '',   -- MD5 of file
    `mime_type`          varchar(100)         NOT NULL default '',
    `modified`           tinyint(1) unsigned  NOT NULL default 0,
    `width`              smallint(2) unsigned NOT NULL default 0,
    `height`             smallint(2) unsigned NOT NULL default 0,
    `original_size`      int(4) unsigned      NOT NULL default 0,
    `optimized_size`     int(4) unsigned      default NULL,
    `percent`            smallint(2) unsigned default NULL,
    `optimization_level` tinyint(1) unsigned  default NULL,
    `status`             varchar(20)          default NULL,
    `error`              varchar(255)         default NULL,
    `data`               longtext             default NULL,   -- serialized, see below
    PRIMARY KEY  (file_id),
    UNIQUE KEY   path (path),
    KEY          folder_id (folder_id),
    KEY          optimization_level (optimization_level),
    KEY          status (status),
    KEY          modified (modified)
);

ngg_imagify_data (NextGEN Gallery)

Class: Imagify\ThirdParty\NGG\DB (inc/3rd-party/nextgen-gallery/classes/DB.php). Per-site table ($wpdb->prefix). Table version: 100.

CREATE TABLE `{prefix}ngg_imagify_data` (
    `data_id`            bigint(20) unsigned NOT NULL auto_increment,
    `pid`                bigint(20) unsigned NOT NULL default 0,
    `optimization_level` varchar(1)          NOT NULL default '',
    `status`             varchar(30)         NOT NULL default '',
    `data`               longtext            default NULL,
    PRIMARY KEY  (data_id),
    KEY          pid (pid)
);

pid is the NextGEN picture ID. data is serialized the same way as _imagify_data.

Abstract DB Base Class

All three DB classes extend Imagify_Abstract_DB which implements Imagify\DB\DBInterface. It provides:

Class: Imagify\Bulk\Bulk (classes/Bulk/Bulk.php). Singleton. Registered hooks in init().

Bulk Run Flow

ActionScheduler Job Enqueue

// Bulk::run_optimize() — one as_enqueue_async_action() per media
as_enqueue_async_action(
    'imagify_optimize_media',
    [
        'id'      => (int) $media_id,
        'context' => (string) $context,      // 'wp' | 'custom-folders'
        'level'   => (int) $optimization_level,
    ],
    "imagify-{$context}-optimize-media"   // group name — allows cancellation per context
);

// Next-gen generation uses a separate hook
as_enqueue_async_action(
    'imagify_convert_next_gen',
    [ 'id' => $media_id, 'context' => $context ],
    "imagify-{$context}-convert-nextgen"
);

Progress Tracking Transients

ActionScheduler Job Lifecycle

ActionScheduler is bundled at inc/Dependencies/ActionScheduler/action-scheduler.php. Jobs go through these states:

On failure: failed. On cancel: canceled. The check_optimization_status() hook fires on imagify_after_optimize and decrements the running counter, deleting the transient and setting the complete transient when all jobs finish.

Multisite Context Routing

// Bulk::get_contexts() — determines which contexts appear on bulk page
if ( ! is_network_admin() ) {
    $types['library|wp'] = 1;                // library only in site admin
}
if ( imagify_is_active_for_network() && is_network_admin() ) {
    $types['custom-folders|custom-folders'] = 1;  // custom folders in network admin
} elseif ( ! imagify_is_active_for_network() ) {
    $types['custom-folders|custom-folders'] = 1;  // custom folders in site admin
}

Per-Media Process Lock

Defined in AbstractProcess. Each lock is a transient named after the context and media ID.

// Transient name pattern (LOCK_NAME constant)
const LOCK_NAME = 'imagify_%1$s_%2$s_process_locked';
// Example: 'imagify_wp_42_process_locked'
// Example: 'imagify_custom-folders_7_process_locked'

// Network-aware: uses set_site_transient when context is_network_wide()
public function lock( string $action = 'optimizing' ): void {
    $name     = $this->get_lock_name();           // sprintf(LOCK_NAME, ctx, id)
    $callback = $media->get_context_instance()->is_network_wide()
        ? 'set_site_transient' : 'set_transient';
    call_user_func( $callback, $name, $action, 10 * MINUTE_IN_SECONDS );
}

public function is_locked(): string|false {
    // Returns 'optimizing' | 'restoring' | false
    $callback = ...'get_site_transient' or 'get_transient'...;
    $action   = call_user_func( $callback, $name );
    return $this->validate_lock_action( $action );  // normalizes 'restore' → 'restoring'
}

public function unlock(): void {
    $callback = ...'delete_site_transient' or 'delete_transient'...;
    call_user_func( $callback, $name );
}

Lock Actions

Transient Name Summary for Cleanup

Managed by Imagify\Tools\InternalStateList::get_locked_transient_patterns(). Used by ResetInternalState for SQL LIKE deletion:

'_transient_%imagify-auto-optimize-%'      // Legacy (deprecated)
'_transient_%imagify_rpc_%'                // Legacy (deprecated)
'_transient_imagify_%_process_locked'      // Active single-site locks
'_site_transient_imagify_%_process_lock%'  // Active network-wide locks

Class: Imagify\Picture\Display (classes/Picture/Display.php). Implements SubscriberInterface.

Subscribed Events

public static function get_subscribed_events(): array {
    return [
        'template_redirect'            => 'start_content_process',
        'imagify_process_webp_content' => 'process_content',
    ];
}

Full Rewrite Pipeline

Guards in start_content_process()

• get_imagify_option('display_nextgen') must be truthy
• get_imagify_option('display_nextgen_method') must equal 'picture' (Display::OPTION_VALUE)
• Filter imagify_allow_picture_tags_for_nextgen must return true

Lazy-Load Support

The parser checks these src attributes in priority order: data-lazy-src → data-src → src. Likewise for srcset: data-lazy-srcset → data-srcset → srcset. The generated <source> tag mirrors whichever attribute was active.

Generated HTML Structure

<!-- Input -->
<img src="/uploads/photo.jpg" srcset="/uploads/photo-300.jpg 300w" sizes="..." alt="...">

<!-- Output (when both AVIF and WebP exist) -->
<picture>
  <source type="image/avif" srcset="/uploads/photo.jpg.avif, /uploads/photo-300.jpg.avif 300w" sizes="...">
  <source type="image/webp" srcset="/uploads/photo.jpg.webp, /uploads/photo-300.jpg.webp 300w" sizes="...">
  <img src="/uploads/photo.jpg" srcset="/uploads/photo-300.jpg 300w" sizes="..." alt="...">
</picture>

URL → Path Resolution

url_to_path() converts image URLs to filesystem paths for existence checks. It handles: uploads URL, site root URL, CDN URL (via imagify_cdn_source_url filter), and protocol-relative URLs. Static caches are maintained per request.

Filters on the Rewrite Path

Security is enforced by imagify_check_nonce($action, $query_arg) which wraps check_ajax_referer() and calls imagify_die() on failure. Capability checks use imagify_get_context($ctx)->current_user_can($capability, $media_id).

wp_ajax_* + admin_post_* (both)

These are registered for both AJAX and form POST. Handler class: Imagify_Admin_Ajax_Post.

wp_ajax_* only

admin_post_* only