<?php
/**
 * The demo wire format.
 *
 * Shared by the Demo Source module, which writes it, and the Demos
 * module, which reads it. It lives in core rather than in either module so the
 * two can never disagree about stage names, post types or which meta travels.
 *
 * @package PageCore
 */

namespace PageCore;

defined( 'ABSPATH' ) || exit;

/**
 * Names and shapes both ends of a demo transfer agree on.
 */
class Demo_Wire {

	/**
	 * Wire format version. Bumped only when the shape changes incompatibly.
	 */
	const FORMAT = '1.0';

	/**
	 * Stages the source publishes, in the order the importer consumes them.
	 *
	 * Order matters: terms and media exist before anything can point at them,
	 * and settings run last because they point at pages.
	 */
	const STAGES = array(
		'terms',
		'plugin-content',
		'media',
		'patterns',
		'content',
		'navigation',
		'templates',
		'styles',
		'settings',
	);

	/**
	 * Post types carried by each object stage.
	 *
	 * @return array<string,string[]>
	 */
	public static function stage_post_types() {
		return array(
			'media'      => array( 'attachment' ),
			'patterns'   => array( 'wp_block' ),
			'content'    => array( 'page', 'post' ),
			'navigation' => array( 'wp_navigation' ),
			'templates'  => array( 'wp_template', 'wp_template_part' ),
			'styles'     => array( 'wp_global_styles' ),
		);
	}

	/**
	 * Whether a stage is allowed to deliver an object of one post type.
	 *
	 * The stage a batch was asked for is the only thing the receiving side
	 * decided; everything in the answer was written by the other end. A demo
	 * that answers the templates stage with a page, or with a post type of its
	 * own invention, is either broken or trying something, and either way the
	 * object does not belong in the stage that asked for it. Checked rather
	 * than assumed, so an import can only ever create the kinds of object the
	 * plan below names.
	 *
	 * @param string $stage   Stage name.
	 * @param string $type    Post type the item claims to be.
	 * @param array  $plugins Plugins this demo declared.
	 * @return bool
	 */
	public static function stage_allows_type( $stage, $type, $plugins = array() ) {
		$type = (string) $type;

		if ( '' === $type ) {
			return false;
		}

		return in_array( $type, self::post_types_for( $stage, $plugins ), true );
	}

	/**
	 * Media types an import will store.
	 *
	 * Narrower than what the site accepts from its own administrators, because
	 * these files arrive over the network from a document. Anything that is
	 * not a picture, a font or a plain document has no place in a demo.
	 *
	 * @return string[]
	 */
	public static function importable_mime_types() {
		return array(
			'image/jpeg',
			'image/png',
			'image/gif',
			'image/webp',
			'image/avif',
			'image/svg+xml',
			'image/x-icon',
			'image/vnd.microsoft.icon',
			'video/mp4',
			'video/webm',
			'audio/mpeg',
			'application/pdf',
			'font/woff',
			'font/woff2',
			'font/ttf',
			'application/font-woff',
			'application/font-woff2',
		);
	}

	/**
	 * Post types in one stage.
	 *
	 * @param string $stage   Stage name.
	 * @param array  $plugins Plugins this demo uses, for the plugin-content stage.
	 * @return string[]
	 */
	public static function post_types_for( $stage, $plugins = array() ) {
		if ( 'plugin-content' === $stage ) {
			return self::plugin_post_types( $plugins );
		}

		$map = self::stage_post_types();

		return isset( $map[ $stage ] ) ? $map[ $stage ] : array();
	}

	/**
	 * Post types owned by the plugins a demo uses.
	 *
	 * A WPForms block or shortcode is useless without the form it points at,
	 * so the form travels with the demo and the page is pointed at the copy
	 * made here.
	 *
	 * @param array $plugins Plugin entries, as the manifest lists them.
	 * @return string[]
	 */
	public static function plugin_post_types( $plugins = array() ) {
		$signatures = self::plugin_signatures();
		$types      = array();

		foreach ( (array) $plugins as $plugin ) {
			$slug = isset( $plugin['slug'] ) ? $plugin['slug'] : '';

			if ( ! $slug || empty( $signatures[ $slug ]['postTypes'] ) ) {
				continue;
			}

			foreach ( (array) $signatures[ $slug ]['postTypes'] as $type ) {
				if ( post_type_exists( $type ) ) {
					$types[] = $type;
				}
			}
		}

		return array_values( array_unique( $types ) );
	}

	/**
	 * A WPForms form with everything belonging to the demo site taken out.
	 *
	 * Where a form's notifications go is the site owner's business, not the
	 * demo's. A demo's endpoints are public, so an address typed into a
	 * notification would be handed to anyone who asked, and a demo that set
	 * one could have a customer's enquiries sent somewhere else. Connections
	 * to outside services - marketing lists, payment accounts, webhooks - are
	 * the demo site's own accounts and do not travel at all. Run by the demo
	 * when it exports and again by the site that imports.
	 *
	 * @param mixed $form Form data, decoded.
	 * @return array
	 */
	public static function scrub_form( $form ) {
		$form = is_array( $form ) ? $form : array();

		unset( $form['providers'], $form['payments'] );

		if ( ! isset( $form['settings'] ) || ! is_array( $form['settings'] ) ) {
			return $form;
		}

		unset( $form['settings']['webhooks'], $form['settings']['webhooks_enable'] );

		if ( isset( $form['settings']['notifications'] ) && is_array( $form['settings']['notifications'] ) ) {
			foreach ( $form['settings']['notifications'] as $key => $notification ) {
				$form['settings']['notifications'][ $key ] = self::scrub_form_notification( $notification );
			}
		}

		return $form;
	}

	/**
	 * One WPForms notification, addressed by the site that receives it.
	 *
	 * It goes to that site's administrator and is sent from that address,
	 * both by WPForms' own {admin_email} smart tag, which WPForms fills in
	 * from the site's settings when it sends. Reply-to may only name a field
	 * of the form, so a reply goes to whoever filled it in. The sender's name
	 * is the site's own unless it is made only of smart tags. A literal
	 * address anywhere else in the notification is replaced too.
	 *
	 * @param mixed $notification Notification settings.
	 * @return array
	 */
	public static function scrub_form_notification( $notification ) {
		$notification = is_array( $notification ) ? $notification : array();

		unset( $notification['carboncopy'] );

		$notification['email']          = '{admin_email}';
		$notification['sender_address'] = '{admin_email}';

		$replyto = isset( $notification['replyto'] ) && is_string( $notification['replyto'] ) ? trim( $notification['replyto'] ) : '';

		$notification['replyto'] = preg_match( '/^\{field_id="\d+"\}$/', $replyto ) ? $replyto : '';

		$sender = isset( $notification['sender_name'] ) && is_string( $notification['sender_name'] ) ? trim( $notification['sender_name'] ) : '';

		$notification['sender_name'] = preg_match( '/^(\s*\{[a-z_]+\}\s*)+$/', $sender ) ? $sender : '{site_name}';

		foreach ( array( 'notification_name', 'subject', 'message' ) as $key ) {
			if ( isset( $notification[ $key ] ) && is_string( $notification[ $key ] ) ) {
				$notification[ $key ] = preg_replace( '/[^\s<>"\'{}\[\](),;:]+@[^\s<>"\'{}\[\](),;:]+\.[a-z]{2,}/i', '{admin_email}', $notification[ $key ] );
			}
		}

		return $notification;
	}

	/**
	 * Site options that travel in the settings stage.
	 *
	 * Deliberately a fixed list. A demo must not be able to change a customer's
	 * site in ways they did not ask for, so only options that are part of how a
	 * demo looks are carried.
	 *
	 * @return string[]
	 */
	public static function transferred_options() {
		return array(
			'blogname',
			'blogdescription',
			'show_on_front',
			'page_on_front',
			'page_for_posts',
			'posts_per_page',
			'permalink_structure',
			'site_logo',
			'site_icon',
			'date_format',
			'time_format',
			'start_of_week',
		);
	}

	/**
	 * Options in the settings stage whose value is a post id.
	 *
	 * These must be rewritten through the id map before they are stored.
	 *
	 * @return string[]
	 */
	public static function post_id_options() {
		return array(
			'page_on_front',
			'page_for_posts',
			'site_logo',
			'site_icon',
		);
	}

	/**
	 * Block attribute names holding a single object id.
	 *
	 * @return string[]
	 */
	public static function id_attributes() {
		return array(
			'id',
			'mediaId',
			'backgroundId',
			'imageId',
			'iconId',
			'ref',
			'postId',
			'featuredImageId',
		);
	}

	/**
	 * Block attribute names holding an array of object ids.
	 *
	 * @return string[]
	 */
	public static function id_list_attributes() {
		return array(
			'ids',
			'includes',
			'selectedTerms',
		);
	}

	/**
	 * Block attribute names holding a URL.
	 *
	 * @return string[]
	 */
	public static function url_attributes() {
		return array(
			'url',
			'src',
			'href',
			'mediaLink',
			'poster',
			'backgroundImage',
			'iconUrl',
		);
	}

	/**
	 * Plugins a demo's content can depend on, and how to recognise them.
	 *
	 * A demo site's author should not have to remember to declare that the
	 * contact page holds a WPForms form. The source site reads its
	 * own content and works it out, so what the manifest declares is what the
	 * demo actually uses.
	 *
	 * Only plugins the demos actually use are listed. Recognising a plugin
	 * nobody here builds with is not free: it means offering to install
	 * something on a customer's site off the back of a shortcode that was never
	 * tested against, and it invites the list to grow into a catalogue of the
	 * whole plugin directory. Add an entry when a demo needs one.
	 *
	 * @return array<string,array>
	 */
	public static function plugin_signatures() {
		return array(
			'wpforms-lite' => array(
				'name'       => 'WPForms Lite',
				'source'     => 'wordpress.org',
				'shortcodes' => array( 'wpforms' ),
				'blocks'     => array( 'wpforms/form-selector' ),
				// The form itself, so the demo's fields and settings
				// travel. WPForms keeps a whole form as JSON in the post
				// body, so no protected meta is needed.
				'postTypes'  => array( 'wpforms' ),
				// WPForms Pro lives in its own directory and does the
				// same job; a site running it needs nothing installed.
				'providedBy' => array( 'wpforms' ),
				// The block attribute that names the form to show.
				'formAttribute' => 'formId',
			),
		);
	}

	/**
	 * Themes an import may install and activate.
	 *
	 * A demo names the theme it is built for, but which theme code comes onto
	 * a customer's site is decided here, not by the demo server. Add a theme
	 * here when a demo is built on one.
	 *
	 * @return array<string,string> Theme name, keyed by WordPress.org slug.
	 */
	public static function approved_themes() {
		return array(
			PAGECORE_THEME_SLUG => 'PageCore FSE',
		);
	}

	/**
	 * The theme a demo's manifest asks for, checked against approved_themes().
	 *
	 * An approved theme is described from this list, not from the manifest.
	 * Any other theme is kept only to tell the customer about it, marked
	 * unsupported, and is never installed or activated.
	 *
	 * @param mixed $theme Theme block as the manifest wrote it.
	 * @return array Empty when the manifest names no theme.
	 */
	public static function demo_theme( $theme ) {
		$theme = is_array( $theme ) ? $theme : array();
		$slug  = isset( $theme['slug'] ) && is_string( $theme['slug'] ) ? sanitize_key( $theme['slug'] ) : '';

		if ( '' === $slug ) {
			return array();
		}

		$approved = self::approved_themes();

		if ( isset( $approved[ $slug ] ) ) {
			return array(
				'slug' => $slug,
				'name' => $approved[ $slug ],
			);
		}

		$name = isset( $theme['name'] ) && is_scalar( $theme['name'] ) ? sanitize_text_field( (string) $theme['name'] ) : '';

		return array(
			'slug'        => $slug,
			'name'        => '' !== $name ? $name : $slug,
			'unsupported' => true,
		);
	}

	/**
	 * The plugins a demo's manifest asks for, sorted against plugin_signatures().
	 *
	 * Only a plugin this file knows may be installed or activated, and its
	 * name and source come from here, not from the manifest. Anything else is
	 * kept only to tell the customer about it.
	 *
	 * @param mixed $plugins requiredPlugins as the manifest wrote it.
	 * @return array{supported: array[], other: array[]}
	 */
	public static function demo_plugins( $plugins ) {
		$signatures = self::plugin_signatures();
		$supported  = array();
		$other      = array();

		foreach ( array_slice( is_array( $plugins ) ? $plugins : array(), 0, 20 ) as $plugin ) {
			$slug = is_array( $plugin ) && isset( $plugin['slug'] ) && is_string( $plugin['slug'] ) ? sanitize_key( $plugin['slug'] ) : '';

			if ( '' === $slug || isset( $supported[ $slug ] ) || isset( $other[ $slug ] ) ) {
				continue;
			}

			if ( isset( $signatures[ $slug ] ) ) {
				$supported[ $slug ] = array(
					'slug'     => $slug,
					'name'     => isset( $signatures[ $slug ]['name'] ) ? (string) $signatures[ $slug ]['name'] : $slug,
					'source'   => isset( $signatures[ $slug ]['source'] ) ? (string) $signatures[ $slug ]['source'] : 'wordpress.org',
					'detected' => ! empty( $plugin['detected'] ),
				);

				continue;
			}

			$name = isset( $plugin['name'] ) && is_scalar( $plugin['name'] ) ? sanitize_text_field( (string) $plugin['name'] ) : '';

			$other[ $slug ] = array(
				'slug' => $slug,
				'name' => '' !== $name ? $name : $slug,
			);
		}

		return array(
			'supported' => array_values( $supported ),
			'other'     => array_values( $other ),
		);
	}

	/**
	 * What to tell the customer about a plugin a demo uses that PageCore does
	 * not install.
	 *
	 * @param string $name Plugin name, or its slug.
	 * @return string
	 */
	public static function other_plugin_message( $name ) {
		return sprintf(
			/* translators: %s: plugin name. */
			__( 'This demo also uses %s. PageCore won\'t install it, so install it yourself if you need it.', 'pagecore' ),
			$name
		);
	}

	/**
	 * The blocks that embed a form, from PageCore's own list of plugins.
	 *
	 * @return array<string,string> Name of the attribute holding the form, keyed by block name.
	 */
	public static function form_blocks() {
		$blocks = array();

		foreach ( self::plugin_signatures() as $signature ) {
			if ( empty( $signature['formAttribute'] ) ) {
				continue;
			}

			foreach ( (array) ( isset( $signature['blocks'] ) ? $signature['blocks'] : array() ) as $block ) {
				$blocks[ (string) $block ] = (string) $signature['formAttribute'];
			}
		}

		return $blocks;
	}

	/**
	 * The form plugins a piece of markup is waiting for.
	 *
	 * A form block whose plugin is not active is only a marker; the customer
	 * has to activate the plugin before a form can be chosen in it.
	 *
	 * @param string $content Serialized blocks.
	 * @return string[] Plugin names.
	 */
	public static function inactive_form_plugins( $content ) {
		$content = (string) $content;
		$names   = array();

		foreach ( self::plugin_signatures() as $slug => $signature ) {
			if ( empty( $signature['formAttribute'] ) ) {
				continue;
			}

			foreach ( (array) ( isset( $signature['blocks'] ) ? $signature['blocks'] : array() ) as $block ) {
				if ( false !== strpos( $content, '<!-- wp:' . $block ) && ! self::block_is_registered( (string) $block ) ) {
					$names[] = isset( $signature['name'] ) ? (string) $signature['name'] : (string) $slug;

					break;
				}
			}
		}

		return array_values( array_unique( $names ) );
	}

	/**
	 * Whether a block type is registered on this site.
	 *
	 * @param string $name Block name.
	 * @return bool
	 */
	private static function block_is_registered( $name ) {
		return class_exists( 'WP_Block_Type_Registry' ) && \WP_Block_Type_Registry::get_instance()->is_registered( $name );
	}

	/**
	 * A block's category and tag filters, pointed at this site's terms.
	 *
	 * A Query Loop and a Latest Posts block can show only the posts of some
	 * categories or tags, named by the source site's term ids: a Query Loop in
	 * its taxQuery, in either shape WordPress stores ({"category":[4]} or
	 * {"include":{"category":[4]},"exclude":{...}}), or in the older
	 * categoryIds and tagIds; Latest Posts in categories. Each id goes through
	 * $map, and one it answers 0 for is taken out, so the block shows more
	 * posts rather than those of whichever term has that number here.
	 *
	 * @param string   $name   Block name.
	 * @param array    $attrs  Attributes to write the filters into.
	 * @param array    $source Attributes as the source wrote them.
	 * @param callable $map    Source term id to this site's id, or 0.
	 * @return array
	 */
	public static function map_term_filters( $name, array $attrs, array $source, callable $map ) {
		if ( 'core/query' === $name && isset( $source['query'] ) && is_array( $source['query'] ) ) {
			foreach ( array( 'taxQuery', 'categoryIds', 'tagIds' ) as $key ) {
				if ( isset( $source['query'][ $key ] ) && is_array( $source['query'][ $key ] ) ) {
					$attrs['query'][ $key ] = self::map_term_list( $source['query'][ $key ], $map );
				}
			}
		}

		if ( 'core/latest-posts' === $name && isset( $source['categories'] ) && is_array( $source['categories'] ) ) {
			$kept = array();

			foreach ( $source['categories'] as $category ) {
				$local = is_array( $category ) && isset( $category['id'] ) && is_numeric( $category['id'] )
					? (int) call_user_func( $map, (int) $category['id'] )
					: 0;

				if ( $local > 0 ) {
					$category['id'] = $local;
					$kept[]         = $category;
				}
			}

			$attrs['categories'] = $kept;
		}

		return $attrs;
	}

	/**
	 * Every term id in a filter, mapped, at any depth.
	 *
	 * @param array    $value Filter as the source wrote it.
	 * @param callable $map   Source term id to this site's id, or 0.
	 * @return array
	 */
	private static function map_term_list( array $value, callable $map ) {
		$is_list = array_values( $value ) === $value;
		$out     = array();

		foreach ( $value as $key => $item ) {
			if ( is_array( $item ) ) {
				$out[ $key ] = self::map_term_list( $item, $map );
			} elseif ( ! is_numeric( $item ) ) {
				$out[ $key ] = $item;
			} else {
				$local = (int) call_user_func( $map, (int) $item );

				if ( $local > 0 ) {
					$out[ $key ] = $local;
				}
			}
		}

		// A list with an id taken out stays a list, not an object.
		return $is_list ? array_values( $out ) : $out;
	}

	/**
	 * Markup with every category and tag filter taken out.
	 *
	 * A page or pattern from the Design Library brings no categories with
	 * it, so a filter naming the source's term ids would show the posts of
	 * whichever of the customer's terms has that number. Taken out, the block
	 * shows the latest posts, and the customer picks a category in it.
	 *
	 * @param string $content Serialized blocks.
	 * @return string
	 */
	public static function detach_term_filters( $content ) {
		$content = (string) $content;

		if ( false === strpos( $content, '<!-- wp:query {' ) && false === strpos( $content, '<!-- wp:latest-posts {' ) ) {
			return $content;
		}

		$changed = false;
		$blocks  = self::detach_term_filters_in( parse_blocks( $content ), $changed );

		return $changed ? serialize_blocks( $blocks ) : $content;
	}

	/**
	 * Take the term filters out of a list of blocks and everything inside them.
	 *
	 * @param array[] $blocks  Parsed blocks.
	 * @param bool    $changed Set when any filter was taken out.
	 * @return array[]
	 */
	private static function detach_term_filters_in( $blocks, &$changed ) {
		foreach ( $blocks as $index => $block ) {
			$name  = isset( $block['blockName'] ) ? (string) $block['blockName'] : '';
			$attrs = isset( $block['attrs'] ) && is_array( $block['attrs'] ) ? $block['attrs'] : array();
			$clear = self::map_term_filters( $name, $attrs, $attrs, '__return_zero' );

			if ( $clear !== $attrs ) {
				$blocks[ $index ]['attrs'] = $clear;
				$changed                   = true;
			}

			if ( ! empty( $block['innerBlocks'] ) ) {
				$blocks[ $index ]['innerBlocks'] = self::detach_term_filters_in( $block['innerBlocks'], $changed );
			}
		}

		return $blocks;
	}

	/**
	 * Markup with every embedded form pointed at no form.
	 *
	 * A page taken from the Design Library brings its markup but not the
	 * forms behind it. A form block or shortcode names its form by the demo
	 * site's number, and on this site that number is something else: usually
	 * nothing, sometimes one of the customer's own forms, which the page
	 * would then show. So the number is cleared, and the customer chooses a
	 * form of their own in the block.
	 *
	 * A demo import does not come through here. It brings the form with it
	 * and points the page at the copy; see Block_Rewriter.
	 *
	 * @param string $content Serialized blocks, or classic markup.
	 * @return string
	 */
	public static function detach_forms( $content ) {
		$content    = (string) $content;
		$blocks     = self::form_blocks();
		$shortcodes = array();

		foreach ( self::plugin_signatures() as $signature ) {
			if ( empty( $signature['formAttribute'] ) ) {
				continue;
			}

			foreach ( (array) ( isset( $signature['shortcodes'] ) ? $signature['shortcodes'] : array() ) as $shortcode ) {
				$shortcodes[] = (string) $shortcode;
			}
		}

		// Nearly every page has no form in it, and is handed back untouched.
		$has_form = false;

		foreach ( array_keys( $blocks ) as $block ) {
			$has_form = $has_form || false !== strpos( $content, '<!-- wp:' . $block );
		}

		foreach ( $shortcodes as $shortcode ) {
			$has_form = $has_form || false !== stripos( $content, '[' . $shortcode );
		}

		if ( ! $has_form ) {
			return $content;
		}

		if ( ! has_blocks( $content ) ) {
			return self::detach_form_shortcodes( $content, $shortcodes );
		}

		return serialize_blocks( self::detach_forms_in( parse_blocks( $content ), $blocks, $shortcodes ) );
	}

	/**
	 * Clear the form in a list of blocks and everything inside them.
	 *
	 * @param array[]  $list       Parsed blocks.
	 * @param string[] $blocks     Form attribute name, keyed by block name.
	 * @param string[] $shortcodes Shortcode tags that embed a form.
	 * @return array[]
	 */
	private static function detach_forms_in( $list, $blocks, $shortcodes ) {
		foreach ( $list as $index => $block ) {
			$name = isset( $block['blockName'] ) ? (string) $block['blockName'] : '';

			if ( isset( $blocks[ $name ] ) && isset( $block['attrs'][ $blocks[ $name ] ] ) ) {
				$block['attrs'][ $blocks[ $name ] ] = '';
			}

			// The plugin behind the block is not active, so nothing on this
			// site knows what its other settings mean. Only the block and
			// its unset form are kept: a marker for where the form goes,
			// which becomes the plugin's own form chooser once it is active.
			if ( isset( $blocks[ $name ] ) && ! self::block_is_registered( $name ) ) {
				$block['attrs']        = array( $blocks[ $name ] => '' );
				$block['innerBlocks']  = array();
				$block['innerHTML']    = '';
				$block['innerContent'] = array();
			}

			if ( isset( $block['innerHTML'] ) && is_string( $block['innerHTML'] ) ) {
				$block['innerHTML'] = self::detach_form_shortcodes( $block['innerHTML'], $shortcodes );
			}

			if ( isset( $block['innerContent'] ) && is_array( $block['innerContent'] ) ) {
				foreach ( $block['innerContent'] as $key => $chunk ) {
					if ( is_string( $chunk ) ) {
						$block['innerContent'][ $key ] = self::detach_form_shortcodes( $chunk, $shortcodes );
					}
				}
			}

			if ( ! empty( $block['innerBlocks'] ) && is_array( $block['innerBlocks'] ) ) {
				$block['innerBlocks'] = self::detach_forms_in( $block['innerBlocks'], $blocks, $shortcodes );
			}

			$list[ $index ] = $block;
		}

		return $list;
	}

	/**
	 * Point form shortcodes in a piece of markup at no form.
	 *
	 * @param string   $html       Markup.
	 * @param string[] $shortcodes Shortcode tags that embed a form.
	 * @return string
	 */
	private static function detach_form_shortcodes( $html, $shortcodes ) {
		foreach ( $shortcodes as $shortcode ) {
			if ( false === stripos( $html, '[' . $shortcode ) ) {
				continue;
			}

			$html = (string) preg_replace(
				'/(\[' . preg_quote( $shortcode, '/' ) . '(?=[\s\]\/])[^\]]*?\bid=)(["\']?)[^"\'\s\]]*\2/i',
				'${1}${2}0${2}',
				$html
			);
		}

		return $html;
	}

	/**
	 * An active plugin that does the job of one a demo asks for.
	 *
	 * Installing the free edition next to an active paid one helps nobody,
	 * and WPForms switches its free edition off again when it finds Pro.
	 *
	 * @param string $slug Plugin directory slug the demo names.
	 * @return string Plugin file of the active alternative, or empty.
	 */
	public static function active_alternative( $slug ) {
		$signatures = self::plugin_signatures();
		$others     = isset( $signatures[ $slug ]['providedBy'] ) ? (array) $signatures[ $slug ]['providedBy'] : array();

		if ( ! $others ) {
			return '';
		}

		if ( ! function_exists( 'get_plugins' ) ) {
			require_once ABSPATH . 'wp-admin/includes/plugin.php';
		}

		foreach ( array_keys( get_plugins() ) as $file ) {
			if ( in_array( dirname( $file ), $others, true ) && is_plugin_active( $file ) ) {
				return $file;
			}
		}

		return '';
	}

	/**
	 * Provenance meta key recording the import run that created an object.
	 */
	const META_RUN = '_pagecore_run_id';

	/**
	 * Provenance meta key recording which demo an object came from.
	 */
	const META_DEMO = '_pagecore_demo';

	/**
	 * Provenance meta key recording the object's id on the demo site.
	 */
	const META_SOURCE_ID = '_pagecore_source_id';

	/**
	 * Provenance meta key recording which demo site an object came from.
	 */
	const META_SOURCE_HOME = '_pagecore_source_home';

	/**
	 * Meta key recording the run that changed an object it did not create.
	 *
	 * Deliberately not META_RUN. That key means "PageCore made this, and
	 * removing the demo may delete it", and a record that was on the site
	 * before the import must never wear it.
	 */
	const META_MODIFIED_RUN = '_pagecore_modified_run_id';

	/**
	 * Meta key recording which demo changed an object it did not create.
	 */
	const META_MODIFIED_DEMO = '_pagecore_modified_demo';

	/**
	 * Meta key holding what an object's content was before an import changed it.
	 */
	const META_PREVIOUS_CONTENT = '_pagecore_previous_content';
}