Uri Parser Laravel Package

Getting Started

league/uri-parser is a small, dependency-free library that does exactly one thing: split a URI string into its RFC 3986 components. It does not build, normalize, validate, or resolve URIs — that is left to league/uri and league/uri-components.

Install it (PHP 7.0+; ext-intl must be present and correctly configured as of 1.4.1):

composer require league/uri-parser:^1.4.1

First use case — splitting an absolute URL into parts:

use League\Uri\Parser;

$parser = new Parser();
$components = $parser->parse('https://user:[email protected]:8080/path/to?q=1#frag');

// [
//   'scheme'    => 'https',
//   'user_info' => 'user:pass',
//   'host'      => 'example.com',
//   'port'      => 8080,
//   'path'      => '/path/to',
//   'query'     => 'q=1',
//   'fragment'  => 'frag',
// ]

Where to look first:

1. The Parser class — it exposes parse(), plus component-level methods: parseScheme(), parseUserInfo(), parseHost(), parsePort(), parsePath(), parseQuery(), parseFragment(), parseAuthority().
2. The README examples for the exact return shape.
3. The RFC 3986 Appendix B regex in the source if you need to understand edge cases — but note that as of 1.4.1 the scheme is no longer taken from a naive regex split; scheme detection now follows RFC 3986 §3.1 (ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )) via issue #19.

The first realistic use case is ingesting a URL from user input, config, or a log line and needing its parts before handing them to a different library (e.g. league/uri-schemes, a database column splitter, or a routing layer).

Implementation Patterns

Parse-then-reassemble. Because parse() returns a flat array, the common workflow is:

$parts = (new Parser())->parse($uri);
$parts['host'] = strtolower($parts['host']);      // RFC 3986 case-folding
$parts['scheme'] = strtolower($parts['scheme']);
// rebuild using http_build_url(), league/uri, or manual concat

Parse a single component. If you only care about the query string or the authority, call the focused method instead of running the full parser:

$parser->parseQuery('a=1&b=2');
$parser->parseAuthority('user:[email protected]:8080');
$parser->parsePath('/a/b/c');
$parser->parseScheme('HTTPS');    // stricter since 1.4.1

Wrap in try/catch for user input — and catch two different failure modes. Parsing failures and environment failures now throw different exception types, so catch them separately and log accordingly:

use League\Uri\Parser;

try {
    $parts = (new Parser())->parse($raw);
} catch (\UnexpectedValueException $e) {
    // 1.4.1+: Intl extension missing/misconfigured on this host.
    // This is an infrastructure bug, not bad user input — alert, don't reject.
    report($e);
    throw $e;
} catch (\Exception $e) {
    // genuinely unsplittable input — reject or fall back
}

Compensate for what the parser deliberately omits. Day-to-day you'll almost always pair it with:

• Normalization (lowercasing scheme/host, default ports, dot-segment removal).
• Percent-encoding validation — the parser splits, it does not validate %XX sequences.
• IDN → punycode conversion for hostnames.
• Relative-reference resolution (UriResolver lives in league/uri, not here).

Integration pattern — request/log pipelines. A common shape is a small UriComponents value object that wraps the array, exposes scheme(), host(), port(), etc., and centralizes the normalization rules so every consumer sees consistent output. Put the UnexpectedValueException handling in this wrapper so callers never have to think about it.

Component-level composition. Use parseAuthority() when you already know you have an authority-only string (e.g. reading Host + credentials from a config), and skip the full parser round-trip.

Pin and test the runtime, not just the version. Because 1.4.1 adds a hard environment precondition, add a CI job (and a health check) that constructs new Parser() and parses one URI, so a broken ICU setup fails the build rather than production traffic.

Gotchas and Tips

• The package is superseded, but not frozen. The parsing logic was folded into league/uri / league/uri-components, which is where new work happens. Patch releases like 1.4.1 do still land. For new code, install league/uri and use League\Uri\UriString::parse() (or the Parser class shipped there) — the maintained equivalent. Only reach for league/uri-parser if you are pinned to an old dependency tree.
• New in 1.4.1 — Intl is now a hard runtime dependency in practice. Parser throws UnexpectedValueException if the Intl extension is misconfigured for the PHP/OS platform. This is the classic ICU-data-mismatch situation: Alpine/Docker images, distros where php-intl lags the system ICU, or a PHP upgrade without the matching intl build. It is not a parse failure — don't let it fall into your "invalid URL" branch.
• New in 1.4.1 — scheme detection changed (issue #19). Scheme parsing now follows RFC 3986 more strictly, so inputs that used to yield a bogus scheme key may now come back as path-only, and vice versa. If you have fixtures or a DB of stored URIs, re-run them after the bump and diff the resulting arrays before deploying. Strings like 1abc://x, ://x, or drive-letter-looking prefixes such as C:/path are the ones most likely to shift.
• PHP 7.0 era code. It was not comprehensively tested against PHP 8.x. Expect possible deprecation notices (especially around nullability) if you run it on a modern runtime — and note the Intl check above surfaces far more often on 8.x images. Test before shipping on 8.1+.
• Return array is sparse. Keys like port, user_info, query, and fragment are absent when the URI does not contain them. Always use $parts['port'] ?? null rather than assuming the key exists.
• Ports come back as integers, not strings — a mismatch if you're comparing against raw request data.
• No normalization is performed. Scheme and host case, default ports (:80 vs none), empty fragments, and percent-encoding are all preserved verbatim. If downstream code does string comparison on hosts, normalize yourself or you'll get example.com ≠ EXAMPLE.com.
• No validation of the components. Syntax splitting succeeds even for semantically invalid values (e.g. a non-numeric port that slipped through). Don't treat a clean parse as a valid URI.
• Relative references are not resolved. parse('../a/b') gives you a path component; it does not apply remove_dot_segments or resolve against a base URI. Use league/uri for resolution.
• IDN hosts are returned as-is. No punycode/Unicode conversion — handle it explicitly if you accept internationalized hostnames.
• Debugging tip: var_export($parser->parse($uri)) first — the array shape tells you immediately whether your bug is in parsing (missing/extra key) or in your downstream normalization. If you instead get an UnexpectedValueException, skip the debugger and check php -m | grep intl and php -i | grep ICU.
• Long-term support: pin ^1.4.1 (not a floating constraint) in composer.json and consider vendoring the ~single-class parser, since upstream work has moved to league/uri and no further patches are guaranteed.