uri-interfaces is the contract layer the League URI packages are written against

What this package is, and the warning in its README

The README opens with the package's purpose and then with a warning. The package contains an interface to represent URI objects according to RFC 3986. Then, in a callout, it says this is a sub-split, for development, pull requests and issues, visit the uri-src repository. That sentence is the most important thing in the file, and it changes what this repository is. It is a read-only split of the League URI common code, and the repository description calls it a common package with a READ-ONLY marker on it. Development happens in the parent uri-src repository, so an issue filed here or a pull request opened here goes to the wrong place. The licence is MIT, the default branch is master, the last push was on 2026-10-16, and the release list shows 7.9.0 published on 2026-10-16, 7.8.1 on 2026-03-15 and 7.8.0 on 2026-01-16. The full documentation lives at uri.thephpleague.com.

The file layout is the API surface

The top-level entries show a package built almost entirely out of interfaces and small value objects, and the names describe the URI model precisely. There is UriString.php and UriStringTest.php, plus UriStringBench.php for benchmarks, and QueryString.php with its own test and benchmark files. Host handling is split across HostFormat.php, HostRecord.php, HostType.php and HostRecordTest.php, with an IPv4 directory, an IPv6 directory, an Idna directory and a KeyValuePair directory. Then come the mode enums that describe how the library behaves under different circumstances: QueryComposeMode, QueryExtractMode, StringCoercionMode, UriComparisonMode and UrnComparisonMode, plus Occurrence.php for repeated query parameters. Contracts holds the interfaces themselves, and Exceptions holds the exception types. Encoder.php and FeatureDetection.php sit at the root, with an EncoderTest.php alongside. The design intent is clear from the names: this package is where the vocabulary of the URI model lives, and the concrete parsers elsewhere plug into it.

System requirements that become runtime exceptions

The README states PHP 8.1 or later is required, with the latest stable version recommended, and then lists two extension requirements that fail loudly rather than silently. The first concerns IDN hosts. Handling of an IDN host requires the presence of the intl extension, or a polyfill for the intl IDN functions such as symfony/polyfill-intl-idn, otherwise an exception is thrown when attempting to validate or interact with such a host. The second concerns IPv4 conversion, which requires at least one of the GMP extension, the BCMatch extension, or a 64-bits PHP version, otherwise an exception is thrown when attempting to convert a host as an IPv4 address. That second requirement is a portability trap worth spelling out. On a 32-bit PHP build without GMP or BCMatch, an application that otherwise looks fine will fail at the moment it tries to convert a host to an IPv4 address, which in practice means a runtime error in production on an environment nobody tested.

Installing with Composer, and who actually needs it

The installation instruction is one Composer command.

$ composer require league/uri-interfaces

That is the whole installation story, and for most PHP developers it is also the whole of the relevant story. This package does not parse URLs on its own. It defines the contracts that the concrete League URI packages implement, and the value objects that those implementations share. The repository topics list contracts-programming, php, uri and uri-interfaces, and the contracts-programming topic is the tell: this is an interface package, published so that a dependency can be required against a stable contract rather than against whichever concrete implementation happens to be installed. If you are writing an application that parses and builds URIs, you want one of the concrete packages. If you are writing a library that other libraries will plug into, this is the thing you require.

Feature detection and the comparison mode enums

Two root-level files point at how the library handles environment differences. FeatureDetection.php is the mechanism by which the package checks for the capabilities the README's requirements describe, and it is what lets the same code run on a host with intl and on a host without it, provided the polyfill is present. The mode enums are the other mechanism, and they are the interesting design choice. Rather than a bag of boolean flags on a method signature, the library enumerates the decisions. QueryComposeMode covers how query parameters are composed, QueryExtractMode covers how they are extracted, StringCoercionMode covers when a value is cast to string, UriComparisonMode covers how two URIs are judged equal, and UrnComparisonMode does the same for URNs, where the rules differ from ordinary URIs. The presence of a dedicated URN comparison mode is the detail that tells you the model is not a thin wrapper over a generic URI string but an attempt to cover the corners of RFC 3986 and its relatives.

Where uri-interfaces is the wrong tool

Three cases. The first is the obvious one. If you want to parse a URL in PHP, this package will not do it, because it holds contracts and value objects rather than a parser, and the README points at the documentation site for the concrete implementations. The second is the read-only warning, and it is a real operational issue rather than a formality. Because development happens in uri-src, a fork of this repository will drift from the parent, and a pull request submitted here is directed at a split that is regenerated from elsewhere. The third is the exception behaviour. Both documented extension requirements surface as thrown exceptions at the point of use rather than as a capability check you can branch on, so an application that supports internationalised host names on one deployment and not another needs its own handling. The mitigation is the polyfill, and the polyfill is a dependency you now carry. Whether that is acceptable depends on whether your target environments include 32-bit PHP builds or hosts without intl, which in a modern containerised deployment is increasingly a non-issue and in a shared hosting environment is not.

Editorial conclusion

Adopt uri-interfaces only if you are implementing a URI object or building against the League URI ecosystem, since it contains contracts rather than a usable URI parser of its own. Skip it if you just need to parse and build URLs, since the concrete packages in the League URI family do that. Before you depend on it, check the intl requirement for internationalised host names and the GMP or BCMath requirement for IPv4 conversion, because both throw exceptions when the extension is missing rather than degrading quietly.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. thephpleague/uri-interfaces on GitHub