Uri Laravel Package

Getting Started

Start by installing the package via Composer: composer require opis/uri. The core classes are Opis\Uri\Uri, Opis\Uri\UriTemplate, and Opis\Uri\UriValidation. The most common first use case is parsing and building URIs — instantiate a Uri object from a string or build one programmatically using fluent setters. For example:

use Opis\Uri\Uri;

$uri = Uri::createFromString('https://example.com/path?query=value');
echo $uri->getHost(); // 'example.com'
$uri = $uri->withPath('/new-path')->withQuery('foo=bar');
echo (string)$uri; // 'https://example.com/new-path?foo=bar'

The README and /docs directory (if present in the repo) contain essential examples and API references.

Implementation Patterns

• Immutable URI Modelling: Treat Uri objects as immutable — always use with*() methods to create modified copies.
• Template Expansion: Use UriTemplate to safely expand templated URIs (e.g., for REST APIs or OpenAPI specs):

  $template = new UriTemplate('https://api.example.com/users/{id}');
  echo $template->expand(['id' => 123]); // 'https://api.example.com/users/123'
  

• Validation Workflow: Validate URIs before use (e.g., in form processing) via UriValidation::isValid().
• Integration with PSR-7: Though not PSR-7 compliant, Uri can be converted to a PSR-7 URI by casting to string and using GuzzleHttp\Psr7\Uri.
• Query Handling: Use getQueryParams() and withQueryParams() for structured query manipulation instead of raw string editing.

Gotchas and Tips

• Silent Failure Risk: Some with*() method behavior (e.g., invalid characters) may throw exceptions, so wrap in try/catch or pre-validate.
• No Recent Updates: Last release was in 2021; verify compatibility with PHP 8.0+ (it appears to support up to 8.1).
• Normalization ≠ Validation: Uri::normalize() cleans percent-encoding but doesn’t guarantee validity — always use UriValidation for strict checks.
• Fragment Encoding: Fragments (#section) are percent-encoded on output; test with special characters (e.g., #key=value) to avoid unexpected results.
• Escaping Pitfall: Non-ASCII domain names (IDN) require manual idn_to_ascii() conversion before use — the package doesn’t auto-convert.
• Debugging Tip: Cast to string after every transformation to catch encoding/structure issues early; use (string)$uri in logs.