Download the PHP package bentools/url-pattern without Composer

UrlPattern

A PHP implementation of the WHATWG URL Pattern Standard (the URLPattern web API), validated against the official web-platform-tests suite.

WPT conformance: 369/369 cases of urlpatterntestdata.json pass on PHP 8.3, 8.4 and 8.5, with no skipped case.

Installation

Requirements: PHP >= 8.3 with ctype and mbstring, and PCRE2 >= 10.40 (for \p{ID_Start}; always true with the PCRE2 bundled with PHP, check it only if PHP is linked against a system library). intl is recommended on PHP < 8.5 (faster IDNA).

Usage

Creating a pattern

An invalid pattern throws BenTools\UrlPattern\Exception\InvalidPatternException (the equivalent of the JavaScript TypeError).

The normalized component patterns are exposed as read-only properties:

Matching

test() and exec() accept a URL string (with an optional base URL) or an array of component values. They never throw on an invalid URL: they return false / null. The only exception is a programming error: passing a base URL along with an array input throws an InvalidArgumentException.

URLPatternResult exposes inputs, plus one URLPatternComponentResult (input, groups) per component: protocol, username, password, hostname, port, pathname, search, hash. A group that did not participate in the match is null (undefined in JavaScript). Anonymous groups are numbered from 0, and, PHP being PHP, their keys are integers.

Options

An invalid option value throws an InvalidPatternException.

Performance

Patterns are compiled once, in the constructor. URLPattern instances are immutable (readonly) and can be shared and cached freely. There is no global cache in the library: if you build patterns from user input, keep an LRU cache of compiled instances on your side.

Indicative figures (Apple Silicon, https://example.com/books/:id):

Matching a URL string is dominated by URL parsing: on PHP < 8.5, matching against an array of components (which skips the parser), or upgrading to PHP 8.5, is much faster.

URL parser

The encoding callbacks of the specification rely on the WHATWG URL parser. This library uses Uri\WhatWg\Url, which is native since PHP 8.5, and backported to PHP 8.3/8.4 by league/uri-polyfill (itself built on rowbot/url). On PHP 8.5, the polyfill is inert and the native implementation is used.

Why league/uri-polyfill rather than rowbot/url directly: a single API (Uri\WhatWg\Url) across versions, and the native, much faster parser on PHP 8.5, while the polyfill still delegates to rowbot/url, a WPT-compliant parser, on older versions. PSR-7 / RFC 3986 URI libraries are not suitable: URL patterns require WHATWG semantics (IDNA, IPv4 normalization, backslashes, special schemes...).

Uri\WhatWg\Url does not expose the "state override" entry points of the URL parser that the encoding callbacks use, so the corresponding parser states (port, path, opaque path, query, fragment, userinfo encoding) are reimplemented in Internal\Canonicalizer; the URL parser is used for scheme validation and host parsing.

The native parser of PHP 8.5.1 deviates from the URL standard in two places, which the library normalizes itself:

• it does not lowercase percent-decoded code points of special hosts (https://%41.com/ yields A.com instead of a.com);
• it does not percent-encode ^ in paths (https://example.com/a^b keeps /a^b instead of /a%5Eb).

Differences with the specification

The specification compiles patterns into ECMAScript regular expressions (with the v flag). PHP has no ECMAScript regex engine, so the generated expressions are translated to PCRE2 (/u). The translator validates the ECMAScript syntax (it rejects what a JavaScript engine rejects, e.g. \m, (?R) or \H, which PCRE would accept) and preserves the ECMAScript semantics where PCRE differs:

Other notes:

• Strings are converted like WebIDL USVStrings: invalid UTF-8 sequences become U+FFFD.
• Unknown keys of an init array are ignored (like JavaScript dictionaries); non-string values are rejected.
• The undefined value of a group is null.

Security (ReDoS)

URL patterns may come from untrusted sources (e.g. Mercure subscribers), and a malicious regular expression can make a backtracking engine run for ages, freezing a single-threaded event loop. The library defends in depth:

1. Linear-time guard (at construction): user-provided regexp groups whose structure is prone to catastrophic backtracking are rejected with an InvalidPatternException. That is a repeated sub-expression (*, +, {n,}, {n,m} with m > 1, or a URLPattern */+ modifier) containing an unbounded quantifier, e.g. (a+)+, (?:a*)*, ((a+)){2,}. Backreferences are rejected too. This is a deliberate deviation from the specification. It is a heuristic, not a proof of linearity, hence the next layer.
2. Bounded matching (at match time): every test()/exec() call temporarily sets pcre.backtrack_limit (PCRE2's match limit) to the backtrackLimit option, and restores the previous value afterwards. The limit applies to each component match: with the default of 100,000, a hostile component costs about a millisecond with the PCRE JIT, and a whole call at most 8 times that. The limit is also enforced by the JIT, which therefore stays enabled. Without the JIT (pcre.jit=0, or a platform refusing executable memory), each unit of the limit is far more expensive: a hostile component can cost about half a second with the default limit, so lower backtrackLimit accordingly (e.g. 10,000) or keep the JIT enabled. Note that patterns without any regexp group can be polynomial or even exponential too (e.g. *a*a*a*b, or /x:a+, which behaves like (a+)+); this layer covers them.
3. Fail as no match: any PCRE error (limit exhausted, JIT stack limit, ...) results in false / null, never in an exception or a warning.

If ini_set() is disabled on your platform, the process-wide pcre.backtrack_limit applies instead (PHP's default is 1,000,000).

Recommendations for untrusted patterns:

• Cache compiled patterns (LRU) instead of compiling them on every request.
• Bound the length of patterns and URLs you accept.
• If you do not need custom regular expressions, reject patterns where $pattern->hasRegExpGroups is true, as the specification itself suggests. This narrows the attack surface, but does not replace the backtracking limit (see the regexp-free examples above).

Development

The WPT fixtures are vendored in tests/Fixtures.

License

MIT.