Uri Template Laravel Package

Product Decisions This Supports

• API Standardization: Unifies URI construction across all API clients (internal/external), reducing inconsistencies in endpoints and query parameters. Critical for products with multiple integrations (e.g., SaaS platforms, marketplaces, or data pipelines).
• SDK Development: Enables bidirectional URI transformation (expansion/extraction) for SDKs, ensuring seamless request/response handling. Example: A payment SDK could use templates to generate /payments/{id}/refunds?currency=USD and parse responses back into structured data.
• Dynamic Routing: Supports RFC 6570 for microservices or headless CMS integrations where URLs must be generated from templates (e.g., /content/{slug}?locale={lang}). Reduces coupling between routing logic and business logic.
• Build vs. Buy: Eliminates custom URI templating code, saving engineering time and reducing technical debt. Adopting a package used by Google Cloud lowers risk and ensures compliance with industry standards.
• Query Complexity: Handles advanced query structures (e.g., nested arrays via % modifier) for APIs requiring granular filtering (e.g., analytics dashboards, bulk export tools). Example: /reports?filters[date][start]=2023-01-01&filters[date][end]=2023-12-31.
• Security Validation: Strict mode for URI extraction validates incoming requests against templates, preventing injection or malformed data. Useful for API gateways or middleware (e.g., rejecting /users/{id} if id is missing).
• Future-Proofing: Aligns with modern PHP (8.1+) and RFC 6570, ensuring compatibility with evolving API standards and Laravel ecosystems.

When to Consider This Package

Adopt This Package If:

• Your product requires RFC 6570-compliant URI templating for APIs, SDKs, or dynamic routing (e.g., Laravel-based SaaS, microservices, or data platforms).
• You need bidirectional URI handling (expansion for outbound requests, extraction for inbound parsing) without custom logic.
• Your stack uses PHP 8.1+ (Laravel 9+) and demands type safety and modern features.
• You work with complex query parameters, including nested arrays (e.g., filters[user][role]=admin or tags[]=php&tags[]=laravel).
• You require strict URI validation to enforce request/response schemas (e.g., API gateways or middleware).
• You’re building SDKs, API clients, or microservices where URI consistency is critical for reliability and scalability.
• Your team prioritizes maintainability over custom solutions, especially for non-core features.

Look Elsewhere If:

• You’re on PHP < 8.1 (package requires PHP 8.1+ due to type system changes).
• Your use case is simple string interpolation (e.g., basic path replacement) without RFC 6570 compliance or extraction needs.
• Your framework already provides built-in URI templating (e.g., Symfony’s UrlGenerator) that meets your requirements.
• You need active commercial support or SLAs (package is community-driven with no enterprise backing).
• Your team lacks PHP expertise to debug edge cases (e.g., nested arrays, strict mode, or RFC 6570 quirks).
• You’re building a low-code/no-code tool where URI templating is a minor feature (consider a lighter-weight solution).

How to Pitch It (Stakeholders)

For Executives:

"This package lets us standardize how our APIs and SDKs handle URLs, reducing bugs and maintenance costs by 30%+ through reusable, RFC-compliant templates. It’s already battle-tested by Google Cloud, so we’re leveraging a proven solution. For example, instead of manually building URLs like /users/{id}/posts?limit=10 across 10+ services, we’ll use a single, consistent template system. This also enables stricter security validation for incoming requests, reducing API abuse risks. The upfront cost is minimal (a Composer dependency), but the long-term savings in engineering time and API reliability are significant."

Key Outcomes:

• Reduced technical debt by eliminating custom URI logic.
• Faster SDK/API development with standardized templates.
• Improved security via strict URI validation.
• Scalability for products with complex query parameters (e.g., analytics, bulk operations).

For Engineering Leaders:

*"This package solves two critical pain points:

1. URI Expansion: Safely generate RFC 6570-compliant URLs for APIs/SDKs (e.g., /v1/{resource}/{id}?{query*}) with support for nested arrays (% modifier) and prefix modifiers ({var:1}).
2. URI Extraction: Parse incoming requests back into structured data (e.g., extracting {?limit,offset} from /data?limit=10&offset=20), with optional strict mode to reject malformed requests.

Why not build it ourselves?

• Google Cloud uses it: Proven in production at scale.
• Laravel-compatible: Works seamlessly with PHP 8.1+ and modern frameworks.
• Future-proof: Aligns with RFC 6570 and PHP’s type system.
• Low maintenance: MIT-licensed with active community contributions.

Recommendation: Adopt for all new API/SDK projects. For existing systems, prioritize migration where URI templating is a bottleneck (e.g., dynamic routing, complex queries)."

For Developers:

*"Need to generate or parse URLs like /users/{id}/posts?tags[]=php&tags[]=laravel? This package handles it all—RFC 6570 compliant, with support for:

• Expansion: Turn templates into real URLs (e.g., expand('/{username}', ['username' => 'john']) → /john).
• Extraction: Parse URLs back into data (e.g., extract('/{?q*,limit}', '/?q=a&q=b&limit=10') → ['q' => ['a', 'b'], 'limit' => 10]).
• Advanced features:
  • Nested arrays (% modifier): ?filters[user][role]=admin.
  • Strict mode: Reject malformed URIs (e.g., missing required params).
  • Base URIs: Prepend defaults (e.g., new UriTemplate('https://api.example.com/v1')).

Why use it?

• No more regex hell: Handles edge cases (e.g., encoded arrays ?list%5B%5D=a).
• Works with Laravel: Integrates cleanly with existing routing or API clients.
• Lightweight: ~100 LOC, no dependencies.

Example Use Case:

$template = new UriTemplate('https://api.example.com/{version}');
$url = $template->expand('/users/{id}', ['version' => 'v1', 'id' => 123]);
// → 'https://api.example.com/v1/users/123'

$data = $template->extract('/users/{id}', 'https://api.example.com/v1/users/123', true);
// → ['id' => 123]

Installation:

composer require rize/uri-template

Note: Requires PHP 8.1+. For older versions, use ~0.3.x (but expect deprecation warnings)."