- What is league/uri-components used for in a Laravel app?
- It provides immutable value objects for URI components such as Scheme, Host, Domain, Path, Query, Port, UserInfo and Fragment, with with/without copy-based mutation. In Laravel it is useful for parsing, validating, normalizing and composing URLs, hosts, paths and query strings outside the request/response layer. It fits form requests, jobs, API clients and multi-tenant routing where parse_url and parse_str are too loose.
- How do I install league/uri-components in Laravel?
- Run composer require league/uri-components. There is no service provider, facade, config publishing or registration step; the package is PSR-4 autoloaded and framework-agnostic. You can call it from form requests, jobs, API clients or a thin service abstraction.
- Which Laravel and PHP versions support league/uri-components?
- It requires PHP 8.1 or newer, which Laravel 10, 11 and 12 satisfy, noting that Laravel 11+ requires PHP 8.2. It is not tied to a Laravel version because it is a framework-agnostic Composer package. Verify that your production, queue-worker and CI images all meet the PHP and extension requirements.
- Does league/uri-components require the intl extension?
- Handling IDN or Unicode hosts requires intl or a polyfill such as symfony/polyfill-intl-idn. Without either, validating or interacting with such hosts throws an exception rather than silently degrading. If you only handle ASCII hostnames, intl may not be exercised.
- What are the requirements for IPv4 host conversion in league/uri-components?
- Converting a host to or from IPv4 requires GMP, BCMath, or a 64-bit PHP build. Otherwise an exception is thrown when conversion is attempted. These are runtime requirements, so check web, Horizon/queue, scheduler and container images identically.
- Is league/uri-components a PSR-7 request/response replacement?
- No. It provides immutable URI component value objects and only depends on psr/http-message as an interface; it does not replace Laravel's Symfony HttpFoundation request/response stack. Treat it as a validation, normalization and composition layer beneath the framework.
- Why does league/uri-components throw exceptions on invalid URIs?
- Malformed input throws instead of returning false like parse_url, which is deliberate but shifts responsibility to your boundary code. Wrap calls in try/catch in form requests, middleware, jobs and redirect handling, and define a fallback so bad user input or headers do not become 500s. Keep the exception contract in a thin adapter rather than spreading catches through controllers.
- Can league/uri-components handle IDN hosts and registrable domain logic?
- Yes. The Domain and Host objects support IDN or Unicode hosts plus public-suffix and registrable-domain logic such as isSubdomainOf, commonAncestorWith and parentHost. That is useful for multi-tenant subdomains, cookie scoping and SSRF allowlists. Confirm you actually need this, because simple URL validation may not justify the extra runtime requirements.
- Does league/uri-components write files at runtime?
- Yes, the Host domain resolver can lazily write a public-suffix cache into a vendor subdirectory with a seven-day TTL. That is a real operational consideration for read-only filesystems, containers and Lambda-style deployments. Test it in your target environment and account for cache permissions or warming if you rely on registrable-domain logic.
- Should I depend on league/uri-components or the parent league/uri package?
- This repository is a read-only sub-split generated from league/uri-src, so issues and PRs go upstream and you cannot patch it in place. Its stars and dependents understate real usage; evaluate the parent league/uri package and audit composer.lock for constraints pinning league/uri or league/uri-interfaces. Version coupling is exact, so plan for semver-disciplined major upgrades roughly every 12 to 18 months.