22

✏️ Editing: DependencyDetection.php

<?php
declare( strict_types = 1 );

namespace Automattic\WooCommerce\Blocks;

use Automattic\WooCommerce\Internal\Utilities\BlocksUtil;

/**
 * DependencyDetection class.
 *
 * Provides runtime detection of extensions that use Blocks related WooCommerce globals
 * (window.wc.*) without properly declaring their PHP script dependencies.
 *
 * This runs by default to warn developers about missing dependencies.
 *
 * @since 10.5.0
 * @internal
 */
final class DependencyDetection {

/**
	 * WooCommerce blocks that use the tracked globals.
	 *
	 * Detection script only runs on pages containing these blocks.
	 *
	 * @var array<string>
	 */
	private const TRACKED_BLOCKS = array(
		'woocommerce/checkout',
		'woocommerce/cart',
		'woocommerce/mini-cart',
	);

/**
	 * Maps window.wc.* property names to their required script handles.
	 *
	 * This is the source of truth for both PHP and JS dependency detection.
	 * Based on wcDepMap and wcHandleMap in client/blocks/bin/webpack-helpers.js.
	 *
	 * @var array<string, string>
	 */
	private const WC_GLOBAL_EXPORTS = array(
		'wcBlocksRegistry'      => 'wc-blocks-registry',
		'wcSettings'            => 'wc-settings',
		'wcBlocksData'          => 'wc-blocks-data-store',
		'data'                  => 'wc-store-data',
		'wcBlocksSharedContext' => 'wc-blocks-shared-context',
		'wcBlocksSharedHocs'    => 'wc-blocks-shared-hocs',
		'priceFormat'           => 'wc-price-format',
		'blocksCheckout'        => 'wc-blocks-checkout',
		'blocksCheckoutEvents'  => 'wc-blocks-checkout-events',
		'blocksComponents'      => 'wc-blocks-components',
		'wcTypes'               => 'wc-types',
		'sanitize'              => 'wc-sanitize',
	);

/**
	 * Whether the proxy script was output.
	 *
	 * Used to ensure we only output the registry if the proxy was set up.
	 *
	 * @var bool
	 */
	private bool $proxy_output = false;

/**
	 * Constructor.
	 */
	public function __construct() {
		$this->init();
	}

/**
	 * Initialize hooks.
	 *
	 * @since 10.5.0
	 */
	public function init(): void {
		// Only run when debugging is enabled.
		if ( ! defined( 'WP_DEBUG' ) || ! WP_DEBUG ) {
			return;
		}

// Output an early inline script to set up the Proxy before any other scripts run.
		add_action( 'wp_head', array( $this, 'output_early_proxy_setup' ), 1 );
		add_action( 'admin_head', array( $this, 'output_early_proxy_setup' ), 1 );

// Output registry late when all scripts (including IntegrationInterface) are registered.
		add_action( 'wp_print_footer_scripts', array( $this, 'output_script_registry' ), 1 );
		add_action( 'admin_print_footer_scripts', array( $this, 'output_script_registry' ), 1 );
	}

/**
	 * Output early inline script to set up the Proxy on window.wc.
	 *
	 * This must run before any WooCommerce scripts to intercept access.
	 * The script is loaded from a separate file for better IDE support and testing,
	 * but output inline to ensure correct timing (before any enqueued scripts).
	 *
	 * @since 10.5.0
	 */
	public function output_early_proxy_setup(): void {
		// Only run on pages that have the tracked blocks.
		if ( ! $this->page_has_tracked_blocks() ) {
			return;
		}

// Load from the production assets directory (built by webpack and copied during release build).
		$script_path = __DIR__ . '/../../assets/client/blocks/dependency-detection.js';

if ( ! file_exists( $script_path ) ) {
			return;
		}

// phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- Local file read for inline script output.
		$script_content = file_get_contents( $script_path );

if ( ! $script_content ) {
			return;
		}

// Inject the global-to-handle mapping from PHP (source of truth).
		$mapping_json = \wp_json_encode( self::WC_GLOBAL_EXPORTS );
		if ( false === $mapping_json ) {
			return;
		}
		$script_content = str_replace(
			'__WC_GLOBAL_EXPORTS_PLACEHOLDER__',
			$mapping_json,
			$script_content
		);

// Inject the WooCommerce plugin URL for script origin detection.
		// This accounts for custom plugin directories (WP_PLUGIN_DIR, WP_CONTENT_DIR).
		$wc_plugin_url  = \plugins_url( '/', WC_PLUGIN_FILE );
		$script_content = str_replace(
			'__WC_PLUGIN_URL_PLACEHOLDER__',
			'"' . esc_js( $wc_plugin_url ) . '"',
			$script_content
		);

// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- Script content is from a trusted local file, JSON is safely encoded.
		echo '<script id="wc-dependency-detection">' . $script_content . '</script>' . "\n";

$this->proxy_output = true;
	}

/**
	 * Output the script registry JSON for dependency checking.
	 *
	 * This runs late (wp_print_footer_scripts) to ensure all scripts,
	 * including those registered via IntegrationInterface, are captured.
	 *
	 * @since 10.5.0
	 */
	public function output_script_registry(): void {
		// Only output registry if the proxy was set up earlier.
		// This avoids the duplicate page_has_tracked_blocks() check and ensures
		// we don't output a registry without a proxy to consume it.
		if ( ! $this->proxy_output ) {
			return;
		}

// Build the script registry mapping URLs to handles and dependencies.
		$script_registry = $this->build_script_registry();
		$registry_json   = \wp_json_encode( $script_registry );

if ( false === $registry_json ) {
			return;
		}

// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- JSON is safely encoded by wp_json_encode.
		echo '<script id="wc-dependency-detection-registry">if(typeof window.wc.wcUpdateDependencyRegistry==="function"){window.wc.wcUpdateDependencyRegistry(' . $registry_json . ');}</script>' . "\n";
	}

/**
	 * Build a registry of all enqueued scripts with their URLs and dependencies.
	 *
	 * @return array<string, array{handle: string, deps: array<string>}>
	 */
	private function build_script_registry(): array {
		$wp_scripts = wp_scripts();
		$registry   = array();

foreach ( $wp_scripts->registered as $handle => $script ) {
			// Skip scripts without a source URL.
			if ( empty( $script->src ) ) {
				continue;
			}

// Get the full URL.
			$src = $script->src;
			if ( ! is_string( $src ) ) {
				// Skip malformed src.
				continue;
			}
			if ( ! preg_match( '|^(https?:)?//|', $src ) ) {
				// Relative URL - make it absolute.
				$src = $wp_scripts->base_url . $src;
			}

// Skip WooCommerce's own scripts - we don't need to check those.
			if ( $this->is_woocommerce_script( $src ) ) {
				continue;
			}

// Skip WordPress core scripts - they won't use wc.* globals.
			if ( $this->is_wordpress_core_script( $src ) ) {
				continue;
			}

// Normalize the URL for consistent matching.
			$src = $this->normalize_url( $src );

$registry[ $src ] = array(
				'handle' => $handle,
				'deps'   => $this->get_all_dependencies( $script->deps ),
			);
		}

return $registry;
	}

/**
	 * Check if a script URL belongs to WooCommerce core.
	 *
	 * Checks if the script is loaded from the WooCommerce core plugin directory,
	 * not from third-party extensions that may use similar handle naming.
	 *
	 * @param string $url Script URL.
	 * @return bool
	 */
	private function is_woocommerce_script( string $url ): bool {
		// Get the WooCommerce plugin URL (accounts for custom plugin directories).
		$wc_plugin_url = \plugins_url( '/', WC_PLUGIN_FILE );

// Check if the URL starts with the WooCommerce plugin URL and is in a known subdirectory.
		if ( strpos( $url, $wc_plugin_url ) !== 0 ) {
			return false;
		}

// Get the path after the WooCommerce plugin URL.
		$relative_path = substr( $url, strlen( $wc_plugin_url ) );

// Check if it's in one of the known WooCommerce asset directories.
		return (bool) preg_match( '#^(client|assets|build|vendor)/#', $relative_path );
	}

/**
	 * Check if a script URL belongs to WordPress core.
	 *
	 * WordPress core scripts (wp-includes, wp-admin) won't use wc.* globals,
	 * so we can skip them to reduce registry size.
	 *
	 * @param string $url Script URL.
	 * @return bool
	 */
	private function is_wordpress_core_script( string $url ): bool {
		return (bool) preg_match( '#/(wp-includes|wp-admin)/#', $url );
	}

/**
	 * Recursively get all dependencies including nested ones.
	 *
	 * @param array<string> $deps Direct dependencies.
	 * @return array<string> All dependencies (flattened).
	 */
	private function get_all_dependencies( array $deps ): array {
		$wp_scripts      = wp_scripts();
		$all_deps        = array();
		$deps_to_process = $deps;

while ( ! empty( $deps_to_process ) ) {
			$handle = array_shift( $deps_to_process );

if ( in_array( $handle, $all_deps, true ) ) {
				continue;
			}

$all_deps[] = $handle;

// Add nested dependencies to process.
			if ( isset( $wp_scripts->registered[ $handle ] ) ) {
				foreach ( $wp_scripts->registered[ $handle ]->deps as $nested_dep ) {
					if ( ! in_array( $nested_dep, $all_deps, true ) ) {
						$deps_to_process[] = $nested_dep;
					}
				}
			}
		}

// Filter to only include WooCommerce handles we care about.
		$wc_handles = array_values( self::WC_GLOBAL_EXPORTS );
		return array_values(
			array_filter(
				$all_deps,
				function ( $dep ) use ( $wc_handles ) {
					return in_array( $dep, $wc_handles, true );
				}
			)
		);
	}

/**
	 * Check if the current page contains any of the tracked blocks.
	 * Checks post content, widget areas, and template parts (header) for blocks.
	 *
	 * @return bool True if page has tracked blocks.
	 */
	private function page_has_tracked_blocks(): bool {
		// Check post content for blocks.
		foreach ( self::TRACKED_BLOCKS as $block_name ) {
			if ( \has_block( $block_name ) ) {
				return true;
			}
		}

// Check widget areas for mini-cart (classic themes).
		$mini_cart_in_widgets = BlocksUtil::get_blocks_from_widget_area( 'woocommerce/mini-cart' );
		if ( ! empty( $mini_cart_in_widgets ) ) {
			return true;
		}

// Check header template part for mini-cart (block themes).
		try {
			$mini_cart_in_header = BlocksUtil::get_block_from_template_part( 'woocommerce/mini-cart', 'header' );
			if ( ! empty( $mini_cart_in_header ) ) {
				return true;
			}
		} catch ( \Throwable $e ) { // phpcs:ignore Generic.CodeAnalysis.EmptyStatement.DetectedCatch
			// Template part may not exist in all themes, silently continue.
		}

return false;
	}

/**
	 * Normalize a URL by removing query strings and hash fragments.
	 *
	 * This helps match URLs in stack traces which don't include query strings.
	 *
	 * @param string $url URL to normalize.
	 * @return string Normalized URL without query string or hash.
	 */
	private function normalize_url( string $url ): string {
		$scheme = wp_parse_url( $url, PHP_URL_SCHEME );
		$host   = wp_parse_url( $url, PHP_URL_HOST );
		$path   = wp_parse_url( $url, PHP_URL_PATH );

if ( $scheme && $host && $path ) {
			$port = wp_parse_url( $url, PHP_URL_PORT );
			return $scheme . '://' . $host . ( $port ? ':' . $port : '' ) . $path;
		}

return $url;
	}
}

MR SKB