Hooks & Filters

Compresso exposes WordPress actions and filters that let you hook into the optimization lifecycle, customize behavior, and integrate with other plugins.

Actions

compresso_before_optimize

Fires immediately before an image is optimized. Runs during both manual optimization and auto-optimize on upload.

do_action( 'compresso_before_optimize', int $attachment_id, string $file );

Internal usage: Compresso's Backup class hooks into this at priority 5 to save a copy of the original before optimization. The Cloud Backup module (Pro) also hooks in to queue a cloud upload.

Example: Log every optimization

add_action( 'compresso_before_optimize', function( int $attachment_id, string $file ) {
    error_log( sprintf( 'Compresso: about to optimize #%d (%s)', $attachment_id, basename( $file ) ) );
}, 10, 2 );

Example: Skip optimization for certain images

Since this fires before optimization, you can't cancel it from here. To conditionally skip images, use the skip_small_images / skip_large_images settings, or filter the attachment before it reaches the optimizer.

compresso_after_optimize

Fires after an image has been successfully optimized and its metadata saved. Runs during both manual optimization and auto-optimize on upload.

do_action( 'compresso_after_optimize', int $attachment_id, string $file, array $data );

The $data array contains:

Internal usage: The Analytics module (Pro) hooks in to log metrics. The GIF Converter (Pro) hooks in to convert animated GIFs after they've been optimized.

Example: Send a notification when bulk optimization saves over 100 MB

add_action( 'compresso_after_optimize', function( int $attachment_id, string $file, array $data ) {
    $stats = get_option( 'compresso_stats', [] );
    $total = $stats['total_savings'] ?? 0;

    // Check if we just crossed the 100 MB threshold
    if ( $total >= 100 * MB_IN_BYTES && ( $total - $data['total_savings'] ) < 100 * MB_IN_BYTES ) {
        wp_mail(
            get_option( 'admin_email' ),
            'Compresso: 100 MB saved!',
            sprintf( 'Your site has now saved %s through image optimization.', size_format( $total ) )
        );
    }
}, 10, 3 );

Example: Sync optimized images to a CDN

add_action( 'compresso_after_optimize', function( int $attachment_id, string $file, array $data ) {
    if ( ! $data['optimized'] ) {
        return;
    }

    // Push the optimized file to your CDN
    my_cdn_upload( $file );

    // Also push the WebP version if created
    if ( $data['webp_created'] ) {
        $webp_file = preg_replace( '/\.(jpe?g|png)$/i', '.webp', $file );
        if ( file_exists( $webp_file ) ) {
            my_cdn_upload( $webp_file );
        }
    }
}, 10, 3 );

Filters

compresso_formats

Filter the list of supported image output formats. Used internally by the AVIF module to register AVIF as an available format.

apply_filters( 'compresso_formats', array $formats );

Returns: Modified array of format strings.

Example: Register a custom output format

add_filter( 'compresso_formats', function( array $formats ): array {
    $formats[] = 'jxl'; // JPEG XL
    return $formats;
} );

compresso_disable_legacy_decryption

Controls whether Compresso rejects encrypted values that were stored without HMAC authentication. The plugin uses authenticated encryption (HMAC-SHA256) for sensitive data like OAuth tokens. Older stored values may lack HMAC — this filter lets you reject them.

apply_filters( 'compresso_disable_legacy_decryption', bool $disable );

Returns: true to reject values without HMAC verification (stricter security), false to allow fallback decryption.

Example: Enforce strict encryption

add_filter( 'compresso_disable_legacy_decryption', '__return_true' );

Action Scheduler Hooks

These are internal hooks processed by Action Scheduler for background tasks. They're listed here for reference but are not intended for external use.

Global Functions

Compresso provides two global helper functions:

compresso()

Returns the main plugin instance. Useful for accessing internal components.

$plugin = compresso();

compresso_is_pro()

Check whether a valid Pro license is active.

if ( compresso_is_pro() ) {
    // Pro-only logic
}