Laminas Uri Laravel Package

Getting Started

Install via Composer:

composer require laminas/laminas-uri

Start by instantiating a Laminas\Uri\Uri object from a string or build one step-by-step. The core workflow is:

1. Parse an existing URI or create a new one
2. Access or modify components via methods like getHost(), setPath(), withQuery()
3. Validate before output using isValid()
4. Cast to string for standardized output: (string) $uri

First use case: Validate and normalize user-submitted URLs

use Laminas\Uri\Uri;

$uri = new Uri($userInput);
if ($uri->isValid()) {
    $sanitized = (string) $uri; // safe, standardized
}

Implementation Patterns

• Request URL Construction: Build URLs programmatically for redirects or API responses

  $uri = (new Uri('https://example.com'))
      ->withPath('/api/users')
      ->withQuery(['page' => 1, 'limit' => 20]);
  $redirectUrl = (string) $uri;
  

• Component Validation & Sanitization: Validate parts in isolation (e.g., host, path)

  $host = $uri->getHost();
  if (!Uri::isValidHost($host)) {
      throw new InvalidArgumentException('Invalid host');
  }
  

• Scheme-Specific Handling: Use built-in HTTP/HTTPS validators or register custom schemes

  $uri = new Uri('ftp://files.example.com/pub');
  $uri->setScheme('https'); // auto-normalizes for HTTPS
  

• Immutable Updates: Leverage with*() methods (PSR-7 compatible pattern) for safe transformations in middleware or utilities

  $newUri = $originalUri
      ->withScheme('https')
      ->withFragment('section-2');
  

Gotchas and Tips

• Percent-Encoding: withQuery() and withFragment() automatically encode reserved characters—but only for new values. Use getQuery() or getFragment() before modification if inspecting raw input.
• Empty Hosts: URIs like mailto:john@example.com have no host—getHost() returns null. Always check type ('' or null depending on scheme).
• Relative URIs: new Uri('path/to/resource') creates a relative URI. Validate with isValid() only after contextually resolving (e.g., combine with base URI via Uri::resolve() in your app logic).
• Extensibility: Extend UriInterface and implement Uri::factory() for custom scheme handling (e.g., tel:, geo:) in enterprise integrations.
• Debugging Tip: Use var_dump($uri->toArray()) to inspect all parsed parts—especially helpful when troubleshooting encoding or normalization.