Actions and filters for developers

2 min read · Last updated June 2026

SlashImage exposes WordPress hooks so you can customize its behavior from a small plugin or your child theme's functions.php. Filters change a value before SlashImage uses it; actions let you react to something it did. For no-code image skipping, use Custom exclusions instead.

Filters

The first argument in each signature is the default value your filter receives.

slash_image_should_optimize

php
apply_filters( 'slash_image_should_optimize', true, $attachment_id, $metadata )

Runs once per attachment before optimization. Return false to skip it. Default true.

slash_image_should_skip_attachment

php
apply_filters( 'slash_image_should_skip_attachment', false, $attachment_id, $filename, $url )

The custom-exclusion gate. Return true to skip, or a non-empty string to skip and show it as the matched pattern. Runs after the Custom exclusions patterns. Default false.

slash_image_skip_image

php
apply_filters( 'slash_image_skip_image', false, $img_html, $src )

Runs in the frontend rewriter, once per <img> it considers. Return true to leave that image's HTML untouched. Default false.

slash_image_optimize_timeout

php
apply_filters( 'slash_image_optimize_timeout', 45 )

Per-request API timeout in seconds. Default 45.

slash_image_stream_upload

php
apply_filters( 'slash_image_stream_upload', null )

Force or disable streaming the upload to the API. Return true to force, false to disable, or null to auto-pick. Default null.

slash_image_concurrency

php
apply_filters( 'slash_image_concurrency', 5 )

Images processed per worker tick. Default 5, clamped to at least 1.

slash_image_bulk_enqueue_chunk_size

php
apply_filters( 'slash_image_bulk_enqueue_chunk_size', 500 )

Attachment IDs pulled per feed query during a bulk run. Default 500, clamped to at least 50.

slash_image_stall_threshold

php
apply_filters( 'slash_image_stall_threshold', 600 )

Seconds before a queue row is treated as stalled. Default 600, clamped to at least 60.

slash_image_stale_claim_timeout

php
apply_filters( 'slash_image_stale_claim_timeout', 180 )

Seconds before a claimed row is reaped and freed for another worker. Default 180, clamped to at least 30.

slash_image_queue_retention_days_done

php
apply_filters( 'slash_image_queue_retention_days_done', 30 )

Days completed queue rows are kept before they are purged. Default 30, clamped to at least 1.

slash_image_queue_retention_days_failed

php
apply_filters( 'slash_image_queue_retention_days_failed', 90 )

Days failed queue rows are kept before they are purged. Default 90, clamped to at least 1.

Actions

slash_image_pre_replace_original

php
do_action( 'slash_image_pre_replace_original', $attachment_id, $size_key, $full_path )

Fires before a file is overwritten with its optimized version. SlashImage's own backup feature uses this to copy the original aside first.

slash_image_replaced_original

php
do_action( 'slash_image_replaced_original', $attachment_id, $size_key, $original_path )

Fires after the optimized file has been moved into place.

slash_image_attachment_processed

php
do_action( 'slash_image_attachment_processed', $attachment_id, $data_meta )

Fires once per attachment after it is optimized successfully.

Example

Skip every attachment uploaded by user 5, and raise the API timeout to 90 seconds:

php
add_filter( 'slash_image_should_skip_attachment', function ( $skip, $id, $filename, $url ) {
	return ( 5 === (int) get_post_field( 'post_author', $id ) ) ? true : $skip;
}, 10, 4 );
 
add_filter( 'slash_image_optimize_timeout', function () {
	return 90;
} );

See also

Was this helpful?