Url Laravel Package

Product Decisions This Supports

• Security-boundary decisions on user-supplied URLs. Any surface that accepts a URL from a user — profile/website fields, webhook endpoints, "import from URL," avatar fetch, callback/redirect targets — creates a parser-differential risk: PHP's parse_url() and the browser's URL parser disagree on host, scheme, and path for the same string. A WHATWG-compliant parser lets us validate the same interpretation the browser and any downstream HTTP client will use, which directly supports go/no-go on features like user-configured webhooks and outbound fetches (SSRF allowlisting, open-redirect prevention).
• Build vs. buy for URL handling. This is a buy: MIT-licensed, pure PHP, no framework coupling, no service provider needed. The alternative is us hand-rolling normalization, percent-encoding, IDN/punycode, IPv6 bracket handling, default-port stripping, and relative-reference resolution — all of which are spec-surface we would get subtly wrong. Buying frees engineering to work on the feature, not the RFC.
• Canonicalization as a product feature. WHATWG parsing gives us a deterministic serialized form, which underpins: canonical URLs for SEO (rel=canonical, sitemap generation), duplicate-content detection, dedupe of submitted links in a feed or directory product, and stable cache keys for URL-keyed resources. The package's query-string handling additionally supports UTM/tracking-param stripping and allowlist matching on a normalized param set rather than raw strings.
• Roadmap sequencing for "link-aware" features. Link previews/unfurling, oEmbed, RSS/Atom ingestion, short-link expansion, affiliate-parameter rewriting, and URL-based integrations all sit on the same primitive. Standardizing on one parser now turns each of those from a bespoke effort into a thin layer on top — a sequencing argument for doing the URL primitive early rather than per-feature.
• Risk/vendor decisions. With ~19 stars, zero dependents, and a single maintainer, this is an unproven dependency. That is itself a product decision: adopt behind a thin internal UrlParser interface so swapping to league/uri or guzzlehttp/psr7 is a one-file change, and so the choice never leaks into domain code.
• Support-cost decisions. Malformed or ambiguous URLs are a recurring source of "the link doesn't work" tickets. Spec-compliant parsing plus explicit failure modes (rather than silent coercion) lets us decide deliberately whether to reject, sanitize, or best-effort-repair an input, and to surface a clear error to the user instead of a downstream 500.

When to Consider This Package

Adopt when:

• You accept arbitrary, untrusted URLs and the parsed result crosses a trust boundary (outbound HTTP request, redirect target, allowlist check, signed-URL comparison).
• You need behavior that matches browsers, not RFC 3986 — e.g. backslash handling, whitespace trimming, default-port and dot-segment normalization, IDN/host canonicalization.
• You need relative-reference resolution (urljoin) without writing it yourself.
• You want structured query-string parse/build with correct encoding semantics rather than hand-splitting on & and =.
• You want a PSR-7 UriInterface implementation that can slot into an existing Guzzle/HTTP-client stack.
• The blast radius is containable: a pure-PHP, MIT library with no framework hooks is easy to isolate, and you're willing to write a ~50-line adapter plus a contract test suite.

Look elsewhere when:

• Supply-chain risk is unacceptable. 19 stars, 0 dependents, and one maintainer is not a track record. For a payments- or auth-critical path, prefer league/uri (mature, widely depended on, RFC 3986 + PSR-7) or the URI implementation already shipped with your HTTP client. Note the tradeoff: those are RFC 3986, not WHATWG, so they will not reproduce browser behavior on the messy inputs that motivate this package.
• You actually need RFC 3986 semantics (e.g. strict standards work, non-HTTP schemes where WHATWG's HTTP-oriented rules are a poor fit).
• You only need trivial parsing — parse_url() plus a known-host check is sufficient when inputs are trusted or constrained.
• You need active vendor support, SLAs, or a security-response commitment. None exists here.
• You need Laravel-native ergonomics (validation rule, facade, config) — you'll be writing that glue yourself.
• Verify first: maintenance cadence, test suite coverage of the WHATWG urltestdata.json corpus, PHP version support, and whether the reported 2026-10-03 release is real and not a metadata artifact.

How to Pitch It (Stakeholders)

To executives: We're adding URL-handling features (user-supplied links, webhooks, link previews, canonical URLs for SEO). Today we'd parse those with PHP's built-in function, which reads URLs differently than browsers do — the classic root cause of open-redirect and SSRF bypasses. This is a small, free (MIT) library that parses URLs exactly the way browsers do, so our validation and our HTTP client agree on what a link points to. Cost is a few days of integration; the payoff is closing a known class of security bug before we ship the feature, plus one shared primitive for every link feature on the roadmap. The main caveat is that it's a low-adoption, single-maintainer project, so we'll wrap it behind our own interface and keep the swap to a more established library to a one-file change.

To engineering: WHATWG-spec-compliant parser, pure PHP, no Laravel coupling, PSR-7 UriInterface, includes query-string parse/build and relative resolution. It closes the parse_url() vs. browser divergence (backslashes, whitespace, default ports, dot segments, IDN) that we'd otherwise have to patch around. Low adoption is the risk, not the code: it has ~19 stars and no dependents. So: consume it through a single internal adapter, pin the version, add contract tests around the WHATWG urltestdata fixtures, and don't let its types into domain models. If it goes stale, we replace the adapter with league/uri — at the cost of losing browser-identical behavior, which we should re-evaluate at that point.