Url Validator Laravel Package

Product Decisions This Supports

• Go/no-go on URL-fetching features. Any feature where a user supplies a URL and our server makes the request — webhook registration and delivery, link previews/unfurling, remote avatar and image import, RSS/feed ingestion, "import from URL" onboarding, PDF/screenshot generation, sitemap crawlers, AI agents with browsing tools, OAuth/OIDC discovery — is an SSRF entry point. This package is the guardrail that lets those features ship without every squad re-deriving the allow/deny rules.
• Build vs. buy on a security primitive. SSRF filtering looks like a one-afternoon task ("block localhost and 169.254.169.254") and is not. Doing it correctly means scheme allowlisting, DNS resolution checks, private/reserved/loopback/link-local/CGNAT ranges, IPv4-mapped/NAT64/6to4/Teredo unwrapping, hex and decimal hostname normalization, cloud-metadata hostnames for AWS/GCP/Kubernetes, and — critically — closing the gap between "validated" and "connected." Treat that as an adopt decision, not a sprint ticket. A hand-rolled regex here is a recurring source of pen-test findings.
• Architecture decision: validate-then-pin. The library returns the IP set the hostname resolved to so the HTTP client can connect to a known-good address instead of re-resolving. That is a real constraint: it determines which HTTP client we can use for fetches (Guzzle/cURL yes, many SDK wrappers no), whether redirects are followed manually, and whether a managed egress proxy is a better fit. Decide it before the first URL-fetching feature ships — retrofitting means rewriting the egress layer.
• Roadmap sequencing for platform hardening. If two or more teams are independently writing SSRF checks, that's the signal to standardize. A shared internal SafeUrlFetcher (wrapper + form-request rule + job-level re-validation + connection pinning) is a platform-team deliverable that unblocks several roadmaps at once and eliminates duplicate, divergent blocklists.
• Risk acceptance and attack-surface inventory. For endpoints that already accept URLs, this is a gap-closing candidate. It gives a defensible answer to "what stops a user from making our server read cloud metadata?" in security reviews, pen-test remediation, and SOC 2 / ISO 27001 control narratives around input validation and outbound egress.
• Vendor and maintenance risk assessment (the honest read). 1 star, 0 dependents, version 1.1.0, only a README and changelog. That is a maturity signal, not a quality signal — it's published by Craft CMS / Pixel & Tonic, the code is small and readable, MIT-licensed, and the changelog is active enough to show the blocklists get maintained. The decision to note is that we are adopting early on a lightly-adopted library and therefore own the integration, the version pin, and the diff review on every bump.
• Integration cost estimate. It is not a Laravel package — no service provider, no publishable config, no facade. Adoption cost is "composer require plus a thin wrapper we write and own," roughly a day of engineering for the first consumer, not a configuration change. Budget for the wrapper; don't plan around a config/url-validator.php that doesn't exist.

When to Consider This Package

Adopt it when:

• There is at least one endpoint where a user-supplied URL causes a server-side fetch — or one is on the roadmap within a quarter or two.
• The stack is PHP and you control (or can route fetches through) an HTTP client that supports IP pinning, e.g. Guzzle with CURLOPT_RESOLVE.
• You can commit to the full pattern: validate, pin, disable auto-redirects, re-validate on every hop, and re-validate inside queued jobs. The library is a gate, not a network boundary.
• You have, or will build, a dev-only allowlist for localhost/10.x/Docker hostnames, since those are rejected by design and will otherwise break local development.
• You're comfortable pinning the version, committing the lockfile, and reading the source diff when you bump it.

Look elsewhere (or layer differently) when:

• You already have a dedicated fetch service or egress proxy with network-level deny rules — that's a stronger control than any in-process validator, and this becomes a redundant inner layer at best.
• Your HTTP client can't be pinned (some vendor SDKs and managed integrations can't). Validation without pinning is theatre and creates false confidence; route through your own client or don't bother.
• The "URL" is only ever displayed or stored, never fetched by the server — basic format validation is enough, and SSRF defences will just confuse users with rejections.
• Your needs are genuinely "allowlist these five trusted domains." An allowlist is simpler, cheaper, and strictly safer than a general denylist — this package is for the case where you must accept arbitrary user URLs.
• You're not on PHP, or the team would rather evaluate a more widely adopted alternative with comparable coverage. A short bake-off against the strongest-maintained competitor is reasonable; the deciding factors should be IPv6/normalization handling and whether the API returns resolved IPs for pinning.
• You need a supported vendor contract, SLA, or long-term maintenance guarantee. This is a small open-source utility from a reputable org, not a commercial product.

How to Pitch It (Stakeholders)

To executives: This is cheap insurance, not a feature. A handful of engineering days (one to build a shared wrapper, then reuse) closes a well-known vulnerability class where an attacker uses our own servers to reach internal systems and cloud credentials — the kind of incident that shows up as a headline, a breach notification, and a stalled sales cycle. The library is MIT-licensed and free; the cost is the integration work and the small ongoing ownership of a version pin. It won't differentiate the product or win deals, and shouldn't be sold as a capability — it's table stakes that lets us ship link previews, webhook delivery, and import-from-URL features without a security exception on every launch review. The trade-off to accept: we're adopting a very lightly-adopted library from a reputable publisher, so we own the integration layer and are responsible for tracking its updates.

To engineering: Small, framework-agnostic Composer library — no service provider, no config file, no facade. It handles the genuinely hard parts we'd otherwise get wrong: scheme allowlisting, private/reserved/CGNAT/link-local ranges, IPv4-mapped/NAT64/6to4/Teredo unwrapping, hex-encoded hostnames, and cloud-metadata domains. It's deliberately only half the control: it returns the resolved IPs so you can pin the connection, and if you validate without pinning you've reintroduced DNS rebinding and bought nothing. Plan for a shared internal wrapper — a SafeUrl form-request rule, IP pinning in the Guzzle client, manual redirects with a 3–5 hop cap, re-validation inside jobs, and structured logging on rejects (free threat intel). Expect it to block localhost and Docker hostnames in dev; the allowlist must be environment-gated so it cannot be flipped on in production. Read src/ before wiring it in, and review the changelog diff on every version bump — the blast radius of a regression here is a security hole, so tests around our wrapper matter more than trust in the dependency.