Uri Laravel Package

Product Decisions This Supports

• Build vs. buy on URL handling. Any feature that parses, normalizes, or recomposes URLs — canonical link generation, redirect management, sitemap/feed URL building, UTM and query-param manipulation, webhook URL validation, multi-tenant subdomain routing — forces a build-or-adopt decision. This package is the "adopt" candidate: a PSR-7 UriInterface implementation that gives you RFC 3986-style parsing and immutable mutation (withScheme, withQuery, withPath) without pulling in a full HTTP message stack.
• Decoupling URL logic from the HTTP client. If your architecture already speaks PSR-7 (Guzzle, Symfony HttpClient with PSR-7 bridges, Laminas, or any middleware pipeline), adopting a standalone Uri means URL construction lives in a domain service rather than being entangled with request/response objects. That's a real maintainability argument for a roadmap item like "extract link generation into a shared service."
• Feature scoping for URL-heavy epics. Concrete places this class of library earns its keep: building outbound webhook targets from stored config, normalizing user-submitted URLs before dedupe/caching (so ?a=1&b=2 and ?b=2&a=1 collapse), rewriting pagination and filter links, generating signed URLs where the canonical string must be deterministic, and producing absolute URLs from route fragments in API responses.
• Dependency-risk decisions. This is where the PM value is highest and least comfortable: 0 stars, 0 dependents, and a [READ ONLY] marker in the description are strong signals of an unmaintained or archived fork. Choosing it is a decision to own an unowned dependency. That belongs in a build-vs-buy note in the epic, not buried in a composer.json diff.
• Not a differentiator. Nothing here is product-visible. It should never consume roadmap capacity beyond the adoption review; the user-facing decision is "do we handle URLs correctly and consistently," and this package is one interchangeable means to that end.

When to Consider This Package

Adopt only under a narrow set of conditions, all of which must hold:

• You need UriInterface and nothing more. No streams, no headers, no request/response objects. If you're already installing guzzlehttp/psr7 or nyholm/psr7 for their message factories, use their Uri and skip this entirely — a second PSR-7 implementation in the same process is a genuine source of instanceof and type-coercion bugs.
• You accept the maintenance burden. With 0 stars and 0 dependents, treat this as vendored code, not a dependency. That means: pin the version exactly, read the parser before trusting it, and budget for a fork if a URI edge case (IDN, empty path vs. /, percent-encoding normalization, relative resolution) bites you.
• The code is small enough to audit. A single-class URI implementation is realistically readable in an afternoon. If that's true here, the low adoption signal matters less than it would for a framework-scale package.
• You are already in the Windwalker ecosystem. The only scenario where the provenance is a feature rather than a risk.

Look elsewhere when: you need RFC 3986 resolution against a base URI, IDN/IRI support, or template expansion — league/uri is the mature answer and has the test suite to prove it. Look elsewhere when the dependency will be load-bearing in a security-sensitive path (URL validation for SSRF defense, redirect allowlisting); a zero-adoption parser is the wrong place to discover an encoding bug. And look elsewhere as a default: the honest recommendation for most Laravel teams is league/uri for URL semantics, guzzlehttp/psr7 if you're already in PSR-7, and Laravel's own UrlGenerator for route-based URL building.

How to Pitch It (Stakeholders)

To executives: We evaluated a small MIT-licensed library for URL parsing and manipulation — the kind of plumbing behind link generation, canonical URLs, and webhook addressing. Technically it does the job. Commercially the risk is one-sided: zero public adoption, zero downstream dependents, and a repository marked read-only, meaning no upstream maintenance. The cost isn't the license, it's the eventual ownership. Recommendation: do not adopt as a dependency. If we need this, we use a maintained equivalent — same capability, no orphaned code — and we treat URL normalization as a correctness requirement in the relevant epics rather than a library choice.

To engineering: The UriInterface contract is the right abstraction and worth keeping in our designs — it forces URL construction out of controllers and into testable services. But this implementation buys us that abstraction at the price of a dependency nobody maintains. Use a maintained PSR-7 implementation if we're already in that world, league/uri for anything involving parsing edge cases or base-URI resolution, and Laravel's UrlGenerator where routes are the source of truth. If someone wants this specific package, the bar is a written justification covering: what edge cases we've tested, who owns the fork, and what triggers removal.