Uri Laravel Package

Product Decisions This Supports

• URL canonicalization as a product feature. Canonical tags, sitemap generation, duplicate-content de-duplication, and analytics event normalization all depend on reducing equivalent URLs (HTTP://Example.com:80/a/../b?) to one form. A strict RFC 3986 parser with normalization semantics is the difference between "two links" and "one link" in your reporting.
• Build vs. buy for URL handling. The realistic options are: (a) parse_url() / Laravel's UrlGenerator + string helpers, (b) this package, (c) league/uri, (d) a hand-rolled parser. This assessment is the artifact that closes that decision and names the fallback.
• Safe redirect and outbound-link surfaces. Any feature that takes a user-supplied URL and later redirects to it (OAuth return URLs, marketing redirects, webhook targets, "continue to partner" flows) needs scheme/host decomposition before an allowlist check. Component-level parsing is a prerequisite for that policy.
• Link-building and campaign tooling. UTM builders, affiliate/referral link rewriting, short-link expansion, and deep-link composition all need deterministic query-string manipulation without clobbering existing parameters or encoding.
• HATEOAS / API pagination and link relations. Generating next/prev/self links by resolving relative references against a base URI is exactly RFC 3986 §5 reference resolution; this is a small but genuine API-surface decision.
• Multi-tenant and multi-domain routing. Per-tenant host/subdomain parsing and per-environment asset base URL construction benefit from immutable, comparable URI value objects rather than ad-hoc explode('/').
• Roadmap input: if URL identity or link hygiene shows up repeatedly in support tickets or data-quality complaints, this package is a cheap spike to size the problem before committing to a larger URL-service investment.
• Not a decision driver: SSRF protection, phishing detection, or any security boundary. This parses syntax; it does not resolve DNS or classify risk.

When to Consider This Package

Consider it when:

• You need RFC 3986-conformant component parsing and recomposition (scheme, authority, path, query, fragment) as a value object, not string surgery.
• You need relative reference resolution against a base URI — something parse_url() and most framework helpers do not give you.
• You want normalization and equality semantics (compare two URIs for identity rather than string equality).
• You want a small, MIT-licensed, framework-agnostic dependency with an API shape familiar to anyone who has used java.net.URI — relevant if you have JVM-experienced engineers or are porting logic from a Java service.
• You are prepared to pin the version, vendor or fork it, and write your own contract tests, because the adoption signals are thin.

Look elsewhere when:

• Adoption risk is disqualifying. 11 stars, 0 dependents, and a low opportunity score mean effectively zero ecosystem validation. There is no crowd to have found the edge cases for you.
• league/uri fits. It is the mature PHP option: broader RFC coverage, IDN/IRI handling, PSR-7/PSR-17 interop, active maintenance, and a real user base. Default to it unless you have a specific reason not to.
• You need non-ASCII / internationalized URIs. RFC 3986 covers ASCII URIs; IDNA and IRI handling are separate concerns. Verify before assuming coverage.
• You need streaming/PSR-7 request-target parsing. guzzlehttp/psr7 or your HTTP client's URI class is already in the tree.
• Your actual need is routing or URL generation inside Laravel. UrlGenerator and Route already do this; adding a parser is over-engineering.
• You need a vendor with a security response process. A single-maintainer package with no visible security policy is a poor place to put a trust boundary.
• You need an SLA, long-term support commitment, or indemnification. Not available here.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed, zero-cost library for parsing and rebuilding URLs correctly. The business value is narrow but real: cleaner canonical URLs, safer redirect allowlists, and fewer "the link didn't work" defects. The risk is that it is an 11-star package with a single maintainer and no downstream users — so the recommendation is not to adopt it as infrastructure. The recommendation is to spend a short spike evaluating it behind our own internal Uri interface, so the decision is reversible in an afternoon and we end up with either a validated dependency or a one-line swap to the established alternative. Cost: days, not weeks. Downside if we skip it: we keep paying for URL edge cases in bugs and dirty analytics data.

To engineering: It gives you an RFC 3986 parser plus immutable URI value objects with resolution and normalization — the parts parse_url() gets wrong and Laravel's helpers don't attempt. It will not do IDN, it will not do DNS or IP classification, and it is not a security control. Treat it as a syntax layer. Two conditions on adoption: (1) wrap it behind our own small interface so the vendor is swappable to league/uri without touching call sites, and (2) land a contract test suite covering our real-world URL corpus — percent-encoding, empty query vs. no query, default ports, .. segments, trailing slashes — before it goes near a user-facing path. Given 0 dependents and a low opportunity score, assume the edge cases are ours to find; budget for that or choose league/uri and skip the exercise.