Uri Template Laravel Package

Product Decisions This Supports

• Build vs. buy for URL/link construction. This package replaces hand-rolled string concatenation, sprintf-style path building, and ad-hoc query encoding with a spec-backed RFC 6570 expander. That is a buy decision with a very small footprint: one static call, MIT license, maintained under the Guzzle organization. The alternative — writing a partial, subtly wrong expander in-house — is a recurring source of encoding bugs (double-encoded query keys, 0 values dropped, Unicode prefixes split mid-codepoint) that this library has already fixed and regression-tested.
• Consuming hypermedia / linked APIs. If your roadmap includes integrations with APIs that advertise endpoints as templates — HAL, JSON:API-style link objects, Siren, RFC 8288 Link headers, OpenAPI links and server-variable definitions, WebFinger, or pagination "next" links — you need a template expander, not a URL builder. This is the enabling dependency for "follow the links the API gives us" designs, which materially reduce coupling to hardcoded endpoint paths.
• SDK / API client generation. Any generated PHP client (from OpenAPI, or an internal API catalog) needs a single, correct expansion primitive at its core. Standardizing on this package means generated code stays thin and the correctness burden lives in one vetted dependency.
• Multi-tenant and configurable routing. Template-driven path construction (tenant-scoped base paths, environment-specific hosts, per-partner endpoint configuration) becomes a configuration problem rather than a code problem: store the template, pass the variables array.
• Webhook and callback URL templating. Letting customers register parameterized callback URLs, then expanding them server-side with validated values, is directly supported — and v2's strict validation turns malformed customer templates into immediate, catchable InvalidArgumentExceptions rather than half-valid URLs sent to a third party.
• Fail-fast data quality as a product stance. v2.0.0 rejects invalid template syntax, invalid UTF-8, non-finite floats, and prefix modifiers on list/map values, instead of expanding partially. That is a deliberate product decision embedded in the dependency: bad input surfaces at expansion time, in your logs, instead of as a mysterious 404 or a corrupt outbound request. Adopting v2 is effectively signing up for that policy.
• Risk/roadmap input, not a feature. This is infrastructure, not a differentiator — it should appear in dependency and security reviews, not on a customer-facing roadmap. Its presence is a signal that the team is consuming a standards-based API surface rather than guessing at one.

When to Consider This Package

Adopt when:

• You are integrating with an API whose documentation, discovery document, or link relations use {var} / {?var} RFC 6570 syntax and you need to fill those in at runtime.
• You already run PHP ≥ 7.4 (v2 requires >=7.4,<8.6; v2.0.1 adds PHP 8.6 support). If you are pinned below 7.4, the v1.0 maintenance line (PHP >=7.2.5) is still supported.
• You need only expansion. If you just need to send requests, guzzlehttp/guzzle is the starting point and this comes along the dependency graph; install guzzlehttp/uri-template directly only when expansion is the actual need.
• You want spec compliance without owning it: prefix modifiers that count Unicode code points rather than bytes, correct handling of reserved and fragment expansion, correct pct-encoding of existing triplets, deterministic list-vs-map handling for numeric-keyed arrays, and locale-safe float formatting.
• You can tolerate a breaking major. Migrating 1.x → 2.x requires an audit: the class is no longer instantiable (static UriTemplate::expand() only), previously-tolerated invalid templates now throw, and previously-silent coercions (booleans, floats, nulls in composites) now have defined behavior. Budget a test pass over every stored template.

Look elsewhere when:

• You need matching, not expansion. This library turns a template into a URI. It does not take a concrete URI and tell you which template it matched, nor extract path parameters. If you are building a router or an inbound request classifier, you need a router (e.g. FastRoute, Symfony Routing) or a template-matching library.
• You need OpenAPI parameter serialization. OpenAPI's style/explode/allowReserved serialization rules diverge from RFC 6570 in several places. Use a dedicated OpenAPI request builder rather than assuming this covers it; use this only for the parts of the spec that genuinely are URI templates.
• You are assembling query strings only. http_build_query() or PSR-7's Uri with a query builder is simpler and has no new dependency. Reach for this package when the template itself is data — configured, generated, or received from a server.
• You need an HTTP client, retries, middleware, or auth. Wrong package; that is Guzzle proper.
• Your stack is not PHP, or your platform forbids Composer dependencies for this layer — equivalent RFC 6570 implementations exist for most languages; pick the maintained one.
• You need guardrails against hostile templates. Expansion performs no allow-listing of scheme or host. If templates or variables can be influenced by untrusted users, you still need your own validation of the expanded result before issuing a request — this library validates syntax and encoding, not intent.

Diligence items before committing:

• The reported dependent count of 0 is almost certainly a measurement artifact — this class was extracted from Guzzle and is pulled in transitively by widely used PSR-7 tooling. Confirm the real install base via your own composer why / dependency graph rather than trusting the metric, because it materially changes the "is this maintained?" conversation.
• 198 stars and a small maintainer pool. Mitigants: Guzzle org stewardship, a documented changelog and release history, an explicit security disclosure process, and an available Tidelift commercial support subscription. If this sits on a critical path, the Tidelift option is the cheapest way to buy down maintenance risk.
• Pin to ^2.0 and track patch releases; the 2.x line is where correctness fixes land.

How to Pitch It (Stakeholders)

For executives (one paragraph): We are proposing a small, MIT-licensed, standards-based PHP dependency that builds URLs from templates instead of from string concatenation. It is one function call, it is maintained by the Guzzle organization, and it removes a whole class of integration defects — malformed query strings, mis-encoded international characters, dropped zero values, broken pagination links — that currently surface as customer-visible failures and support tickets. It supports our direction of following links that APIs advertise rather than hardcoding endpoints, which reduces the cost of every future integration. Cost is effectively zero: no infrastructure, no vendor contract, no lock-in. The one real cost is a one-time audit of existing templates when we move to the current major version, because it now rejects malformed input loudly instead of guessing. Recommendation: adopt at the current major, pin the version, and revisit commercial support only if it lands on a critical path.

For engineering leads: Single-purpose library — UriTemplate::expand($template, $variables) — with a strict v2 contract. It validates template syntax, variable names and modifiers, and UTF-8 in values and map keys before producing any output, so failures arrive as InvalidArgumentException at a known point rather than as a partially-built URL. Behavior is fully specified for edge cases we would otherwise argue about: dense arrays expand as lists and sparse/mixed-key arrays as maps, booleans are 1/0 at every nesting level, non-finite floats throw, floats never pick up a locale decimal separator, and prefix modifiers count Unicode code points rather than bytes. UriTemplate is non-instantiable and rejects PHP serialization. Requires PHP ≥ 7.4; 2.0.1 covers PHP 8.6. If we are on 1.x, the upgrade is mechanical but not invisible — see the v2.0.0 changelog for the full behavior deltas. Not a router: it expands templates, it does not match incoming URIs. And it does not validate that the resulting URL is safe to call, so any untrusted template or variable input still needs our own scheme/host allow-listing.