<?php
/**
 * Source types and markers (S-SRC, D-21).
 *
 * @package ForensixDigital
 */

declare(strict_types=1);

namespace ForensixDigital\Services\Sources;

defined( 'ABSPATH' ) || exit;

/**
 * Where a piece of rendered output comes from. Markers are HTML comments placed around output
 * during scan requests only: <!--fxd:s:type:ref--> ... <!--fxd:e:type:ref-->.
 */
final class Source {

	public const POST_CONTENT = 'post_content';
	public const ELEMENTOR    = 'elementor';
	public const MENU_ITEM    = 'menu_item';
	public const WIDGET       = 'widget';
	public const TEMPLATE     = 'template';
	public const POST_META    = 'post_meta';
	public const OPTION       = 'option';
	public const SEO_FIELD    = 'seo_field';
	public const SITE_FILE    = 'site_file';
	public const MEDIA        = 'media';

	private const PREFIX = 'fxd:';

	/**
	 * Source type.
	 *
	 * @var string
	 */
	public readonly string $type;

	/**
	 * Reference within the type: post id, "post:element", menu item id, widget id.
	 *
	 * @var string
	 */
	public readonly string $ref;

	/**
	 * Creates a source.
	 *
	 * @param string $type Source type.
	 * @param string $ref  Reference.
	 */
	public function __construct( string $type, string $ref = '' ) {
		$this->type = $type;
		$this->ref  = $ref;
	}

	/**
	 * Output that no marker surrounds: theme templates, plugins, wp_head/wp_footer.
	 */
	public static function template(): self {
		return new self( self::TEMPLATE );
	}

	/**
	 * Opening marker.
	 *
	 * @param string $type Source type.
	 * @param string $ref  Reference.
	 */
	public static function open( string $type, string $ref ): string {
		return '<!--' . self::PREFIX . 's:' . self::clean( $type ) . ':' . self::clean( $ref ) . '-->';
	}

	/**
	 * Closing marker.
	 *
	 * @param string $type Source type.
	 * @param string $ref  Reference.
	 */
	public static function close( string $type, string $ref ): string {
		return '<!--' . self::PREFIX . 'e:' . self::clean( $type ) . ':' . self::clean( $ref ) . '-->';
	}

	/**
	 * Wraps output in markers.
	 *
	 * @param string $html Output.
	 * @param string $type Source type.
	 * @param string $ref  Reference.
	 */
	public static function wrap( string $html, string $type, string $ref ): string {
		return self::open( $type, $ref ) . $html . self::close( $type, $ref );
	}

	/**
	 * Reads a comment's text. Returns [ 's' or 'e', Source ] for a marker, null otherwise.
	 *
	 * @param string $comment Comment text without <!-- and -->.
	 * @return array{0: string, 1: Source}|null
	 */
	public static function parse_marker( string $comment ): ?array {
		if ( 1 !== preg_match( '/^fxd:([se]):([a-z_]+):([A-Za-z0-9_:.-]*)$/', trim( $comment ), $m ) ) {
			return null;
		}
		return array( $m[1], new self( $m[2], $m[3] ) );
	}

	/**
	 * Keeps only characters that cannot break a comment or the marker syntax. "--" may not
	 * appear inside an HTML comment, so runs of hyphens become one.
	 *
	 * @param string $value Value.
	 */
	private static function clean( string $value ): string {
		return (string) preg_replace( '/-{2,}/', '-', (string) preg_replace( '/[^A-Za-z0-9_:.-]/', '', $value ) );
	}
}