DOCUMENTATION · DEVELOPER HOOKS

Developer hooks

Three hooks to integrate Tempaloo with your custom theme or plugin. They fire identically on the auto-convert-on-upload path and the bulk path, so a single rule applies everywhere.

At a glance

tempaloo_webp_skip_attachment — bypass conversion per attachment.
tempaloo_webp_quality_for — override quality (1-100) per attachment.
tempaloo_webp_after_convert — fire on every successful conversion.

Where to put the code

Drop these snippets in your theme's functions.php or in a tiny custom plugin file at wp-content/plugins/your-tempaloo-tweaks/your-tempaloo-tweaks.php. They take effect on the next upload or bulk run — no plugin reactivation needed.

tempaloo_webp_skip_attachment

Filter that decides whether an attachment should be converted at all. Return true to skip.

Signature

php

apply_filters( 'tempaloo_webp_skip_attachment',
    bool $skip,            // default false
    int  $attachment_id,
    string $mode           // 'auto' | 'bulk'
);

Example: exclude a folder

php

add_filter( 'tempaloo_webp_skip_attachment', function( $skip, $id ) {
    $path = get_attached_file( $id );
    return $path && false !== strpos( $path, '/uploads/private/' );
}, 10, 2 );

Example: only convert published media

php

add_filter( 'tempaloo_webp_skip_attachment', function( $skip, $id ) {
    $parent = wp_get_post_parent_id( $id );
    if ( ! $parent ) return $skip;
    return get_post_status( $parent ) !== 'publish';
}, 10, 2 );

Example: skip by mime type or size

php

add_filter( 'tempaloo_webp_skip_attachment', function( $skip, $id ) {
    $mime = get_post_mime_type( $id );
    if ( 'image/gif' === $mime ) return true;          // never touch GIFs
    $path = get_attached_file( $id );
    if ( $path && filesize( $path ) < 50 * 1024 ) {
        return true;                                    // skip files < 50 KB
    }
    return $skip;
}, 10, 2 );

tempaloo_webp_quality_for

Filter that overrides the quality value (1-100) for a specific attachment. Returned values are clamped to 1-100, so a typo can't break your conversion.

Signature

php

apply_filters( 'tempaloo_webp_quality_for',
    int    $quality,        // current quality from settings
    int    $attachment_id,
    string $format          // 'webp' | 'avif' (the chosen target)
);

Example: lift quality on portfolio images

php

add_filter( 'tempaloo_webp_quality_for', function( $q, $id, $format ) {
    if ( has_term( 'portfolio', 'attachment_category', $id ) ) {
        return 92;
    }
    return $q;
}, 10, 3 );

Example: drop quality for AVIF (it tolerates lower q)

php

add_filter( 'tempaloo_webp_quality_for', function( $q, $id, $format ) {
    return $format === 'avif' ? max( 50, $q - 10 ) : $q;
}, 10, 3 );

Example: per-CPT presets

php

add_filter( 'tempaloo_webp_quality_for', function( $q, $id ) {
    $parent = wp_get_post_parent_id( $id );
    if ( $parent && get_post_type( $parent ) === 'product' ) {
        return 80;   // crisper product photos
    }
    return $q;
}, 10, 2 );

tempaloo_webp_after_convert

Action fired after a successful conversion (one or more sizes written). Hook in here to invalidate your CDN, log to your own system, or trigger a webhook.

Signature

php

do_action( 'tempaloo_webp_after_convert',
    int   $attachment_id,
    array $info {
        string $format;       // 'webp' | 'avif'
        int    $converted;    // number of sizes converted
        int    $failed;
        string $mode;         // 'auto' | 'bulk'
        int    $quality;      // post-filter quality used
        array  $sizes;        // map of generated files: orig_basename => { file, bytes }
    }
);

Example: purge Cloudflare

php

add_action( 'tempaloo_webp_after_convert', function( $id, $info ) {
    if ( $info['converted'] === 0 ) return;
    $url = wp_get_attachment_url( $id );
    wp_remote_post(
        'https://api.cloudflare.com/client/v4/zones/' . CF_ZONE . '/purge_cache',
        [
            'headers' => [
                'Authorization' => 'Bearer ' . CF_TOKEN,
                'Content-Type'  => 'application/json',
            ],
            'body' => wp_json_encode( [ 'files' => [ $url, $url . '.webp', $url . '.avif' ] ] ),
        ]
    );
}, 10, 2 );

Example: log to your analytics

php

add_action( 'tempaloo_webp_after_convert', function( $id, $info ) {
    error_log( sprintf(
        '[tempaloo] #%d %s converted %d sizes (q=%d) via %s',
        $id, $info['format'], $info['converted'], $info['quality'], $info['mode']
    ) );
}, 10, 2 );

Example: trigger a webhook

php

add_action( 'tempaloo_webp_after_convert', function( $id, $info ) {
    if ( $info['mode'] !== 'bulk' ) return;            // only batch webhooks
    wp_remote_post( 'https://hooks.example.com/tempaloo', [
        'body' => wp_json_encode( [
            'site' => home_url(),
            'attachment_id' => $id,
            'format'        => $info['format'],
            'sizes'         => $info['converted'],
        ] ),
        'blocking' => false,                            // fire-and-forget
    ] );
}, 10, 2 );

Don't slow the upload

The action fires synchronously on upload — heavy work (large HTTP calls, blocking I/O) will delay the user's upload response. Use'blocking' => false on outbound HTTP, or queue a background job.

What's NOT a hook (yet)

If you need any of these, open an issue — the more we hear them, the faster they ship:

tempaloo_webp_before_convert — pre-flight modify image bytes
tempaloo_webp_convert_failed — react to errors specifically
tempaloo_webp_alternate_url — customize how the .webp URL is computed