League URI

League URI (league/uri) gives PHP applications a strict, standards-compliant way to work with URIs — parsing them into components, validating hosts and schemes, resolving relative references, and rebuilding URIs with a fluent, immutable API. It implements RFC 3986 (URI syntax), RFC 3987 (IRIs), and RFC 6570 (URI Templates), and ships PSR-7-compatible Uri and Http classes alongside dedicated Urn support.

The library is published as a read-only subtree split of the thephpleague/uri-src development monorepo — the canonical way PHP projects consume it is via composer require league/uri, with development, issues, and pull requests happening upstream in uri-src.

What You Get

• RFC 3986/3987-compliant Uri and Http value objects with full component access (scheme, host, path, query, fragment)
• A dedicated Urn class for RFC 8141 URN handling
• RFC 6570 URI Template expansion via the UriTemplate class
• A UriResolver for resolving relative URI references against a base URI
• PSR-7 UriFactoryInterface implementation (HttpFactory) for framework interoperability
• Optional IDN/IPv4/IPv6 host handling backed by intl, GMP, BCMath, or PHP polyfills

Common Use Cases

• Parsing and validating user-submitted or third-party URLs before storing or dispatching them
• Building URLs programmatically from components (query params, path segments) with guaranteed correct encoding
• Expanding RFC 6570 URI templates when calling APIs whose endpoints are template-defined (e.g. OpenAPI specs)
• Resolving relative links against a base URI when crawling or rendering HTML content
• Providing a PSR-7-compatible UriInterface implementation inside an HTTP middleware stack

Under The Hood

Architecture: Uri.php (~1,967 lines) is the core value object, implementing both PSR-7’s Psr\Http\Message\UriInterface and League’s own UriInterface, and internally delegates host validation to Idna\Converter, IPv4\Converter, and IPv6\Converter collaborators rather than inlining that logic. BaseUri.php factors out shared behavior (resolution, comparison, normalization) used by both Uri and the PSR-7-flavored Http class, and UriTemplate.php is a separate, self-contained RFC 6570 expansion engine with its own UriTemplate/ support namespace.

Tech Stack: PHP 8.1+ with declare(strict_types=1) throughout. The only hard composer dependencies are league/uri-interfaces (shared contracts across the League URI toolkit) and psr/http-factory; everything else — intl, dom, fileinfo, bcmath, gmp, symfony/polyfill-intl-idn, league/uri-components — is listed under suggest as an optional capability rather than a hard requirement, keeping the base install lean.

Code Quality: Every core class ships a matching *Test.php in the same repository (UriTest, HttpTest, BaseUriTest, UriTemplateTest, BuilderTest, FactoryTest, WsTest, FtpTest, DataTest, FileTest, UrnTest), and dedicated HttpBench.php/UriBench.php benchmark files track performance regressions. Modern PHP idioms are used throughout (Deprecated attribute, SensitiveParameter, enums via SchemeType), and a Psr7IntegrationTest.php specifically verifies compliance against the PSR-7 interface contract.

API Design: The immutable withX() method family mirrors PSR-7’s own convention, so developers already familiar with PSR-7 messages find the API immediately idiomatic; named factory methods (Uri::new(), Uri::fromServer()) further reduce constructor boilerplate. The trade-off is a large single class (Uri.php) with many capabilities (IDN, IPv4/IPv6, HTML anchor conversion) reachable from one object, which developers new to the library discover incrementally through the hosted documentation rather than the class alone.