Documentation – Embed Privacy

This documentation is mainly limited to any development related content regarding Embed Privacy with some exceptions. Please use the support forums for general questions.

Regex pattern

The regex pattern, which can be set for any embed provider, defines a regular expression to match the content, which should be replaced by Embed Privacy’s overlay. For the default embed providers, it’s sufficient to only match a part of the URL.

If you want to add custom embed providers, the best way is to match the full element’s HTML tag as well:

Don’t use such regular expression

/sub\.example\.com/Code language: plaintext (plaintext)

Do use such regular expression

/<iframe src="(.*)sub\.example\.com([^"]*)"><\/iframe>/Code language: plaintext (plaintext)

However, since version 1.6.0, any regex not containing a < and > will be extended with a variety of HTML tags to check for. So the regular expression /sub\.example\.com/ will become:

/<(blockquote|div|embed|iframe|object)([^"]*)"([^<]*)sub\.example\.com([^"]*)"([^>]*)(>(.*)<\/(blockquote|div|embed|iframe|object))?>/Code language: plaintext (plaintext)

You can filter the tags extending the regular expression with the filter embed_privacy_replacer_matcher_elements.

The beginning end ending / in the regex pattern are optional and automatically added in the code if not available.

Using Embed Privacy in a plugin

If you want to use Embed Privacy in a plugin for your custom code, the best way is to use the method epiphyt\Embed_Privacy\data\Replacer::replace_embeds() directly.

You can pass the content to search for replacements and as a result, you will get the content with all embeds replaced.

If you need more control over the replacement, e.g. the used embed provider, you can use the filter embed_privacy_overlay_provider to filter the actual provider for this content.

Alternate method

If an embedded content should be

If an embedded content must be replaced, the following method also works:

\add_filter( 'embed_privacy_has_embed', '__return_true' );
Embed_Privacy::get_instance()->frontend->print_assets();
echo Template::get( $provider, $embed ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
Code language: PHP (php)

A prior query as to whether the embed provider is always active must also be added.

Custom thumbnail provider

Embed Privacy implemented an easy usable method to create custom thumbnail providers starting with version 1.9.0. To implement a custom thumbnail provider, extend the abstract class epiphyt\Embed_Privacy\thumbnail\provider\Thumbnail_Provider and implement the interface epiphyt\Embed_Privacy\thumbnail\provider\Thumbnail_Provider_Interface. (See also this blog post for more information regarding the abstract class and interface.)

In it, you just need to define how to get the thumbnail and the according embed ID. You can find a basic implementation for Vimeo on GitHub.

Then, use the filter embed_privacy_thumbnail_providers to register your custom thumbnail provider.

Filters

embed_privacy_integrations since 1.10.0

Through the filter embed_privacy_integrations the available integrations can be changed before their initialization.

Parameters:
array $integrations List of integrations

Expects an array.

embed_privacy_content deprecated 1.10.0

Through the filter embed_privacy_content the embed overlay content can be changed.

Deprecated since 1.10.0, use embed_privacy_template_content instead.

Parameters:
string $content The content
string $embed_provider The embed provider of this embed

Expects a string.

Through the filter embed_privacy_overlay_footer the footer of the embed overlay container can be changed.

Parameters:
string $footer_content The footer content

Expects a string.

embed_privacy_markup deprecated 1.10.0

Through the filter embed_privacy_markup the whole embed overlay container can be changed.

Deprecated since 1.10.0, use embed_privacy_template_markup instead.

Parameters:
string $markup The markup
string $embed_provider The embed provider of this embed

Expects a string.

embed_privacy_has_embed since 1.3.0

Through the filter embed_privacy_has_embed the return value of Embed_Privacy::has_embed() can be overridden.

Parameters:
null $has_embed The default value

Expects anything other than null.

embed_privacy_provider_list since 1.10.0

Through the filter embed_privacy_provider_list the list of providers for a specific identifier can be filtered.

Parameters:
array $provider_list Current provider list
string $identifier Current identifier
array $global_list List with all providers of all identifiers

Expects an array.

embed_privacy_provider_name since 1.10.0

Through the filter embed_privacy_provider_name the name of an embed provider can be filtered.

Parameters:
string $name Embed provider name
string $provider Embed provider

Expects a string.

embed_privacy_overlay_provider since 1.10.0

Through the filter embed_privacy_overlay_provider the current embed provider can be filtered.

Parameters:
\epiphyt\Embed_Privacy\embed\Provider $provider Current provider
string $content Content to get the provider from
string $url URL to the embedded content

Expects an object of type \epiphyt\Embed_Privacy\embed\Provider.

embed_privacy_print_assets since 1.10.0

The action embed_privacy_print_assets fires after the assets have been printed.

embed_privacy_register_assets since 1.10.0

The action embed_privacy_register_assets fires after the assets have been registered.

Parameters:
bool $is_debug Whether debug mode is enabled
string $suffix A filename suffix

embed_privacy_assets_$embed_provider_lowercase since 1.4.5

Through the filter embed_privacy_assets_$embed_provider_lowercase additional assets that are necessary to get an embed working can be printed.

Each asset must be an array with at least a type parameter, which is either set to script for script elements or inline for an inline script.

If the type is set to script, the parameters handle and src are required, which are similar to identical parameters in wp_enqueue_script. Additionally, a parameter version can be added.

If the type is set to inline, the parameters data and object_name are required, which are similar to identical parameters in wp_add_inline_script.

Parameters:
array $assets List of embed assets
string $embed_provider_lowercase The current embed provider in lowercase

Expects an array with arrays.

embed_privacy_overlay_args since 1.9.0 deprecated 1.10.0

Through the filter embed_privacy_overlay_args the arguments before creating an overlay can be changed.

Deprecated since 1.10.0, use embed_privacy_template_attributes instead.

Parameters:
array $args Template arguments
string $embed_provider The embed provider
string $embed_provider_lowercase The embed provider without spaces and in lowercase
string $output The output before replacing it

Expects an array.

embed_privacy_overlay_replaced_content since 1.10.0

Through the filter embed_privacy_overlay_replaced_content the replaced embed content can be changed.

Parameters:
string $content Replaced content

Expects a string.

embed_privacy_overlay_character_replacements since 1.10.0

Through the filter embed_privacy_overlay_character_replacements special character replacements for DOMDocument can be changed.

Parameters:
array $replacements Current replacements

Expects an associative array.

embed_privacy_template_attributes since 1.10.0

Through the filter embed_privacy_template_attributes the attributes for the embed template can be changed.

Parameters:
array $attributes Template attributes
string $provider The embed provider
string $output The output before replacing it

Expects an array.

embed_privacy_before_template_output since 1.10.0

The action embed_privacy_before_template_output fires before the template output is generated.

Parameters:
\epiphyt\Embed_Privacy\embed\Provider $provider The embed provider
\epiphyt\Embed_Privacy\embed\Style $style The overlay style object
array $attributes Additional attributes

embed_privacy_template_content since 1.10.0

Through the filter embed_privacy_template_content the content of an overlay template can be changed.

Parameters:
string $content The content
string $provider The embed provider of this embed

Expects a string.

embed_privacy_template_markup since 1.10.0

Through the filter embed_privacy_template_markup the markup of an overlay template can be changed.

Parameters:
string $markup The markup
\epiphyt\Embed_Privacy\embed\Provider $provider The embed provider of this embed

Expects a string.

embed_privacy_theme_content_width since 1.10.0

Through the filter embed_privacy_theme_content_width the content with to determine the correct embed aspect ratio can be filtered.

Parameters:
int $content_width Current content width

Expects an integer.

embed_privacy_background_path_$embed_provider_lowercase since 1.1.0

Through the filter embed_privacy_background_path_$embed_provider_lowercase the path to the background image of the overlay can be changed.

Parameters:
string $background_path The default background path
string $embed_provider_lowercase The current embed provider in lowercase

Expects a string to a valid path to a background image.

embed_privacy_background_url_$embed_provider_lowercase since 1.1.0

Through the filter embed_privacy_background_url_$embed_provider_lowercase the URL to the background image of the overlay can be changed.

Parameters:
string $background_url The default background URL
string $embed_provider_lowercase The current embed provider in lowercase

Expects a string to a valid URL to a background image.

embed_privacy_logo_path_$embed_provider_lowercase

Through the filter embed_privacy_logo_path_$embed_provider_lowercase the path to the logo of the overlay can be changed.

Parameters:
string $logo_path The default logo path
string $embed_provider_lowercase The current embed provider in lowercase

Expects a string to a valid path to a logo.

embed_privacy_logo_url_$embed_provider_lowercase

Through the filter embed_privacy_logo_url_$embed_provider_lowercase the URL to the logo of the overlay can be changed.

Parameters:
string $logo_url The default logo URL
string $embed_provider_lowercase The current embed provider in lowercase

Expects a string to a valid URL to a logo.

embed_privacy_thumbnail_checked_orphaned since 1.7.0

The action embed_privacy_thumbnail_checked_orphaned fires after orphaned data for a provider have been checked and deleted, if applicable.

Parameters:
string $provider Provider name
string $id The ID of the embedded content
string $url The embed URL
bool $missin_id Whether the ID is missing
bool $missing_url Whether the URL is missing
string $meta_value The thumbnail filename
string $meta_key The thumbnail meta key
WP_Post $post The post object
int $post_id The post ID

embed_privacy_thumbnail_data_filename since 1.7.0

Through the filter embed_privacy_thumbnail_data_filename the thumbnail filename while getting thumbnail data can be changed.

Parameters:
string $thumbnail The thumbnail filename
WP_Post $post The post object
string $url The embed URL

Expects a string with a thumbnail filename.

embed_privacy_thumbnail_data_id since 1.7.0

Through the filter embed_privacy_thumbnail_data_id the thumbnail ID while getting thumbnail data can be changed.

Parameters:
string $id The thumbnail ID
WP_Post $post The post object
string $url The embed URL

Expects a string with a thumbnail ID.

embed_privacy_thumbnail_data_path since 1.7.0

Through the filter embed_privacy_thumbnail_data_path the thumbnail path while getting thumbnail data can be changed.

Parameters:
string $thumbnail The thumbnail path
WP_Post $post The post object
string $url The embed URL

Expects a string with a thumbnail path.

embed_privacy_thumbnail_data_url since 1.7.0

Through the filter embed_privacy_thumbnail_data_url the thumbnail URL while getting thumbnail data can be changed.

Parameters:
string $url The thumbnail URL
WP_Post $post The post object
string $url The embed URL

Expects a string with a thumbnail URL.

embed_privacy_thumbnail_get_from_provider since 1.7.0

The action embed_privacy_thumbnail_get_from_provider fires after thumbnail data have been processed.

Parameters:
string $return The returned oEmbed HTML
object $data A data object result from an oEmbed provider
string $url The URL of the content to be embedded

embed_privacy_thumbnail_path_$embed_provider_lowercase since 1.1.0

Through the filter embed_privacy_thumbnail_path_$embed_provider_lowercase the path to the thumbnail of the overlay can be changed.

Parameters:
string $thumbnail_path The default thumbnail path
string $embed_provider_lowercase The current embed provider in lowercase

Expects a string to a valid path to a thumbnail.

embed_privacy_thumbnail_supported_provider_names since 1.7.0

Through the filter embed_privacy_thumbnail_supported_provider_names the internal names of supported thumbnail providers can be changed.

Parameters:
array supported_providers Current supported provider names

Expects an array with thumbnail provider names.

embed_privacy_thumbnail_providers since 1.9.0

Through the filter embed_privacy_thumbnail_providers the registered thumbnail providers can be changed.

Parameters:
Thumbnail_Provider[] $supported_providers Current supported providers

Expects an array with thumbnail provider classes.

embed_privacy_pre_thumbnail_delete_orphaned_delete since 1.8.0 deprecated 1.10.0

Through the action embed_privacy_pre_thumbnail_delete_orphaned_delete the deletion of orphaned thumbnails can be disabled.

Deprecated since 1.10.0, use embed_privacy_thumbnail_delete_orphaned instead.

Parameters:
string $id The thumbnail ID
string $url The thumbnail URL
int $post_id The post ID
string $provider The provider name

embed_privacy_thumbnail_delete_orphaned since 1.10.0

Through the filter embed_privacy_thumbnail_delete_orphaned the deletion of orphaned thumbnails can be disabled.

Parameters:
bool $should_delete Whether the thumbnail should be deleted
string $id The thumbnail ID
string $url The thumbnail URL
int $post_id The post ID
string $provider The provider name

Expects a boolean.

embed_privacy_thumbnail_url_$embed_provider_lowercase since 1.1.0

Through the filter embed_privacy_thumbnail_url_$embed_provider_lowercase the URL to the thumbnail of the overlay can be changed.

Parameters:
string $thumbnail_url The default thumbnail URL
string $embed_provider_lowercase The current embed provider in lowercase

Expects a string to a valid URL to a thumbnail.

embed_privacy_ignore_unknown_providers since 1.5.0

Through the filter embed_privacy_ignore_unknown_providers the processing of embeds of unknown embed providers can be disabled.

Parameters:
bool $ignore_unknown Whether unknown providers should be ignored
string $content The original content

Expects a boolean.

embed_privacy_ignore_embed since 1.9.0

Through the filter embed_privacy_ignore_embed the processing of particular embeds can be disabled.

Parameters:
bool $ignore_embed Whether to ignore this embed
string $content The original content
string $embed_provider The embed provider
string $embed_provider_lowercase The embed provider without spaces and in lowercase
array $args Additional arguments

Expects a boolean.

embed_privacy_is_ignored_request since 1.10.0

Through the filter embed_privacy_is_ignored_request a complete request can be set to be ignored.

Parameters:
bool $is_ignored_embed Whether the request is currently ignored

Expects a boolean.

embed_privacy_ignored_shortcodes since 1.6.0

Through the filter embed_privacy_ignored_shortcodes shortcodes can be ignored from being replaced by an overlay.

Parameters:
string[] $ignored_shortcodes Current list of ignored shortcodes

Expects an array.

embed_privacy_dynamic_style_properties since 1.9.0 deprecated 1.10.0

Through the filter embed_privacy_dynamic_style_properties properties for the dynamic embed style of a page can be changed.

Deprecated since 1.10.0.

Parameters:
array $style_properties Style properties array

Expects an array.

embed_privacy_dynamic_style since 1.9.0 deprecated 1.10.0

Through the filter embed_privacy_dynamic_style the dynamic embed style of a page can be changed.

Deprecated since 1.10.0.

Parameters:
string $style Generated style
array $style_properties Style properties array

Expects a string.

embed_privacy_matcher_elements since 1.6.0 deprecated 1.10.0

Through the filter embed_privacy_matcher_elements the HTML elements, which will extend the regular expression for custom embed providers, can be changed.

Deprecated since 1.10.0, use embed_privacy_replacer_matcher_elements instead.

Parameters:
array $allowed_tags The allowed tags
string $embed_provider_lowercase The current embed provider in lowercase

Expects an array.

embed_privacy_replacer_matcher_elements since 1.10.0

Through the filter embed_privacy_replacer_matcher_elements the HTML elements, which will extend the regular expression for custom embed providers, can be changed.

Parameters:
string[] $allowed_tags List of allowed tags
\epiphyt\Embed_privacy\embed\Provider|null $provider Embed provider

Expects an array.

embed_privacy_widget_output since 1.1.0

Through the filter embed_privacy_widget_output the output of a widget can be changed.

Parameters:
string $widget_output The widget’s output
string $widget_id The widget’s full ID
string $sidebar_id The current sidebar ID

Expects a string.

embed_privacy_opt_out_headline since 1.2.0

Through the filter embed_privacy_opt_out_headline the headline of the opt-out shortcode can be changed.

Parameters:
string $headline Current headline HTML
array $attributes Shortcode attributes

Expects a string.

embed_privacy_opt_out_subline since 1.2.0

Through the filter embed_privacy_opt_out_subline the sublime of the opt-out shortcode can be changed.

Parameters:
string $headline Current subline HTML
array $attributes Shortcode attributes

Expects a string.

embed_privacy_editor_fields

Through the filter embed_privacy_editor_fields additional fields can be rendered in the embed provider editor screen.

Parameters:
int $post_id The current post ID

Expects a string.

embed_privacy_register_fields since 1.2.0

Through the filter embed_privacy_register_fields additional fields can be registered.

Parameters:
int $post_id The current post ID

Expects an array.

embed_privacy_fields

Through the filter embed_privacy_fields all registered fields can be changed.

Parameters:
array $fields Registered fields

Expects an array.

embed_privacy_valid_files

Through the filter embed_privacy_valid_files the name of valid files in POST requests of the editor can be changed.

Parameters:
array The default name list

Expects an array.

jetpack_sharing_facebook_app_id since 1.4.5

Through the filter jetpack_sharing_facebook_app_id the Facebook app ID of Jetpack sharing can be changed.

Parameters:
string $app_id The current app ID

Expects a string.

Table of contents

  1. Regex pattern
  2. Using Embed Privacy in a plugin
  3. Custom thumbnail provider
  4. Filters