Iri Laravel Package

Getting Started

Start by installing via Composer: composer require ml/iri. Once installed, the Iri class is ready to parse and resolve IRIs. The most common day-to-day use case is converting malformed or non-standard URIs/IRIs into normalized, RFC-compliant forms—especially when processing user input, API responses, or webhooks where encoding may be inconsistent. Begin with the parse() method to decompose an IRI into components (scheme, authority, path, query, fragment), and resolve() to resolve relative IRIs against a base.

Example:

use Lanthaler\IRI\Iri;

$iri = new Iri('https://example.com/path?query=1#frag');
$parsed = $iri->parse(); // Returns associative array of components

// Resolve relative IRI
$base = 'https://example.com/path/';
$relative = '../other';
$resolved = (new Iri($relative))->resolve($base); // => 'https://example.com/other'

Implementation Patterns

Use Iri objects as immutable value objects—create, parse, resolve, and discard. A common pattern is to sanitize incoming URLs before redirecting or proxying (e.g., from API payloads or user-submitted links). Since ml/iri handles UTF-IRIs correctly (unlike parse_url()), use it when dealing with internationalized domain names or paths (e.g., /path/日本語). For batch processing (e.g., link extraction from HTML), wrap parsing in a validator layer:

try {
    $iri = new Iri($url);
    $iri->normalize(); // Normalize path segments, decode percent-encoding where safe
    return (string) $iri;
} catch (\Exception $e) {
    // Handle invalid input
}

Integrate with frameworks via middleware or formatters—e.g., in Laravel, use in API resource transformers to ensure links from external APIs are normalized before serialization.

Gotchas and Tips

• No normalization by default: parse() returns raw components. Call normalize() explicitly if you need path normalization (/../, ./, etc.)—but be aware it only partially normalizes (no scheme/authority normalization per spec).
• String casting requires care: (string) $iri may not always preserve original encoding. Use getUri() (or rely on __toString() only after normalize()) for predictable output.
• Relative resolution behavior: resolve() follows RFC 3986 strictly; trailing slashes matter (http://a/b/c vs http://a/b/c/). Test with edge cases (e.g., #, empty path, relative scheme).
• Missing validation: This package does not validate IRIs (despite the description). Use parse() first, then manually check required components (e.g., scheme present) if validation is needed.
• No active maintenance: With no recent commits and only a README-level maturity, pair with a defensive layer—e.g., fallback parsing using parse_url() if Iri throws unexpected exceptions.

Best practice: Encapsulate IRI handling behind a custom UrlSanitizer interface to ease future migration or extension (e.g., switching to php-http/uri-resolver or webmozart/path-util if needed).