Helper class for replacing $matches[] references in query strings without using eval().

Source: wp-includes/class-wp-matchesmapregex.php
Since: 2.9.0

Overview

This class provides a safe way to substitute $matches[n] placeholders in rewrite rule query strings with actual matched values from regex captures. It eliminates the security risk of using eval() for dynamic string replacement.

Primarily used internally by WordPress’s rewrite system to map URL regex captures to query parameters.

Properties

Methods

__construct()

Creates a new mapper and performs substitution.

public function __construct( string $subject, array $matches )

The result is immediately available in the $output property.

apply()

Static helper for one-liner substitution.

public static function apply( string $subject, array $matches ): string

Returns: String with all $matches[n] placeholders replaced.

Example:

$query = 'post_type=page&pagename=$matches[1]&page=$matches[2]';
$captures = array( 'about-us', '2' );
$result = WP_MatchesMapRegex::apply( $query, $captures );
// Result: 'post_type=page&pagename=about-us&page=2'

callback()

Internal callback for preg_replace_callback().

public function callback( array $matches ): string

Returns: URL-encoded replacement value, or empty string if index not found.

Note: Values are automatically urlencode()d for URL safety.

_map() (private)

Performs the actual regex replacement.

private function _map(): string

Returns: Subject string with all placeholders replaced.

Pattern Matching

The class matches $matches[n] where n is a positive integer (1-9 followed by any digits):

($matches[[1-9]+[0-9]*])

• $matches[1] ✓
• $matches[12] ✓
• $matches[0] ✗ (zero not allowed)
• $matches[] ✗ (index required)

Usage in WordPress

Used by the rewrite system when translating pretty permalinks to query strings:

// Internal WordPress usage in class-wp-rewrite.php
$query = WP_MatchesMapRegex::apply( $query, $matches );

Security Note

This class was introduced to eliminate eval() calls in the rewrite system. Prior to WordPress 2.9.0, placeholder substitution used preg_replace() with the e modifier, which is both deprecated and a security risk.