apply_filters( 'calucon_embed_gate_providers', array $providers )

filter1 argument

Fires

Once per request, when the provider registry is first resolved. Not at plugins_loaded.

Returns

The full descriptor array. Append to the array received and return it.

Parameters

$providers array

The built-in descriptors, already normalised and already passed through the plugin’s translator.

Owner-defined rows and the per-provider settings are applied after this filter. A site owner’s notice text, button text, privacy URL and enabled flag therefore override a code-registered descriptor.

Compare on id. The note and action values are translated before this filter runs; label and controller are not.

Example

add_filter(
	'calucon_embed_gate_providers',
	function ( array $providers ) {
		$providers[] = array(
			'id'          => 'example-videos',
			'label'       => 'ExampleVideos',
			'kind'        => 'video',
			'match'       => array(
				'iframe_host' => array( 'embed.example.com' ),
				// Named captures interpolate,
				// URL-encoded, into load_path
				// and fallback as {id}-style
				// tokens.
				'iframe_path' => '#^/v/(?<id>[A-Za-z0-9_-]+)#',
			),
			// Optional privacy-preserving
			// target, used after the click.
			'load_host'   => 'embed-nocookie.example.com',
			'load_path'   => '/v/{id}',
			'fallback'    => 'https://example.com/watch/{id}',
			'controller'  => 'Example Ltd, Berlin, Germany',
			'privacy_url' => 'https://example.com/privacy',
			'aspect'      => '16/9',
		);
		return $providers;
	}
);

Fired at src/Plugin.php:279. Permalink

apply_filters( 'calucon_embed_gate_provider_for_url', array $provider, string $url, string $host )

filter3 arguments

Fires

Once per detected embed, after the registry matches a descriptor and before rendering.

Returns

The descriptor to use. Cast to array.

Parameters

$provider array

The descriptor the registry matched. For an unrecognised host this is the generic one.

$url string

The embed URL as found in the content — except from resolve_for_asset_host(), which passes a synthetic https://host/. See the note.

$host string

That URL’s host, lower-cased.

Affects only how an embed is described. Gating is unaffected: an unrecognised host is gated either way.

One caller hands over a URL that never appeared in the markup. Matching a provider by asset host alone — a stylesheet, or since 1.0.0 the check that stops a known provider from hiding behind a /wp-content/ path — has only a host to work with, so it synthesises https://host/ for this filter. Code here that reads $url for a path, a query string or an id must tolerate that: match on $host first, and treat a bare origin as no information rather than as a URL that failed to match.

Example

add_filter(
	'calucon_embed_gate_provider_for_url',
	function ( array $provider, $url, $host ) {
		// One tenant's videos share a host with
		// everyone else's, so the label has to
		// come from the path.
		if ( 'generic' === $provider['id']
			&& false !== strpos( $url, '/studio-a/' ) ) {
			$provider['label'] = 'Studio A';
		}
		return $provider;
	},
	10,
	3
);

Fired at src/Plugin.php:427. Permalink

apply_filters( 'calucon_embed_gate_note_text', string $note, array $provider, array $ctx )

filter3 arguments

Fires

Once per gated embed, while its panel is built.

Returns

Plain text. The panel escapes the return value; do not pre-escape.

Parameters

$note string

The notice text as resolved so far: the provider default, or the site owner’s override if one is set.

$provider array

The descriptor. See the shared arguments.

$ctx array

Where this embed was found. See the shared arguments.

The plugin is a technical measure. Notice text should not assert a legal outcome.

Example

add_filter(
	'calucon_embed_gate_note_text',
	function ( $note, array $provider, array $ctx ) {
		// Plain text in, plain text out. The
		// panel escapes this, so an & here
		// would reach the visitor as
		// "&".
		if ( 'youtube' === $provider['id'] ) {
			return 'Video hosted by YouTube. It loads when you '
				. 'choose to load it.';
		}
		return $note;
	},
	10,
	3
);

Fired at src/Plugin.php:449. Permalink

apply_filters( 'calucon_embed_gate_action_text', string $action, array $provider, array $ctx )

filter3 arguments

Fires

Once per gated embed, while its panel is built.

Returns

Plain text. The panel escapes the return value; do not pre-escape.

Parameters

$action string

The button text resolved so far.

$provider array

The descriptor.

$ctx array

The integration context.

The label is the accessible name of a <button> and should describe the action, for example “Load this video”.

Example

add_filter(
	'calucon_embed_gate_action_text',
	function ( $action, array $provider, array $ctx ) {
		// $ctx['integration'] is the one key
		// that is always present, whichever
		// path the embed came in on.
		if ( 'comment' === $ctx['integration'] ) {
			return 'Load this embed';
		}
		return $action;
	},
	10,
	3
);

Fired at src/Plugin.php:452. Permalink

apply_filters( 'calucon_embed_gate_fallback_url', string $url, array $provider, array $ctx )

filter3 arguments

Fires

Once per gated embed, while its panel is built.

Returns

A URL, used for the server-rendered link and for the error state. An empty string leaves no link.

Parameters

$url string

The fallback the descriptor produced, usually built from the embed’s own id.

$provider array

The descriptor.

$ctx array

The integration context.

This link is the only route to the content when JavaScript is unavailable.

Example

add_filter(
	'calucon_embed_gate_fallback_url',
	function ( $url, array $provider, array $ctx ) {
		// Prefer your own write-up over the
		// provider's page, when the post has
		// one. post_id is absent on the widget,
		// description and output-buffer paths.
		if ( ! empty( $ctx['post_id'] ) ) {
			$own = get_post_meta(
				$ctx['post_id'],
				'embed_writeup_url',
				true
			);
			if ( is_string( $own ) && '' !== $own ) {
				return $own;
			}
		}
		return $url;
	},
	10,
	3
);

Fired at src/Plugin.php:455. Permalink

apply_filters( 'calucon_embed_gate_placeholder_html', string $html, array $provider, array $ctx )

filter3 arguments

Fires

Once per gated embed, after the placeholder template has rendered.

Returns

HTML, printed unescaped. Escape any interpolated value.

Parameters

$html string

The rendered panel.

$provider array

The descriptor.

$ctx array

The integration context.

Four parts are contractual and are located by class: the cg-embed container with its data-cg-* attributes, the cg-embed__panel div directly inside it, a <button type="button" class="cg-embed__button">, and the cg-embed__fallback paragraph.

Must not emit a literal <iframe: gated content may be processed again, and a raw iframe is re-detected. To replace the markup wholesale, override templates/placeholder.php in the theme.

Example

add_filter(
	'calucon_embed_gate_placeholder_html',
	function ( $html, array $provider, array $ctx ) {
		if ( 'video' !== $provider['kind'] ) {
			return $html;
		}
		// Wrapping keeps every class and
		// attribute the front end relies on
		// intact. Whatever is returned is
		// printed, so the caption is escaped
		// here.
		$caption = sprintf(
			/* translators: %s: provider name. */
			__( 'Hosted by %s.', 'my-theme' ),
			$provider['label']
		);
		return '<figure class="video-embed">'
			. $html
			. '<figcaption>' . esc_html( $caption )
			. '</figcaption></figure>';
	},
	10,
	3
);

Fired at src/Plugin.php:434. Permalink

apply_filters( 'calucon_embed_gate_payload', array $payload, array $provider )

filter2 arguments

Fires

Once per gated embed, after the payload is assembled and before it is encoded.

Returns

The payload array. Cast to array, then JSON-encoded into an attribute; the value must be serialisable.

Parameters

$payload array

What the browser rebuilds the embed from: src, attrs, and depending on the embed srcdoc, tag, strategy or inline. See the payload.

$provider array

The descriptor.

No $ctx is passed. Use placeholder_html where the integration context is required.

attrs is an array when attributes are present and an empty stdClass otherwise, so that it encodes as {} rather than []. Check with is_array() before writing to it.

Example

add_filter(
	'calucon_embed_gate_payload',
	function ( array $payload, array $provider ) {
		// attrs is an empty stdClass when the
		// embed carried no attributes, so it
		// cannot be indexed blindly.
		if ( ! is_array( $payload['attrs'] ) ) {
			$payload['attrs'] = array();
		}
		if ( ! isset( $payload['attrs']['title'] ) ) {
			$payload['attrs']['title'] = sprintf(
				/* translators: %s: provider name. */
				__( 'Embedded content from %s', 'my-theme' ),
				$provider['label']
			);
		}
		return $payload;
	},
	10,
	2
);

Fired at src/Plugin.php:437. Permalink

apply_filters( 'calucon_embed_gate_cmp_config', ?array $config, array $cmp_options )

filter2 arguments

Fires

On a page with gated embeds, when the bridge configuration is assembled.

Returns

The configuration array, or null to disable the bridge. Any non-array value disables it.

Parameters

$config array|null

The built config, or null when the bridge is disabled or no tested platform was detected.

$cmp_options array

The cmp section of the settings: bridge, borlabs_group.

Disabling the bridge is restrictive rather than permissive: the server always renders the panel, so gated embeds then require a click.

Example

add_filter(
	'calucon_embed_gate_cmp_config',
	function ( $config, array $cmp_options ) {
		// null means the bridge is already off.
		// Leave it off.
		if ( ! is_array( $config ) ) {
			return $config;
		}
		// This site's platform files embeds
		// under its own category name rather
		// than the default.
		$config['category'] = 'external-media';
		return $config;
	},
	10,
	2
);

Fired at src/Plugin.php:763. Permalink

apply_filters( 'calucon_embed_gate_the_content_priority', int $priority )

filter1 argument

Fires

During plugin registration, on plugins_loaded.

Returns

The priority. Default 20. Cast to int.

Parameters

$priority int

The default, 20.

Not usable from a theme. Registration occurs on plugins_loaded, which precedes theme loading, so a callback added in functions.php never runs and no error is raised. Use an mu-plugin; see where the code goes.

Example

// wp-content/mu-plugins/embed-gate-priority.php
// An mu-plugin, not functions.php: this filter
// fires while the plugin registers on
// plugins_loaded, before any theme loads.

add_filter(
	'calucon_embed_gate_the_content_priority',
	function ( $priority ) {
		// Run after a plugin that rewrites
		// content at 50.
		return 60;
	}
);

Fired at src/Integration/TheContent.php:37. Permalink

apply_filters( 'calucon_embed_gate_render_block_priority', int $priority )

filter1 argument

Fires

During plugin registration, on plugins_loaded.

Returns

The priority. Default 10. Cast to int.

Parameters

$priority int

The default, 10.

Not usable from a theme, for the reason given under the_content_priority.

Example

// wp-content/mu-plugins/embed-gate-priority.php

add_filter(
	'calucon_embed_gate_render_block_priority',
	function ( $priority ) {
		// Let a block-rewriting plugin at 15 go
		// first.
		return 20;
	}
);

Fired at src/Integration/RenderBlock.php:38. Permalink

apply_filters( 'calucon_embed_gate_asset_version', string $version, string $relative )

filter2 arguments

Fires

Once per bundled asset, when its ver argument is resolved.

Returns

The version string. Cast to string.

Parameters

$version string

The plugin version, or the file’s modification time on a site the plugin considers a development one.

$relative string

The asset path inside the plugin, for example assets/js/gate.js.

On a multi-server site the default modification time differs between machines, so one file can be served under several version strings. A build identifier is stable across servers.

Example

add_filter(
	'calucon_embed_gate_asset_version',
	function ( $version, $relative ) {
		// One deploy identifier for every
		// server behind the load balancer,
		// instead of each machine's own mtime.
		if ( defined( 'MY_DEPLOY_ID' ) ) {
			return (string) MY_DEPLOY_ID;
		}
		return $version;
	},
	10,
	2
);

Fired at src/Support/AssetVersion.php:67. Permalink

do_action( 'calucon_embed_gate_before_render', array $provider, array $ctx )

action2 arguments

Fires

Once per gated embed, before the wording hooks and before any markup exists.

Returns

Nothing.

Parameters

$provider array

The descriptor about to be rendered.

$ctx array

The integration context.

Runs for every panel on every page view. Callbacks must be inexpensive, and must not write to client storage.

Example

add_action(
	'calucon_embed_gate_before_render',
	function ( array $provider, array $ctx ) {
		// Remember which kinds of embed this
		// page holds, so the footer can enqueue
		// only the styles it needs.
		if ( ! isset( $GLOBALS['my_embed_kinds'] ) ) {
			$GLOBALS['my_embed_kinds'] = array();
		}
		$kind = '' !== $provider['kind']
			? $provider['kind']
			: 'generic';
		$GLOBALS['my_embed_kinds'][ $kind ] = true;
	},
	10,
	2
);

Fired at src/Plugin.php:446. Permalink

do_action( 'calucon_embed_gate_embed_gated', array $provider, array $ctx )

action2 arguments

Fires

Once per gated embed, after its panel is rendered. The front-end assets are enqueued at the same point.

Returns

Nothing.

Parameters

$provider array

The descriptor that was gated.

$ctx array

The integration context.

Differs from before_render in timing: before_render runs as a panel begins to be built; this runs once the embed has been gated.

Example

add_action(
	'calucon_embed_gate_embed_gated',
	function ( array $provider, array $ctx ) {
		// A per-request tally, for a debug bar
		// or a footer note. Deliberately
		// in-memory: writing on a render would
		// make every page view a database
		// write.
		if ( ! isset( $GLOBALS['my_gated_embeds'] ) ) {
			$GLOBALS['my_gated_embeds'] = array();
		}
		$id = $provider['id'];
		$GLOBALS['my_gated_embeds'][ $id ] = 1 + (int) (
			isset( $GLOBALS['my_gated_embeds'][ $id ] )
				? $GLOBALS['my_gated_embeds'][ $id ]
				: 0
		);
	},
	10,
	2
);

Fired at src/Plugin.php:503. Permalink

do_action( 'calucon_embed_gate_flush_caches' )

actionno arguments

Fires

After the plugin clears the caches it manages. Five occasions, not one: a settings save, the first settings save (a distinct event — a site that has never opened the screen has no option row, so WordPress adds one rather than updating it, and 1.0.0 was the release that started listening for it), activation, deactivation, and an update of the plugin.

Returns

Nothing. No arguments are passed.

Intended for caches the plugin cannot detect: a hosting layer, a CDN, a custom fragment cache. A stale page continues to serve panels built from superseded settings.

Do not assume a settings save: the same action arrives on activation and deactivation, when what is cached is a page with no gate at all, and after an update, when it is the previous version’s placeholder markup. A callback that purges is right in every case; one that reads the current settings to decide what to purge is not.

Example

add_action(
	'calucon_embed_gate_flush_caches',
	function () {
		// No arguments: add_action's default
		// $accepted_args of 1 is fine because
		// the callback declares none.
		if ( function_exists( 'my_host_purge_everything' ) ) {
			my_host_purge_everything();
		}
	}
);

Fired at src/Support/CacheFlush.php:54. Permalink

apply_filters( 'calucon_embed_gate_should_gate', bool $gate, string $url, array $ctx )

filter3 arguments

Fires

Once per candidate embed, after a detection rule selects it and before rendering.

Returns

true to gate the embed, false to allow the request on page load. Cast to bool.

Parameters

$gate bool

What the gate intends to do. In practice always true here — the filter runs on embeds it has already decided to hold.

$url string

The URL that would be requested.

$ctx array

The integration context.

Blocks set to Always gate bypass this filter: force_gate is evaluated before the callback runs.

The Never gate setting expresses a host exemption in the admin, where it remains visible to the site owner.

Example

add_filter(
	'calucon_embed_gate_should_gate',
	function ( $gate, $url, array $ctx ) {
		// Tightening, not loosening: hold
		// everything that reaches a sidebar
		// widget, whatever the settings say.
		if ( 'widget' === $ctx['integration'] ) {
			return true;
		}
		return $gate;
	},
	10,
	3
);

Fired at src/Plugin.php:468. Permalink

apply_filters( 'calucon_embed_gate_is_own_host', bool $own, string $host )

filter2 arguments

Fires

Whenever a host is classified as this site or as a third party.

Returns

true if the host is the site itself, in which case its embeds are not gated. Cast to bool.

Parameters

$own bool

What the built-in rules concluded: the home and site URLs, since 1.0.0 the site’s asset bases as well — content_url(), includes_url(), plugins_url(), the uploads base and both theme directory URIs — the network’s other sites on multisite, and the configured own-hosts and never-gate lists.

$host string

The host being classified, lower-cased.

The always-gate list takes precedence and is evaluated first: hosts on it return false without reaching this filter.

Equivalent to the Own hosts setting, which requires no code.

This filter classifies a host, and 1.0.0 added one rule that classifies a URL instead: a <script> or <link rel=stylesheet> whose path contains /wp-content/ or /wp-includes/ is left alone whatever host serves it, for the CDN that rewrites the finished HTML rather than filtering WordPress’s URL functions. It does not run this filter, so returning false here will not gate such a URL. Two things do: the host belonging to a provider the plugin already knows, and the always-gate list. Never applies to iframes or images.

Example

add_filter(
	'calucon_embed_gate_is_own_host',
	function ( $own, $host ) {
		// This CDN serves this site's own media
		// library, so it is not a third party.
		// Anything added here is requested on
		// page load, with no panel and no
		// click.
		return $own || 'assets.my-cdn.example' === $host;
	},
	10,
	2
);

Fired at src/Plugin.php:413. Permalink

apply_filters( 'calucon_embed_gate_own_hosts', array $hosts )

filter1 argument

Fires

While the own-host list is assembled, before the detection pipeline is built.

Returns

The additional hosts. Cast to array and merged with the hosts the plugin derives itself, which are always present.

Parameters

$hosts array

The configured Own hosts and Never gate lists, merged. Both have the same effect here; they are separate settings because they mean different things to the site owner.

Hosts added here are not gated, and are requested on page load. The Own hosts setting is equivalent and remains visible to the site owner.

The list this filter receives is already populated. Since 1.0.0 it carries the host of every URL WordPress reports as the site’s own: home_url(), site_url(), content_url(), includes_url(), plugins_url(), the uploads base and both theme directory URIs — plus every domain on a multisite network. A CDN plugin that filters those functions therefore declares its host as the site’s own already, and needs nothing added here.

Those functions can only ever answer where do my assets live, so none of them can introduce a third party. This filter can: a host added here is exempt from gating on every page, for iframes as much as for scripts.

Example

add_filter(
	'calucon_embed_gate_own_hosts',
	function ( array $hosts ) {
		// Declared in code because it is
		// deploy-specific: the bucket name
		// differs between staging and
		// production.
		if ( defined( 'MY_MEDIA_HOST' ) ) {
			$hosts[] = MY_MEDIA_HOST;
		}
		return $hosts;
	}
);

Fired at src/Plugin.php:828. Permalink

apply_filters( 'calucon_embed_gate_www_equivalence', bool $equivalent )

filter1 argument

Fires

Once, when the host matcher is constructed.

Returns

true if www.example.com and example.com are the same site. Defaults to the www equivalence setting, which is enabled. Cast to bool.

Parameters

$equivalent bool

The configured value.

Disabling this changes classification in both directions: a host previously treated as the site becomes a third party, and on a site whose canonical host carries www the bare domain is no longer recognised as the site itself.

Example

add_filter(
	'calucon_embed_gate_www_equivalence',
	function ( $equivalent ) {
		// Only on a site where www and the bare
		// domain really are separate
		// properties. Check both spellings with
		// `wp calucon-embed-gate scan` after
		// changing this.
		return false;
	}
);

Fired at src/Plugin.php:405. Permalink