Hooks: Actions & Filters

Every action and filter the plugin fires, what it's for, and the ones you probably want.

All hooks are prefixed shaped_gallery_. Add them from a plugin or your theme's functions.php unless a hook's note says otherwise.

Actions

Hook	Fires when	Arguments
shaped_gallery_register_providers	Media providers are being registered. The seam for adding your own media source.	$registry — the provider registry class name
shaped_gallery_integrations_loaded	Page-builder integrations have booted. The seam for registering an integration of your own.	$builders — the key → class map
shaped_gallery_flush_cache	Between invalidating and reclaiming, during Clear Gallery Cache.	—
shaped_gallery_watermark_generated	A watermarked derivative has been written.	Details of the generated file
shaped_gallery_watermark_failed	A derivative could not be generated.	The failure details
shaped_gallery_watermark_purged	Purge Watermark Cache has run.	What was removed
shaped_gallery_watermark_signature_changed	The watermark configuration changed, making existing derivatives unreachable.	—
shaped_gallery_debug_note	A note or counter was recorded while Debug Performance is on. The seam for contributing your own line.	The note

Filters

Rendering and layout

Hook	What it filters
shaped_gallery_style_contributors	The ordered list of CSS contributors. The only supported way to add a style the plugin emits — a contributor returns CSS custom properties; there's no raw-CSS escape hatch.
shaped_gallery_image_sizes	The sizes hint used for responsive images.
shaped_gallery_item_categories	An item's category memberships, before filtering. The seam for sourcing memberships from elsewhere — a taxonomy, a provider album — allow-listed against the gallery's own vocabulary.
shaped_gallery_shortcode_output	The rendered output of [shaped_gallery].

Caching

Hook	What it filters	Note
shaped_gallery_cache_ttl	The plugin's cache lifetime, in seconds.	Floored at one hour — returning 0 would make entries permanent.
shaped_gallery_ajax_context_ttl	The lifetime of one gallery's Ajax render context.	Wraps the value above and wins.
shaped_gallery_browser_caching	Whether browser caching is on.	Mirrors the Advanced Controls setting.
shaped_gallery_retina_images	Whether responsive candidates are emitted.	Mirrors the Advanced Controls setting.

Licensing

Hook	What it filters
shaped_gallery_license_required	Whether front-end output is gated on a valid license. Return false to disable enforcement — for a migration, an air-gapped install, or a support session.
shaped_gallery_license_notice	The administrator notice shown when the license isn't active.
shaped_gallery_license_site_url	The site URL sent to the store when activating. Useful for staging environments.
shaped_gallery_license_updater_enabled	Whether the update checker registers its hooks.

Watermark

Hook	What it filters
shaped_gallery_watermark_lazy	Whether derivatives are generated on first request (the default) or synchronously during render. Returning false is the only sanctioned way a render composites.
shaped_gallery_watermark_backend	Which image backend is used — ImageMagick or GD.
shaped_gallery_watermark_geometry	The computed placement of every mark before it's drawn.
shaped_gallery_watermark_slots	Which item fields (url, full, thumb) get a derivative, and at which registered size.
shaped_gallery_watermark_alpha	The mark's alpha.
shaped_gallery_watermark_max_pixels	The ceiling on image size the composer will attempt.
shaped_gallery_watermark_skip_attachment	Return true to exclude an attachment from watermarking.
shaped_gallery_watermark_font_path	The TrueType font used for a text watermark.
shaped_gallery_watermark_dirname	The folder derivatives are written to, inside uploads.
shaped_gallery_watermark_endpoint_url	The URL that generates a cold derivative.
shaped_gallery_watermark_cache_headers	The cache headers on a served derivative.
shaped_gallery_watermark_signature_salt	Extra input to the cache signature. Changing it invalidates every derivative.

Editor and admin

Hook	What it filters
shaped_gallery_editor_allowed_blocks	Which blocks may be inserted on the gallery post type. Defaults to the gallery block alone.
shaped_gallery_block_starter_post_type	The post type the dashboard's Create New Gallery button opens.
shaped_gallery_dashboard_config	The whole dashboard payload — every label, link and section. Anything a filter changes is re-validated before it ships.
shaped_gallery_dashboard_routes	The dashboard's route map.
shaped_gallery_dashboard_hide_notices	Whether other plugins' admin notices are suppressed on the dashboard.

Ready Patterns and lightbox

Hook	What it filters
shaped_gallery_patterns_provider_base	The base URL the pattern catalogue is fetched from.
shaped_gallery_lightbox_slideshow_interval	How long the lightbox slideshow holds each slide.

Bootstrap

Hook	What it filters	Note
shaped_gallery_pro_free_basename	The free plugin's basename that Pro checks for.	Must be added from an mu-plugin. It runs while WordPress is still including plugin files, long before plugins_loaded.

Examples

Turn off license enforcement temporarily

add_filter( 'shaped_gallery_license_required', '__return_false' );

Useful during a migration or on a staging copy. Remove it when you're done.

Exclude some images from watermarking

add_filter(
    'shaped_gallery_watermark_skip_attachment',
    function ( $skip, $attachment_id ) {
        // Never watermark anything tagged as a logo.
        return has_term( 'logo', 'media_tag', $attachment_id ) ? true : $skip;
    },
    10,
    2
);

Lengthen the cache lifetime on a low-traffic site

add_filter(
    'shaped_gallery_cache_ttl',
    function () {
        return WEEK_IN_SECONDS;
    }
);

The value is floored at one hour, so you can't accidentally make entries permanent.

Add a line to the debug output

add_action(
    'shaped_gallery_debug_note',
    function ( $note ) {
        error_log( 'Shaped Gallery: ' . wp_json_encode( $note ) );
    }
);

Nothing is collected at all while Debug Performance is off, so this costs nothing in production.

Things worth knowing

There's no raw-CSS hook, deliberately. Every style the plugin emits derives from a setting. To add one, register a contributor via shaped_gallery_style_contributors that returns CSS custom properties. The site-wide and per-gallery CSS fields that used to exist were both removed. Why →

Unprefixed constants are aliases. SHAPED_GALLERY_* point at whichever build booted, so code that reads them works under free or Pro without a change. Pro's own identity is SHAPED_GALLERY_PRO_*.

Identifiers never change. The namespace, the shaped_gallery post type, the shaped-gallery/gallery block, the shaped_gallery_settings option, the shaped-gallery/v1 REST namespace and the [shaped_gallery] shortcode are fixed. Stored galleries depend on them.

Where to go next

• Media Providers — adding a media source
• REST API · Shortcode · Block Attributes