Download the PHP package atldays/laravel-url without Composer

Laravel URL

atldays/laravel-url is a Laravel package for working with URLs in a more predictable, framework-friendly way.

At its core, the package builds on top of spatie/url, adds Laravel integration, supports browser-specific schemes, provides sanitizer pipelines for unsafe input, ships validation rules, request macros, and optional integration with spatie/laravel-data.

Why This Package Exists

Working with URLs in real applications is usually messier than simply parsing a clean string.

Inputs may come from:

• request headers such as Origin and Referer
• user-submitted form fields
• browser-specific URLs like chrome-extension://...
• values that contain control characters or broken UTF-8
• DTOs and data objects that need automatic casting

This package gives you a single Laravel-oriented layer for those cases while still relying on the excellent parsing foundation provided by spatie/url.

Features

• Atldays\Url\Url value object built on top of spatie/url
• support for browser-specific schemes: chrome-extension, moz-extension, chrome, opera, edge
• URL factory with sanitizer profiles
• configurable sanitizer pipelines
• Laravel facade for short, expressive usage
• validation rules for generic URLs and browser URLs
• request macros for extracting typed URLs from headers
• optional spatie/laravel-data casts and transformer
• translations for validation messages

Requirements

• PHP ^8.2
• Laravel ^11.0|^12.0|^13.0

Installation

Install the package:

If you want to customize sanitizer profiles, publish the config:

If you want to use spatie/laravel-data integration, install it separately:

Quick Start

Use the facade

Use the factory directly

The URL Value Object

The package provides Atldays\Url\Url, which extends Spatie's URL object and adds Laravel-oriented behavior.

Browser-specific schemes

Detect IP hosts

Get the base URL

Factory And Sanitizer Profiles

The recommended entry point for application code is UrlFactory or the Url facade.

Before the URL object is created, the factory runs the input through a configurable sanitizer pipeline.

Default behavior

When you do not pass a profile explicitly, the factory uses the configured default profile:

Explicit profile

Available profiles

The package currently ships with two profiles:

• default General-purpose cleanup for regular application input
• header Cleanup for header values such as Origin and Referer

Built-in sanitizers

• HeaderValueSanitizer Trims wrapping quotes and header-specific whitespace noise
• ControlCharsSanitizer Removes control characters before parsing
• Utf8Sanitizer Normalizes broken UTF-8 before the final URL object is created

Configuration

You can add your own sanitizer classes as long as they implement:

Validation Rules

The package includes Laravel validation rules for both standard URLs and browser-specific URLs.

Generic URL rule

This rule:

• supports nullable
• rejects non-string values
• accepts browser-specific URLs
• validates regular web URLs using Laravel-friendly behavior

Browser URL rule

This rule only accepts browser-specific schemes such as:

• chrome-extension://...
• moz-extension://...
• chrome://...
• edge://...
• opera://...

Request Macros

The service provider registers a few request macros that return typed URL objects.

getUrlFromHeader

getOriginUrl

getRefererUrl

getFullUrl

These macros:

• parse values through the package factory
• use the header profile when reading headers
• return null or the provided default when parsing fails
• reject header URLs with IP hosts

spatie/laravel-data Integration

If your project uses spatie/laravel-data, the package provides casts and a transformer under src/Data.

UrlCast

Use UrlCast when the incoming value must already be a valid URL.

ToUrlCast

Use ToUrlCast when you want to coerce host-like values into full URLs.

Examples it can handle:

• https://example.com/path
• example.com/path
• example.com

UrlTransformer

UrlTransformer converts the URL object back to its string representation when the data object is transformed.

Contracts

The package exposes a small set of contracts under Atldays\Url\Contracts, including:

• Url
• Query
• Segment
• Urlable

These contracts are useful when you want to type against abstractions instead of the concrete URL implementation.

Translations

Validation messages are provided through the package translation namespace:

If you want to publish the package translations into your Laravel application and customize them, run:

After publishing, you can override the package translations in:

Testing

Run the test suite:

Check formatting:

Auto-fix formatting:

Credits

• Spatie URL for the parsing foundation
• Spatie Laravel Package Tools
• Spatie Laravel Data for optional DTO integration

License

The MIT License. Please see LICENSE.md for more information.