Uri Laravel Package

Getting Started

Start by installing the package via Composer:

composer require joomla/uri

Then, create and manipulate URIs using the Uri (mutable) or UriImmutable (read-only) classes. The most common first use case is building or modifying query strings for internal routing or API clients:

use Joomla\Uri\Uri;

$uri = new Uri;
$uri->setScheme('https')
    ->setHost('api.example.com')
    ->setPath('/v1/users')
    ->setQuery('limit=10&offset=0');

echo (string) $uri; // https://api.example.com/v1/users?limit=10&offset=0

Check the README for basic method usage — it includes inline examples for setHost, setQuery, setPath, and authentication fields. Also review UriHelper::parseUrl() when dealing with non-ASCII URLs (e.g., internationalized domains) where PHP’s native parse_url() fails.

Implementation Patterns

• Immutable passes: Use UriImmutable when passing URIs into untrusted or complex contexts (e.g., services, middleware) to prevent accidental mutation:

  use Joomla\Uri\UriImmutable;
  
  $uri = new UriImmutable('https://example.com?foo=bar');
  $uri->setQuery('foo=baz'); // ⚠️ Throws InvalidArgumentException
  

• Interface-typed APIs: Type-hint against Joomla\Uri\UriInterface in service methods to accept both mutable and immutable instances — enabling testability and future-proofing.
• Query manipulation with arrays: Use setQuery() with associative arrays instead of raw strings to avoid encoding pitfalls:

  $uri->setQuery(['search' => 'café & parks', 'page' => 1]);
  

• Hybrid parsing: Use UriHelper::parseUrl() before constructing a Uri object if you’re processing external or malformed URLs (e.g., from logs or legacy systems).

Gotchas and Tips

• PHP version dependency: Version 4.0+ requires PHP 8.3+. If stuck on older PHP, use ~3.0 (requires PHP 8.1). Check composer.json requirements before upgrading.
• Protocol-relative URIs: setHost() expects a host, not a full URL. Passing 'http://localhost' to setHost() will misbehave — use setScheme() and setHost() separately.
• Immutable is deeply immutable: Even calling __toString() on an immutable URI returns a new string — but it does not modify internal state. However, methods like setQuery() return new instances, so chain or reassign carefully:

  $immutable = new UriImmutable;
  $immutable->setQuery('a=1'); // ❌ returns new object, but $immutable unchanged
  $immutable = $immutable->setQuery('a=1'); // ✅ correct
  

• Encoding consistency: UriHelper::parseUrl() uses mbstring — ensure the extension is installed. PHP’s parse_url() will misparse UTF-8 characters (e.g., café in path), but UriHelper handles them correctly.
• No PSR-7 compatibility: This is not PSR-7 compliant. Do not expect interoperability with Symfony’s UrlMatcher or Guzzle’s Uri — it’s a dedicated Joomla Framework tool.
• Minimal documentation: The docs/overview.md is a stub. Rely on code comments and the README examples — inspect src/Uri.php and src/UriInterface.php for method signatures (e.g., setFragment(), buildQuery()).