Laravel Url Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require atldays/laravel-url
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Atldays\LaravelUrl\LaravelUrlServiceProvider" --tag="config"
   

2. First Use Case: Basic URL Handling Parse a URL from user input:

   use Atldays\LaravelUrl\Url;
   
   $url = Url::fromString('https://example.com/path?query=1');
   $url->isValid(); // bool
   $url->getScheme(); // "https"
   

3. Validation Integration Add to app/Providers/AppServiceProvider.php:

   use Atldays\LaravelUrl\Rules\Url as UrlRule;
   
   protected function boot(): void
   {
       $this->validateUrls();
   }
   

   Use in a form request:

   $this->rules = [
       'website' => ['required', new UrlRule],
   ];
   

Implementation Patterns

Core Workflows

1. Request Macros for Automatic Parsing Extend Illuminate\Http\Request to auto-convert URL fields:

   // In AppServiceProvider@boot()
   $this->extendRequestMacros();
   

   Now request()->input('url_field') returns a Url object.

2. Sanitization Pipelines Clean unsafe URLs (e.g., from user input):

   $dirtyUrl = Url::fromString("javascript:alert(1)");
   $cleanUrl = $dirtyUrl->sanitize(); // Removes unsafe schemes
   

3. Browser-Specific URL Support Handle non-HTTP(S) schemes (e.g., chrome-extension://):

   $extensionUrl = Url::fromString('chrome-extension://abcdef1234');
   $extensionUrl->isBrowserScheme(); // true
   

4. Laravel Data Integration Auto-cast URLs in DTOs:

   use Atldays\LaravelUrl\Casts\Url as UrlCast;
   
   class UserProfile extends \Spatie\LaravelData\Data
   {
       public function __construct(
           public string $website,
       ) {}
   
       public static function rules(): array
       {
           return [
               'website' => ['nullable', new UrlRule],
           ];
       }
   
       public static function casts(): array
       {
           return [
               'website' => UrlCast::class,
           ];
       }
   }
   

5. Validation Rules Reusable validation logic:

   $this->validate([
       'redirect' => ['required', 'url', new UrlRule(['schemes' => ['https']])],
   ]);
   

Gotchas and Tips

Pitfalls

1. Scheme Whitelisting

   • Default sanitization removes all non-HTTP(S) schemes. Explicitly allow browser schemes if needed:

     Url::fromString('chrome-extension://...')->sanitize(['allow_browser_schemes' => true]);
     

2. UTF-8 Validation

   • The package enforces strict UTF-8 validation by default. Disable with:

     Url::fromString('invalid-utf8')->validate(['strict_utf8' => false]);
     

3. Request Macro Overrides

   • If extending request macros, ensure they don’t conflict with existing Laravel macros. Test with:

     $request->hasMacro('parseUrl'); // Check before adding
     

4. Laravel Data Conflicts

   • If using spatie/laravel-data, ensure the UrlCast is registered after the data provider boots. Use booted events if needed.

5. Performance with Large Inputs

   • Sanitization pipelines add overhead. Cache parsed URLs for repeated use:

     $url = Url::fromString($input)->remember();
     

Debugging Tips

• Inspect Parsed Components Use ->toArray() to debug:

  $url->toArray(); // ['scheme' => 'https', 'host' => 'example.com', ...]
  

• Validation Errors Check raw validation messages:

  $url->validate()->errors(); // Returns a MessageBag
  

• Browser Scheme Quirks Test edge cases like mailto: or tel: schemes:

  $url = Url::fromString('mailto:test@example.com');
  $url->isBrowserScheme(); // true
  

Extension Points

1. Custom Sanitizers Add pipeline steps in config/laravel-url.php:

   'sanitizers' => [
       \Atldays\LaravelUrl\Sanitizers\RemoveUnsafeSchemes::class,
       App\Sanitizers\CustomSanitizer::class, // Your class
   ],
   

2. Request Macro Extensions Override default parsing logic:

   \Illuminate\Http\Request::macro('parseUrl', function ($key, $default = null) {
       $value = $this->input($key, $default);
       return Url::fromString($value)->sanitize(['allow_empty' => true]);
   });
   

3. Validation Rule Customization Extend UrlRule for project-specific needs:

   class ProjectUrlRule extends UrlRule
   {
       public function __construct(array $options = [])
       {
           $options['schemes'] = ['https', 'app'];
           parent::__construct($options);
       }
   }