Templated Uri Router Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ibexa/templated-uri-router
   

   Add to composer.json if not using CLI:

   "require": {
       "ibexa/templated-uri-router": "^1.0"
   }
   

2. Define Routes: Create a YAML/array config file (e.g., routing.yml):

   demo_route:
       pattern: "/products/{category}"
   

3. First Use Case: Generate a templated URI in a controller or service:

   use Hautelook\TemplatedUriRouter\Routing\Generator\Rfc6570Generator;
   
   $routes = require __DIR__.'/routing.yml';
   $generator = new Rfc6570Generator($routes, new \stdClass()); // Context (e.g., request params)
   $uri = $generator->generate('demo_route', ['category' => '{category}']);
   // Output: `/products/{category}`
   

Implementation Patterns

Core Workflows

1. Route Definition:

   • Use RFC-6570 syntax for dynamic segments (e.g., {id}, {*path}).
   • Example:

     api_route:
         pattern: "/api/v1/{controller}/{action}.{_format}"
     

     • _format is reserved for Symfony’s format parameter.

2. URI Generation:

   • Pass placeholders (e.g., {page}) or arrays (e.g., ['{filter}']) for query parameters:

     $uri = $generator->generate('api_route', [
         'controller' => 'users',
         'action'     => 'list',
         '_format'    => 'json',
         'page'       => ['{page}'],
         'sort'       => ['{sort}']
     ]);
     // Output: `/api/v1/users/list.json{?page*,sort*}`
     

3. Integration with Laravel:

   • Service Provider: Bind the generator to Laravel’s container in AppServiceProvider:

     public function register()
     {
         $this->app->singleton('templated.uri.generator', function ($app) {
             $routes = require __DIR__.'/../config/routing.php';
             return new Rfc6570Generator($routes, new \stdClass());
         });
     }
     

   • Usage in Controllers:

     use Illuminate\Support\Facades\App;
     
     $uri = App::make('templated.uri.generator')->generate('demo_route', ['category' => 'electronics']);
     

4. Query Parameter Handling:

   • Arrays for optional/multiple params:

     ['{filter}', '{sort}']  // Output: `{?filter*,sort*}`
     

   • Objects for structured data (e.g., pagination):

     ['page' => ['{page}'], 'limit' => ['{limit}']]
     

5. Context Injection:

   • Pass a context object (e.g., request params, user data) to resolve defaults:

     $context = (object) ['default_category' => 'books'];
     $generator = new Rfc6570Generator($routes, $context);
     $uri = $generator->generate('demo_route', ['category' => '{category}']);
     // If `category` is omitted, uses `default_category` from context.
     

Gotchas and Tips

Pitfalls

1. Reserved Parameters:

   • Avoid using _format, _locale, or _controller as route keys—these are reserved by Symfony/Laravel.
   • Example of incorrect usage:

     bad_route:
         pattern: "/{_format}"  # May conflict with Laravel's format system.
     

2. Context Overrides:

   • Context values override placeholders if not explicitly passed:

     $context = (object) ['category' => 'default'];
     $uri = $generator->generate('demo_route', ['category' => '{category}']);
     // Output: `/products/default` (not `/products/{category}`).
     

3. Query Parameter Escaping:

   • The package does not escape dynamic query values. Sanitize inputs manually:

     $safePage = htmlspecialchars($page);
     $uri = $generator->generate('route', ['page' => $safePage]);
     

4. Route Key Collisions:

   • Ensure route keys (e.g., demo_route) are unique in your config.

Debugging

1. Invalid Patterns:

   • If generation fails, check for malformed RFC-6570 syntax (e.g., unclosed {} or invalid modifiers like *).
   • Example of invalid pattern:

     bad_pattern: "/{category}"  # Missing closing brace if written as `/{category`.
     

2. Missing Routes:

   • Throw RouteNotFoundException if the route key doesn’t exist. Handle gracefully:

     try {
         $uri = $generator->generate('nonexistent_route', []);
     } catch (\InvalidArgumentException $e) {
         abort(404);
     }
     

Extension Points

1. Custom Context:

   • Extend the context object to include app-specific data (e.g., user roles):

     $context = (object) [
         'user' => auth()->user(),
         'default_lang' => 'en'
     ];
     

2. Post-Processing:

   • Chain with Laravel’s Url::to() for additional logic:

     $templatedUri = $generator->generate('route', ['{param}']);
     $finalUri = url($templatedUri); // Add base URL, etc.
     

3. Middleware Integration:

   • Use the generator in middleware to modify outgoing links:

     public function handle($request, Closure $next)
     {
         $uri = app('templated.uri.generator')->generate('route', ['{token}' => $request->token]);
         // Modify headers/response based on $uri.
         return $next($request);
     }
     

4. Testing:

   • Mock the generator in tests:

     $mockGenerator = Mockery::mock(Rfc6570Generator::class);
     $mockGenerator->shouldReceive('generate')
         ->with('route', ['{param}'])
         ->andReturn('/expected/uri');
     $this->app->instance('templated.uri.generator', $mockGenerator);