Router Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require poshtive/router
   

   Publish config (optional but recommended for customization):

   php artisan vendor:publish --provider="Poshtive\Router\RouterServiceProvider" --tag="config"
   

2. First Use Case: Define a controller with attributes in app/Http/Controllers/. Example: UserController.php

   use Poshtive\Router\Attributes\Route;
   
   class UserController {
       #[Route('/users', methods: ['GET'])]
       public function index() { ... }
   
       #[Route('/users/{user}', methods: ['GET'])]
       public function show(User $user) { ... }
   }
   

   Run:

   php artisan route:discover
   

3. Verify: Check routes with:

   php artisan route:list
   

Implementation Patterns

Core Workflow

1. Convention-Based Discovery:

   • Place controllers in app/Http/Controllers/ (default).
   • Use #[Route] attributes to define routes.
   • Example for RESTful resources:

     #[Route('/posts', methods: ['GET'])]
     #[Route('/posts', methods: ['POST'])]
     public function index() { ... }
     
     #[Route('/posts/{post}', methods: ['GET'])]
     #[Route('/posts/{post}', methods: ['PUT', 'DELETE'])]
     public function update(Post $post) { ... }
     

2. Nested Resources:

   • Group controllers in subdirectories (e.g., app/Http/Controllers/Admin/).
   • Prefix routes automatically:

     // app/Http/Controllers/Admin/UserController.php
     #[Route('/users', methods: ['GET'])]
     public function index() { ... }
     

     Registers as /admin/users.

3. Middleware and Constraints:

   • Apply middleware via attribute:

     #[Route('/admin', middleware: ['auth.admin'])]
     public function dashboard() { ... }
     

   • Add constraints:

     #[Route('/posts/{id}', where: ['id' => '[0-9]+'])]
     public function show($id) { ... }
     

4. Model Binding:

   • Inject models directly into methods:

     public function show(User $user) { ... } // Automatically resolves from route parameter
     

5. Skipping Routes:

   • Exclude specific routes from discovery:

     #[Route('/skip-me', skip: true)]
     public function hidden() { ... }
     

6. Discovering Routes:

   • Run discovery manually:

     php artisan route:discover
     

   • Or auto-discover on boot (configured in config/router.php).

Integration Tips

• Hybrid Approach: Combine with Laravel’s traditional Route::get() for edge cases. Example:

  Route::get('/legacy', [LegacyController::class, 'action']);
  

• Testing: Use Route::getRoutes() to inspect discovered routes in tests:

  public function test_discovered_routes() {
      $routes = Route::getRoutes();
      $this->assertCount(3, $routes);
  }
  

• Custom Directories: Extend discovery to custom paths in config/router.php:

  'paths' => [
      app_path('Http/Controllers'),
      app_path('Modules/*/Http/Controllers'),
  ],
  

Gotchas and Tips

Pitfalls

1. Duplicate Routes:

   • The package enforces strict duplicate detection by default.
   • If duplicates are found, discovery fails. Use skip: true or adjust attributes to resolve conflicts.

2. Middleware Inheritance:

   • Middleware applied at the class level (e.g., via #[Route] on the class) does not inherit to methods.
   • Explicitly define middleware per route or method.

3. Model Binding Quirks:

   • Ensure model classes are autoloadable and follow Laravel’s binding conventions.
   • Custom binders may not work out-of-the-box; extend the package or use traditional binding.

4. Caching:

   • Discovered routes are cached by default. Clear cache after changes:

     php artisan route:clear
     

5. PHP 8.3+ Requirement:

   • Attributes are PHP 8.0+, but the package leverages newer features. Ensure your environment matches.

Debugging

1. Skipped Routes Report: Enable in config/router.php:

   'report_skipped' => true,
   

   Run discovery to see skipped routes in logs.

2. Route Dumping: Dump discovered routes to a file for debugging:

   php artisan route:dump
   

   Outputs to bootstrap/cache/route_dump.json.

3. Verbose Discovery: Run with verbose output:

   php artisan route:discover --verbose
   

Tips

1. DRY Routes: Use inheritance for shared route logic:

   #[Route('/base', middleware: ['auth'])]
   class BaseController {
       #[Route('/endpoint', methods: ['GET'])]
       public function endpoint() { ... }
   }
   

2. Dynamic Prefixes: Dynamically set prefixes via configuration or environment variables:

   #[Route(config('router.admin_prefix').'/users')]
   

3. API Versioning: Leverage subdirectories for versioning:

   app/Http/Controllers/
     ├── v1/
     │   └── UserController.php
     └── v2/
         └── UserController.php
   

   Configure paths in config/router.php to include both.

4. Performance:

   • Disable auto-discovery in config/router.php if using manual discovery:

     'auto_discover' => false,
     

   • Run discovery only during deployment or when routes change.

5. Extending Attributes: Create custom attributes by extending Poshtive\Router\Attributes\Route:

   #[Attribute(Attribute::TARGET_METHOD)]
   class ApiRoute extends Route { ... }