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+).

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.
• 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 or percent-encoded values.