Uri Template Laravel Package

Getting Started

Install the package with composer require guzzlehttp/uri-template. Start by using the simple static API to expand URIs using RFC 6570 templates:

use GuzzleHttp\UriTemplate\UriTemplate;

$template = 'https://api.example.com/users{/id}{?filter*}';
$params = ['id' => 123, 'filter' => ['active' => true, 'role' => 'admin']];

echo UriTemplate::expand($template, $params);
// Outputs: https://api.example.com/users/123?active=true&role=admin

Check the README for basic usage and the RFC 6570 spec for template syntax (e.g., {/var}, {?key*}).

Implementation Patterns

• Static API: Use UriTemplate::expand() for one-off expansions.
• Class-based expansion: Instantiate UriTemplate for repeated use (e.g., in service classes or SDKs):

  $uriTemplate = new UriTemplate();
  $url = $uriTemplate->expand('/users{/id}', ['id' => 42]);
  

• Integration with Guzzle: Often used internally by Guzzle, but standalone usage is common in HTTP client libraries and API SDKs to support templated endpoints.
• Array expansion with * suffix: Leverage {'key*'} syntax to safely expand arrays and objects (e.g., {'query*'} => ['page' => 1, 'size' => 20]). Now handles empty nested arrays correctly (v1.0.6+).
• Custom encoding: No custom encoding—relies on PHP’s built-in rawurlencode() for RFC 3986-compliant encoding. Reserved/fragment values now preserve existing percent-encoded triplets (v1.0.6+).
• Handling empty strings: Fixed in v1.0.7—operators (e.g., /, ?, #) now correctly retain their leading characters even when defined variables expand to empty strings (e.g., {/id} with id => "" now yields / instead of omitting it entirely).

Gotchas and Tips

• PHP 8.5+ only: While backwards compatible with earlier versions (v0.2+ supports PHP 7.1+), recent releases (v1.0+) drop older PHP support—ensure your runtime matches.
• Empty nested arrays: Previously, empty nested arrays could add malformed query components. Fixed in v1.0.6—now correctly omits empty nested arrays without side effects.
• Double-encoding of query keys: Nested query array keys were double-encoded in earlier versions. Fixed in v1.0.6—now encodes keys only once.
• Reserved/fragment expansion: Existing percent-encoded triplets (e.g., %20) in variable values were not preserved. Fixed in v1.0.6—now retains original encoding.
• 0 values expand correctly: Prior to v1.0.2, 0 used in arrays/objects would be skipped; now it expands as "0". Double-check if upgrading from older versions.
• Empty strings in paths/queries: Fixed in v1.0.7—operators like /, ?, or # will no longer be omitted if their associated variable expands to an empty string. For example, {/id} with id => "" now correctly produces / instead of being skipped.
• Non-finite floats: Fixed in v1.0.7—no longer emits coercion warnings for non-finite float values (e.g., INF, -INF, NAN) on PHP 8.5+.
• No built-in validation: Templates are expanded per RFC 6570 spec, but invalid templates or mismatched variables may produce unexpected or malformed URIs—test edge cases.
• Empty arrays/objects: Empty arrays expand to nothing (?{list*} with list=[] yields ""). Use default values (e.g., ['list' => null]) if omission is desired.
• Path vs query confusion: Use / vs ? prefix in templates carefully—{/var} affects the path; {?var} affects the query string.
• Extensibility: No hooks or plugins; the class is final. Extend indirectly via composition (e.g., a UriExpander service wrapper).
• Debug tip: Use var_dump(UriTemplate::expand(...)) with known inputs to validate expansions incrementally, especially for nested objects. Test with edge cases like empty arrays, percent-encoded values, or empty strings.
• Non-finite values: If working with floats, ensure values are finite (e.g., is_finite($value)) to avoid unexpected behavior in older versions. v1.0.7 resolves this issue entirely.