Embed
extends Abstract_Block_Renderer
in package
Embed block renderer.
This renderer handles core/embed blocks, detecting audio and video provider embeds and rendering them appropriately.
Audio providers: Spotify, SoundCloud, Pocket Casts, Mixcloud, ReverbNation - rendered as audio players. Video providers: YouTube - rendered as video thumbnails with play buttons.
Table of Contents
- AUDIO_PROVIDERS = array('pocket-casts' => array('domains' => array('pca.st'), 'base_url' => 'https://pca.st/'), 'spotify' => array('domains' => array('open.spotify.com'), 'base_url' => 'https://open.spotify.com/'), 'soundcloud' => array('domains' => array('soundcloud.com'), 'base_url' => 'https://soundcloud.com/'), 'mixcloud' => array('domains' => array('mixcloud.com'), 'base_url' => 'https://www.mixcloud.com/'), 'reverbnation' => array('domains' => array('reverbnation.com'), 'base_url' => 'https://www.reverbnation.com/'))
- Supported audio providers with their configuration.
- MAX_EMBED_FETCHES = 5
- Maximum number of embed page fetch attempts per email render.
- VIDEO_PROVIDERS = array('youtube' => array('domains' => array('youtube.com', 'youtu.be'), 'base_url' => 'https://www.youtube.com/'), 'videopress' => array('domains' => array('videopress.com', 'video.wordpress.com'), 'base_url' => 'https://videopress.com/'))
- Supported video providers with their configuration.
- $embed_fetch_count : int
- Number of embed page fetch attempts so far by this instance.
- render() : string
- Renders the embed block.
- add_spacer() : string
- Add a spacer around the block for vertical spacing (margin-top).
- compile_css() : string
- Compile objects containing CSS properties to a string.
- get_inner_content() : string
- Extract inner content from a wrapper element.
- get_styles_from_block() : array<string|int, mixed>
- Wrapper for wp_style_engine_get_styles which ensures all values are returned.
- render_content() : string
- Renders the embed block content.
- create_fallback_attributes() : array<string|int, mixed>
- Create fallback attributes for link rendering.
- detect_provider_from_domains() : string
- Detect provider from content by checking against known domains.
- extract_provider_url() : string
- Extract provider URL from block attributes or content.
- extract_url_from_content() : string
- Extract URL from block content using DOM parsing.
- fetch_embed_page_data() : array{title: string, thumbnail_url: string, provider_name: string, provider_url: string, excerpt: string, site_icon_url: string}
- Fetch metadata from a WordPress embed page.
- get_all_provider_configs() : array<string|int, mixed>
- Get all provider configurations (audio and video).
- get_all_supported_providers() : array<string|int, mixed>
- Get all supported providers (audio and video).
- get_provider_base_url() : string
- Get base URL for a provider when specific URL extraction fails.
- get_provider_label() : string
- Get appropriate label for the provider.
- get_supported_provider() : string
- Get supported audio or video provider from block attributes or content.
- get_translated_provider_label() : string
- Get translated label for a provider.
- get_video_thumbnail_url() : string
- Get video thumbnail URL for supported providers.
- get_videopress_thumbnail() : string
- Extract VideoPress video thumbnail URL.
- get_youtube_thumbnail() : string
- Extract YouTube video thumbnail URL.
- is_valid_url() : bool
- Validate URL using both filter_var and wp_http_validate_url.
- is_video_provider() : bool
- Check if a provider is a video provider.
- render_compact_link_card() : string
- Render a compact link card for embeds that exceed the rich card cap.
- render_link_embed_card() : string
- Render a link embed as a rich card using data from the WordPress embed page.
- render_link_fallback() : string
- Render a simple link fallback for non-supported embeds.
- render_video_embed() : string
- Render a video embed using the Video renderer.
- url_matches_provider() : bool
- Validate that a URL's host matches the expected provider's domains.
Constants
AUDIO_PROVIDERS
Supported audio providers with their configuration.
private
array<string|int, mixed>
AUDIO_PROVIDERS
= array('pocket-casts' => array('domains' => array('pca.st'), 'base_url' => 'https://pca.st/'), 'spotify' => array('domains' => array('open.spotify.com'), 'base_url' => 'https://open.spotify.com/'), 'soundcloud' => array('domains' => array('soundcloud.com'), 'base_url' => 'https://soundcloud.com/'), 'mixcloud' => array('domains' => array('mixcloud.com'), 'base_url' => 'https://www.mixcloud.com/'), 'reverbnation' => array('domains' => array('reverbnation.com'), 'base_url' => 'https://www.reverbnation.com/'))
MAX_EMBED_FETCHES
Maximum number of embed page fetch attempts per email render.
private
mixed
MAX_EMBED_FETCHES
= 5
Beyond this limit, embeds render as compact link cards (no HTTP fetch). Counts attempts, not successes, to cap outbound HTTP requests.
VIDEO_PROVIDERS
Supported video providers with their configuration.
private
array<string|int, mixed>
VIDEO_PROVIDERS
= array('youtube' => array('domains' => array('youtube.com', 'youtu.be'), 'base_url' => 'https://www.youtube.com/'), 'videopress' => array('domains' => array('videopress.com', 'video.wordpress.com'), 'base_url' => 'https://videopress.com/'))
Properties
$embed_fetch_count
Number of embed page fetch attempts so far by this instance.
private
int
$embed_fetch_count
= 0
Methods
render()
Renders the embed block.
public
render(string $block_content, array<string|int, mixed> $parsed_block, Rendering_Context $rendering_context) : string
Parameters
- $block_content : string
-
Block content.
- $parsed_block : array<string|int, mixed>
-
Parsed block.
- $rendering_context : Rendering_Context
-
Rendering context.
Return values
string —add_spacer()
Add a spacer around the block for vertical spacing (margin-top).
protected
add_spacer(string $content, array<string|int, mixed> $email_attrs) : string
Horizontal root padding is applied uniformly by Content_Renderer::render_block() so that all blocks — including those using render_email_callback without Abstract_Block_Renderer — receive consistent padding.
Parameters
- $content : string
-
The block content.
- $email_attrs : array<string|int, mixed>
-
The email attributes.
Return values
string —compile_css()
Compile objects containing CSS properties to a string.
protected
compile_css(array<string|int, mixed> ...$styles) : string
Parameters
- $styles : array<string|int, mixed>
-
Style arrays to compile.
Return values
string —get_inner_content()
Extract inner content from a wrapper element.
protected
get_inner_content(string $block_content[, string $tag_name = 'div' ]) : string
Removes the outer wrapper element (e.g., div) and returns only the inner HTML content. This is useful when you need to strip the wrapper and use only the inner content.
Parameters
- $block_content : string
-
Block content with wrapper element.
- $tag_name : string = 'div'
-
Tag name of the wrapper element (default: 'div').
Return values
string — Inner content without the wrapper element, or original content if wrapper not found.get_styles_from_block()
Wrapper for wp_style_engine_get_styles which ensures all values are returned.
protected
get_styles_from_block(array<string|int, mixed> $block_styles[, bool $skip_convert_vars = false ]) : array<string|int, mixed>
Parameters
- $block_styles : array<string|int, mixed>
-
Array of block styles.
- $skip_convert_vars : bool = false
-
If true, --wp_preset--spacing--x type values will be left in the original var:preset:spacing:x format.
Return values
array<string|int, mixed> —render_content()
Renders the embed block content.
protected
render_content(string $block_content, array<string|int, mixed> $parsed_block, Rendering_Context $rendering_context) : string
Parameters
- $block_content : string
-
Block content.
- $parsed_block : array<string|int, mixed>
-
Parsed block.
- $rendering_context : Rendering_Context
-
Rendering context (required by parent contract but unused in this implementation).
Return values
string —create_fallback_attributes()
Create fallback attributes for link rendering.
private
create_fallback_attributes(string $url, string $label) : array<string|int, mixed>
Parameters
- $url : string
-
URL for the fallback.
- $label : string
-
Label for the fallback.
Return values
array<string|int, mixed> — Fallback attributes.detect_provider_from_domains()
Detect provider from content by checking against known domains.
private
detect_provider_from_domains(string $content) : string
Parameters
- $content : string
-
Content to check for provider domains.
Return values
string — Provider name or empty string if not found.extract_provider_url()
Extract provider URL from block attributes or content.
private
extract_provider_url(array<string|int, mixed> $attr, string $block_content) : string
Parameters
- $attr : array<string|int, mixed>
-
Block attributes.
- $block_content : string
-
Block content.
Return values
string — Provider URL or empty string.extract_url_from_content()
Extract URL from block content using DOM parsing.
private
extract_url_from_content(string $block_content) : string
Parameters
- $block_content : string
-
Block content HTML.
Return values
string — Extracted URL or empty string.fetch_embed_page_data()
Fetch metadata from a WordPress embed page.
private
fetch_embed_page_data(string $url) : array{title: string, thumbnail_url: string, provider_name: string, provider_url: string, excerpt: string, site_icon_url: string}
WordPress sites expose a {url}/embed/ endpoint that renders a post preview containing the title, excerpt, featured image, provider name, and site icon. This single fetch provides all the data needed for the rich embed card.
Parameters
- $url : string
-
URL of the post to fetch metadata for.
Return values
array{title: string, thumbnail_url: string, provider_name: string, provider_url: string, excerpt: string, site_icon_url: string} — Embed page metadata.get_all_provider_configs()
Get all provider configurations (audio and video).
private
get_all_provider_configs() : array<string|int, mixed>
Return values
array<string|int, mixed> — All provider configurations.get_all_supported_providers()
Get all supported providers (audio and video).
private
get_all_supported_providers() : array<string|int, mixed>
Return values
array<string|int, mixed> — All supported providers.get_provider_base_url()
Get base URL for a provider when specific URL extraction fails.
private
get_provider_base_url(string $provider) : string
Parameters
- $provider : string
-
Provider name.
Return values
string — Base URL for the provider or empty string.get_provider_label()
Get appropriate label for the provider.
private
get_provider_label(string $provider, array<string|int, mixed> $attr) : string
Parameters
- $provider : string
-
Provider name.
- $attr : array<string|int, mixed>
-
Block attributes.
Return values
string — Label for the provider.get_supported_provider()
Get supported audio or video provider from block attributes or content.
private
get_supported_provider(array<string|int, mixed> $attr, string $block_content) : string
Parameters
- $attr : array<string|int, mixed>
-
Block attributes.
- $block_content : string
-
Block content.
Return values
string — Provider name or empty string if not supported.get_translated_provider_label()
Get translated label for a provider.
private
get_translated_provider_label(string $provider) : string
Parameters
- $provider : string
-
Provider name.
Return values
string — Translated label for the provider.get_video_thumbnail_url()
Get video thumbnail URL for supported providers.
private
get_video_thumbnail_url(string $url, string $provider) : string
Parameters
- $url : string
-
Video URL.
- $provider : string
-
Provider name.
Return values
string — Thumbnail URL or empty string.get_videopress_thumbnail()
Extract VideoPress video thumbnail URL.
private
get_videopress_thumbnail(string $url) : string
Uses WordPress oEmbed API to get thumbnail_url from the provider response. Results are cached using transients to avoid repeated HTTP requests.
Note: URL validation against VideoPress domains is done in render_video_embed() via url_matches_provider() before this method is called.
Parameters
- $url : string
-
VideoPress video URL (pre-validated by caller).
Return values
string — Thumbnail URL or empty string.get_youtube_thumbnail()
Extract YouTube video thumbnail URL.
private
get_youtube_thumbnail(string $url) : string
Parameters
- $url : string
-
YouTube video URL.
Return values
string — Thumbnail URL or empty string.is_valid_url()
Validate URL using both filter_var and wp_http_validate_url.
private
is_valid_url(string $url) : bool
Parameters
- $url : string
-
URL to validate.
Return values
bool — True if URL is valid.is_video_provider()
Check if a provider is a video provider.
private
is_video_provider(string $provider) : bool
Parameters
- $provider : string
-
Provider name.
Return values
bool — True if video provider.render_compact_link_card()
Render a compact link card for embeds that exceed the rich card cap.
private
render_compact_link_card(string $url, array<string|int, mixed> $parsed_block, Rendering_Context $rendering_context) : string
Displays the URL in a bordered card without making any HTTP requests.
Parameters
- $url : string
-
URL to render.
- $parsed_block : array<string|int, mixed>
-
Parsed block.
- $rendering_context : Rendering_Context
-
Rendering context.
Return values
string — Rendered compact link card HTML.render_link_embed_card()
Render a link embed as a rich card using data from the WordPress embed page.
private
render_link_embed_card(string $url, array<string|int, mixed> $parsed_block, Rendering_Context $rendering_context) : string
Parameters
- $url : string
-
URL to render as a card.
- $parsed_block : array<string|int, mixed>
-
Parsed block.
- $rendering_context : Rendering_Context
-
Rendering context.
Return values
string — Rendered card HTML or empty string if embed page data is insufficient.render_link_fallback()
Render a simple link fallback for non-supported embeds.
private
render_link_fallback(array<string|int, mixed> $attr, string $block_content, array<string|int, mixed> $parsed_block, Rendering_Context $rendering_context) : string
Parameters
- $attr : array<string|int, mixed>
-
Block attributes.
- $block_content : string
-
Block content.
- $parsed_block : array<string|int, mixed>
-
Parsed block.
- $rendering_context : Rendering_Context
-
Rendering context.
Return values
string — Rendered link or empty string if no valid URL.render_video_embed()
Render a video embed using the Video renderer.
private
render_video_embed(string $url, string $provider, array<string|int, mixed> $parsed_block, Rendering_Context $rendering_context, string $block_content) : string
Parameters
- $url : string
-
URL of the video.
- $provider : string
-
Provider name.
- $parsed_block : array<string|int, mixed>
-
Parsed block.
- $rendering_context : Rendering_Context
-
Rendering context.
- $block_content : string
-
Original block content.
Return values
string — Rendered video embed or fallback.url_matches_provider()
Validate that a URL's host matches the expected provider's domains.
private
url_matches_provider(string $url, string $provider) : bool
This prevents SSRF when provider is set via user-controlled attributes.
Parameters
- $url : string
-
URL to validate.
- $provider : string
-
Provider name.