Getting Started

Minimal Setup

Installation:

composer require derafu/routing

Add the service provider to config/app.php:

'providers' => [
    // ...
    Derafu\Routing\RoutingServiceProvider::class,
],

Basic Route Definition:

use Derafu\Routing\Router;

$router = app(Router::class);
$router->get('/hello', fn() => 'Hello, World!');

First Use Case: Register routes in a dedicated file (e.g., routes/web.php) and bootstrap them in your AppServiceProvider:
```
public function boot()
{
    $router = app(Router::class);
    require __DIR__.'/../routes/web.php';
}
```

Dispatching Requests:

$request = new \Symfony\Component\HttpFoundation\Request();
$response = $router->dispatch($request);

Implementation Patterns

Core Workflows

Plugin-Based Routing: Extend functionality via plugins (e.g., middleware, route groups):

$router->plugin(new \Derafu\Routing\Plugin\MiddlewarePlugin());
$router->group(['middleware' => 'auth'], function($router) {
    $router->get('/dashboard', fn() => 'Dashboard');
});

Dynamic Route Generation: Use named routes for URL generation:

$router->get('/user/{id}', fn() => 'User Profile')->name('user.profile');
$url = $router->url('user.profile', ['id' => 123]);

Route Caching: Cache routes for performance (e.g., in AppServiceProvider):
```
$router->cacheRoutes();
```

Integration with Laravel: Replace Laravel’s router in AppServiceProvider:

public function register()
{
    $this->app->singleton(\Illuminate\Routing\Router::class, function($app) {
        return app(Derafu\Routing\Router::class);
    });
}

Common Patterns

Route Groups:

$router->group(['prefix' => 'admin'], function($router) {
    $router->get('/dashboard', fn() => 'Admin Dashboard');
});

Route Parameters:

$router->get('/post/{slug}', function($slug) {
    return "Post: $slug";
});

HTTP Methods:

$router->post('/submit', fn() => 'Form Submitted');
$router->put('/update', fn() => 'Updated');

Gotchas and Tips

Pitfalls

Plugin Conflicts: Ensure plugins are registered before defining routes that depend on them. Plugins modify router behavior globally.
Route Overrides: Cached routes may not reflect real-time changes. Clear the cache after modifying routes:
```
php artisan route:clear
```
(If using Laravel’s Artisan; otherwise, manually clear the cache.)
Middleware Misconfiguration: Plugins like MiddlewarePlugin require middleware to be registered in Laravel’s container. Verify middleware exists before use.

Case Sensitivity: Route matching is case-sensitive by default. Use case_sensitive: false in route groups if needed:

$router->group(['case_sensitive' => false], function($router) {
    $router->get('/Home', fn() => 'Homepage');
});

Debugging Tips

Inspect Routes: Use $router->getRoutes() to dump all registered routes for debugging.

Error Handling: Wrap dispatch in a try-catch to handle 404s gracefully:

try {
    $response = $router->dispatch($request);
} catch (\Derafu\Routing\Exception\RouteNotFoundException $e) {
    $response = new \Symfony\Component\HttpFoundation\Response('Not Found', 404);
}

Plugin Debugging: Enable debug mode for plugins (if supported) to log their behavior:
```
$router->plugin(new \Derafu\Routing\Plugin\MiddlewarePlugin())->debug();
```

Extension Points

Custom Plugins: Create plugins by implementing Derafu\Routing\Plugin\PluginInterface:

class MyPlugin implements PluginInterface {
    public function apply(Router $router) {
        $router->on('before', fn() => logger()->info('Route called'));
    }
}

$router->plugin(new MyPlugin());

Route Matching Logic: Override the match() method in a custom router class for bespoke matching (e.g., regex-based routes).
Response Handling: Extend the router to support custom response objects or modify responses post-dispatch.

Middleware Integration: Use the MiddlewarePlugin to attach Laravel middleware to routes:

$router->group(['middleware' => ['auth', 'throttle:60']], function($router) {
    $router->get('/api', fn() => 'API Endpoint');
});

Routing Laravel Package