Developer Reference

Theme authors: design values can be handed over via add_theme_support( 'image-socialiser', [ … ] ). see For Theme Authors for the full key reference.

Available interfaces of Image Socialiser: hooks, options, post meta, and WP-CLI commands. Everything here is considered stable API within a major version.

Filters

Rendering & templates

Filter	Signature	Purpose
image_socialiser_renderers	( Renderer[] $renderers )	Renderer instances in priority order; the first available one is used. Default: Imagick, GD.
image_socialiser_fonts	( array<string, string> $fonts )	Font identifier → absolute TTF/OTF path. Register additional fonts here.
image_socialiser_font_urls	( array<string, string> $urls )	Font identifier → public URL, used by the editor's browser preview. Needed for fonts outside the plugin directory.
image_socialiser_default_template	( array $template )	The default template definition (layer stack) before it is parsed.
image_socialiser_templates	( array<string, array> $templates )	All registered templates as arrays, keyed by identifier. Add designs here; they appear in the editor and settings selectors. Template arrays support optional label (localized name), supports (honored features), and pins (tokens fixed by design) keys. Layer capabilities (since 0.17.0): rect layers take an optional stroke ({ color, width }, centered on the box edge) and accept fill: 'none' for outlined frames; text layers take an optional backing ({ color, padding_x, padding_y, radius, opacity }) for content-fitted per-line panels; image layers take an optional frame ({ color, offset }) for an offset "sticker" rect behind the image, and the template_asset source with asset_path (server file) and asset_url (editor preview) on the layer to ship your own background/texture files.
image_socialiser_pack_image_sources	( string[] $sources )	Image source identifiers design packs may reference (default: featured, logo, cover_art, brand_background, template_asset). Extend when binding additional sources.
image_socialiser_default_template_id	( string $template_id )	The identifier of the site-wide default template (default: editorial). The stored value default and the empty value alias this.
image_socialiser_template_for_post	( string $template_id, WP_Post $post )	The template identifier resolved for a post (after meta and per-type settings).
image_socialiser_brand_tokens	( array $tokens )	The sanitized brand tokens (colors, fonts, tri-state logo, cover art, background image).
image_socialiser_layout_tokens	( array $tokens )	The sanitized layout tokens (element toggles, corner positions, text alignment).
image_socialiser_content_tokens	( array $tokens )	The sanitized content tokens (secondary line source).

Data binding

Filter	Signature	Purpose
image_socialiser_binding_text	( string $value, string $source, ?WP_Post $post, Subject $subject )	Resolved text for a template source. Bind arbitrary sources (e.g. post meta tokens) here. Since 0.14.0: $post is null for non-post subjects (terms, archives, special pages) — type-hint callbacks as ?WP_Post; the Subject tells you what is being rendered.
image_socialiser_binding_image_path	( string $path, string $source, ?WP_Post $post, Subject $subject )	Resolved absolute file path for an image source. Same nullable-post contract as above.

Generation & storage

Filter	Signature	Purpose
image_socialiser_supported_post_types	( string[] $post_types )	Post types that get generated images (after the settings option).
image_socialiser_supported_post_statuses	( string[] $statuses )	Post statuses that trigger generation. Default: publish, future.
image_socialiser_directory_name	( string $name )	Name of the storage subdirectory inside uploads. Default: og-images.

Output

Filter	Signature	Purpose
image_socialiser_subject_title	( string $title, Subject $subject )	The title of a non-post subject (term name, archive label, site title, localized "Search"/"Page not found"). A custom title set in Special Pages & Archives takes precedence before this filter runs.
image_socialiser_subject_subtitle	( string $subtitle, Subject $subject )	The secondary line of a non-post subject (term description, site tagline, or empty for search/404). A custom subtitle set in Special Pages & Archives takes precedence before this filter runs.
image_socialiser_resolved_subject_image	( ?array $image, Subject $subject )	The resolved og:image data for a non-post subject; also the last step of its fallback chain. Not applied for disabled subjects (they emit nothing, or only a manual term override).
image_socialiser_resolved_image	( ?array $image, WP_Post $post )	The resolved og:image data (url, width, height, type) after the fallback chain. Return data here for a hard-coded last fallback.
image_socialiser_seo_adapters	( Seo_Adapter[] $adapters )	SEO adapter instances in priority order; the first active one is registered — order = precedence. Built-in ids: the-seo-framework, rank-math, yoast, aioseo (AIOSEO 4.x only), seopress, native (always last).
image_socialiser_native_mode_blockers	( string[] $constants )	Constants that indicate an SEO plugin handling og:image itself, disabling native mode.
image_socialiser_oembed_thumbnail	( bool $enabled, WP_Post $post )	Whether the generated image overrides the oEmbed thumbnail (default true). Note: embed consumers cache oEmbed responses — a regenerated image appears only when the consumer re-fetches.
image_socialiser_print_native_tags	( bool $print )	Whether native mode prints its tags on the current view. Defaults to false on views covered by another plugin's Open Graph block (e.g. Podlove episodes).

Actions

Action	Signature	Fired
image_socialiser_register_designs	()	On init — the canonical hook to register design packs from.
image_socialiser_generated	( int $post_id, string $hash )	After a POST image was successfully generated and stored (kept for backward compatibility).
image_socialiser_generated_subject	( Subject $subject, string $hash )	After an image was generated for any subject — posts, terms, archives, special pages.

Internal queue hooks (image_socialiser_generate, image_socialiser_bulk_regenerate, image_socialiser_generate_term, image_socialiser_bulk_terms, image_socialiser_generate_contexts, image_socialiser_network_bulk, image_socialiser_sweep_orphans) are implementation detail — schedule against them at your own risk. Since 0.14.0, updating the active theme automatically schedules regeneration when the theme declares image-socialiser support.

Functions

Function	Signature	Purpose
image_socialiser_register_design	( string $manifest_path ): string|WP_Error	Register a design pack from its design.json manifest. See docs/creating-designs.md.
image_socialiser_register_design_collection	( string $index_json_path ): array	Register several packs listed in one index.json (array of relative manifest paths).

Options

Option	Content
image_socialiser_brand	Brand tokens: gradient/text/muted colors, heading_font, body_font, logo ({mode: auto|custom|none, id}), cover_art_id, background_id. Saving queues full regeneration.
image_socialiser_layout	Layout tokens: show_site_name, show_logo, site_name_position, logo_position (four corners), text_align.
image_socialiser_content	Content tokens: subtitle_source (none/tagline/excerpt/category).
image_socialiser_post_types	Enabled post types (array of names). Absent = all public types.
image_socialiser_cpt_templates	Per-post-type default template (post type → template identifier).
image_socialiser_fallbacks	Fallback image attachment IDs (post type → ID, _default for the site-wide fallback).
image_socialiser_network_brand / _layout / _content / _post_types / _fallbacks / _custom_fonts	Network options (multisite): network-wide defaults per section, managed on the network settings page.
image_socialiser_network_permissions	Per-section override permissions (section => 'site'|'network'). Locked (network) sections always use network values and ignore theme support.
image_socialiser_context	Context image settings: enabled taxonomies, per-taxonomy templates, special page toggles + templates.
image_socialiser_state_{slug}	Per-subject generation state for archive and special page subjects (front, blog, search, 404, archive-{post_type}), autoload disabled. Terms use term meta, posts post meta. The pre-0.14.0 shared map (image_socialiser_context_state) is migrated automatically.
image_socialiser_custom_fonts	Index of uploaded fonts (id => { file, label }); files live in uploads/og-images/fonts/. Managed through the settings screen (admin-post actions image_socialiser_upload_font / image_socialiser_delete_font).
image_socialiser_design_overrides	Per-design token overrides (template id → partial brand tokens). Site-level; not applied while the brand section is network-locked.
image_socialiser_design_version	Integer, manual invalidation escape hatch. Since 0.8.0 the content hash covers the full resolved design (template array, bound texts and image IDs, font file hashes), so design changes from any source invalidate automatically.

Parsed design-pack manifests are cached in image_socialiser_pack_{hash} transients, keyed by manifest path and invalidated by file modification time and plugin version.

Post meta

Key	Written by	Content
_image_socialiser_title	Editor panel	Custom image title (falls back to the post title).
_image_socialiser_subtitle	Editor panel	Custom secondary line (falls back to the site-wide source).
_image_socialiser_override_id	Editor panel	Manual image override (attachment ID); wins over the generated image.
_image_socialiser_status	Generator	pending / ready / failed.
_image_socialiser_hash	Generator	Content hash of the current image.
_image_socialiser_error	Generator	Last error message when failed.

REST endpoints

Namespace image-socialiser/v1, both gated by edit_post:

• POST /regenerate/<id> — regenerates synchronously, returns the status payload.
• GET /status/<id> — returns status, hash, url, error.

WP-CLI

wp image-socialiser render <post_id>                          # render one post, verbose
wp image-socialiser regenerate [<post_id>...] [--all] [--post_type=<type>]
wp image-socialiser sweep                                     # delete orphaned files
wp image-socialiser scaffold-design <id> [--dir=<path>]      # starter design pack

Fallback chain

When emitting og:image, the first hit wins:

1. per-post manual override (_image_socialiser_override_id)
2. generated image (status ready, file present)
3. per-post-type fallback image (settings)
4. site-wide fallback image (settings)
5. image_socialiser_resolved_image filter