URL Validator

URL Validator (craftcms/url-validator) is a focused PHP security library that vets URLs and IP addresses before your application opens any outbound connection. It is designed to stop Server-Side Request Forgery (SSRF), DNS rebinding, and cloud-metadata exfiltration attacks that arise whenever user-supplied URLs are fetched.

By default it rejects non-HTTP(S) schemes, raw and hex-encoded IP literals, well-known cloud-metadata hostnames, and any hostname that resolves to a private, reserved, loopback, link-local, CGNAT, or metadata IP address, including IPv6 addresses that tunnel an IPv4 address. The allow/deny lists and DNS resolver are configurable so teams can tighten or adapt the policy to their environment.

What You Get

• Scheme allowlisting that blocks file://, ftp://, gopher:// and other non-HTTP(S) schemes
• Rejection of raw IP literals, hex-encoded hostnames, and cloud-metadata domains
• DNS resolution checks against private, reserved, loopback, link-local, and CGNAT ranges
• Detection of IPv6 addresses that embed or tunnel an IPv4 address
• A configurable resolver and allow/deny lists for custom policies

Common Use Cases

• Validating user-supplied webhook or callback URLs before delivery
• Sanitizing URLs for link-preview or URL-unfurling features
• Guarding server-side image or file import from remote URLs
• Hardening any outbound HTTP fetch against internal-network access

Under The Hood

Architecture - The library is intentionally tiny: a single UrlValidator class plus a UrlValidationException, under the CraftCms\UrlValidator namespace. The validator holds configurable allowlists (schemes) and denylists (hostnames, IPv4 addresses, IPv4/IPv6 ranges), and a pluggable resolver callable that maps a hostname to its IPs. Validation flows scheme check, hostname/literal check, DNS resolution, then range membership tests, throwing before any connection is made.

Tech Stack - Requires PHP 8.0.2+ and the ext-filter extension, with zero runtime Composer dependencies. Development tooling is modern: Pest 3 for tests, PHPStan 2 for static analysis, and Laravel Pint for formatting, wired through composer scripts.

Code Quality - Despite being new, the code is carefully written and documented, with inline references to the source research behind the cloud-metadata deny lists. A Pest test suite (UrlValidationTest) exercises the validation paths, and PHPStan plus Pint enforce type safety and style. The narrow scope keeps the surface auditable.

API Design - The public surface is a single validator object with sensible secure defaults, so the common case requires almost no configuration. Denylists, allowed schemes, and the resolver are all injectable for advanced use, striking a good balance between safe-by-default and customizable.