Uri Template Laravel Package

Product Decisions This Supports

• API client / integration roadmap. If we build or consume REST APIs where endpoint shapes are defined by a spec (OpenAPI, vendor docs, Google Cloud-style service definitions), RFC 6570 templates become a first-class artifact. This package lets us treat a URI template as configuration — expand it to call out, extract from it to parse inbound — rather than hand-rolling string concatenation and regex parsing per endpoint.
• Build vs. buy. The "build" alternative is 50–150 lines of sprintf/http_build_query for expansion and a bespoke regex parser for extraction. That looks cheap until we hit {/segments*}, {.extensions*}, prefix modifiers ({term:1}), or operator-specific encoding rules — at which point we are reimplementing RFC 6570 with no spec conformance tests. Buying (well, MIT-licensed adopting) is the correct call if we actually need operators or extraction; otherwise it is unnecessary surface area.
• Multi-tenant / white-label routing and webhook handling. Strict-mode extraction is the decision-enabler for "does this inbound request match template X, and what were the variables?" — useful for partner-defined webhook URLs, customer-configured callback endpoints, and dynamically registered routes where the template is data, not code. Laravel's router cannot express this: it matches registered routes, not runtime template strings.
• SDK / client-library strategy. The Google Cloud adoption signal matters here. If we ship a PHP SDK or wrap a vendor API that publishes URI templates, aligning on the same conformance semantics as the reference ecosystem reduces integration surprise.
• Vendor-neutrality and exit cost. Zero runtime dependencies, framework-agnostic, no state, no I/O. Adopting it commits us to one small, swappable leaf utility — not a platform. That keeps the reversibility cost of the decision low, which is the main thing I want from a utility dependency.
• Not a decision this supports: general URL building inside our own Laravel app. route(), url(), and action() already cover that, and replacing them with templates would be a net loss in readability and tooling (route caching, IDE support, route:list).

When to Consider This Package

Adopt when:

• We have a concrete, named use case requiring operators ({/segments*}, {.extensions*}, {?q*,limit}) or extraction, ideally both. Absent those, this is a solution looking for a problem.
• URI templates are external contract — vendor spec, partner-defined callback, OpenAPI servers/paths — and must stay faithful to a published spec rather than to our internal routing conventions.
• The estate is PHP 8.1+ and on Laravel 10/11. A Laravel 9 / PHP 8.0 estate is blocked on 0.4.x and would be stranded on 0.3.x, which carries PHP 8.4/8.5 deprecation noise. Do not adopt into a PHP 8.0 estate.
• We are willing to pin exactly (^0.4.2, not ~0.3) and add a dependency-review rule for minor bumps. The 0.3 → 0.4.0 transition was a real breaking change that dropped PHP < 8.1; ~0.3 silently strands a project on an unmaintained branch. Note the README's install snippet still says ~0.3 — stale documentation, a trap worth flagging in the ADR.

Look elsewhere when:

• We only need to build internal URLs → use Laravel's router.
• We need full URL parsing/manipulation (normalization, resolution against a base, PSR-7 URI objects) → use guzzlehttp/psr7 / league/uri. This package is templates, not a URI toolkit; do not stretch it.
• We need a routing engine for inbound HTTP → Laravel's router or FastRoute. Strict-mode extraction is a validation and parsing tool, not a router; using it as the primary dispatcher would be off-label and slower.
• We require a stable API contract with LTS-style guarantees. This is pre-1.0 software. If the org cannot tolerate a breaking minor, that is a genuine disqualifier.

Watch item for the decision record: the metadata reports Dependents: 0 while the README claims consumption by google-cloud-php-core and the Google Cloud client libraries. These are not both operationally meaningful; Packagist's dependents count is known to undercount. Treat the Google claim as a reputational signal, not as verified adoption evidence, and do not cite it as a risk mitigant in the ADR without confirming it. Single-maintainer project, 419 stars, active PHP-version maintenance through 2026 releases — healthy enough to adopt, not large enough to be load-bearing without a pin.

How to Pitch It (Stakeholders)

To executives: We are proposing one small, MIT-licensed, zero-dependency PHP library to handle a specific, narrow job: building and parsing URLs that follow a published standard (RFC 6570). It matters because API and partner integrations increasingly define endpoint shapes as templates, and our current approach — hand-written string assembly plus custom regex — is where subtle encoding and parsing bugs live, and where each new integration adds bespoke code. This library is the same implementation Google's Cloud PHP libraries rely on, which de-risks conformance. Cost is effectively zero: no new infrastructure, no vendor contract, no lock-in — it is a swappable utility with no state. The real investment is governance, roughly a day of integration plus a decision on where templates live and how they are tested.

To engineering: Low effort, a day for a spike plus a thin adapter and one container binding. Framework-agnostic by design — no service provider, facade, or published config to own. It does not replace Laravel's router; it fills a genuine gap the router does not cover: expansion with RFC operators and strict-mode extraction of variables from an arbitrary runtime template (useful for validating inbound webhook/partner URIs, not for dispatching). Two conditions on adoption: pin to ^0.4.2 and add review-on-minor-bump, because 0.3 → 0.4.0 was a real breaking change and the README's ~0.3 install snippet is stale; and confirm PHP 8.1+, which rules out a Laravel 9 / PHP 8.0 estate. Treat the library as a leaf utility behind our own small interface so we can swap it out without touching call sites. Verify the Google Cloud adoption claim before we lean on it — our metadata says zero dependents, which contradicts the README, so cite it as a positive signal only, not as a guarantee.