Filters

Filters in Lightpack are reusable hooks that run before or after a controller action. They are typically used for authentication, authorization, CSRF protection, rate limiting, CORS, and other request/response concerns.

How Filters Work

• Before filters can halt the request and return a response before the controller action runs.
• After filters can modify the response after the controller action runs. Modify the passed $response and return it.
• Filters can be attached to individual routes or route groups.

Usage

Attaching Filters to Routes

// Single filter
route()->get('/dashboard', DashboardController::class)->filter('auth');

// Multiple filters
route()->post('/posts', PostController::class)->filter(['csrf', 'auth']);

Grouping Filters

route()->group(['filter' => ['csrf', 'auth']], function() {
    route()->get('/dashboard', DashboardController::class);
});

Halting or Modifying Requests

• To halt a request early (e.g., unauthorized), return a Response from the filter’s before() method.
• To modify the response, update the passed $response and return it from the filter’s after() method.

Defining Custom Filters

php console create:filter TrimFilter

A filter is a class implementing the Lightpack\Filters\FilterInterface interface:

class TrimFilter implements FilterInterface
{
    public function before(Request $request, array $params = [])
    {
        // Logic before action
    }

    public function after(Request $request, Response $response, array $params = []): Response
    {
        // Logic after action
        return $response;
    }
}

Register your filter alias in boot/filters.php:

return [
    'trim' => App\Filters\TrimFilter::class,
];

Built-in Filters

Lightpack provides many pre-defined filters that you can declare on your route definitions. Below are the built-in filters provided by Lightpack, their aliases, and what they do:

1. auth

Purpose: Restricts access to authenticated users (web or API).

• Web: First attempts silent login via remember-me cookie (auth()->recall()). If that fails, redirects to login and stores the intended URL for redirect after login.
• API: Returns 401 JSON if token is missing or invalid.
• Params: ['web'] (default) or ['api'].

2. guest

Purpose: Restricts access to guests only.

• Redirects logged-in users to config('auth.routes.authenticated', 'dashboard').

3. csrf

Purpose: Protects against CSRF attacks.

• Checks for a valid CSRF token on POST, PUT, PATCH, DELETE.
• Throws SessionExpiredException if the session token is missing.
• Throws InvalidCsrfTokenException if the submitted token does not match.
• Bypasses in APP_ENV=testing.

4. cors

Purpose: Handles Cross-Origin Resource Sharing.

• Responds to OPTIONS requests with CORS headers.
• Adds CORS headers to all responses.
• Uses headers from config('cors.headers').

5. limit

Purpose: API rate limiting.

• Limits requests per user or IP to a configurable max per time window.
• Keys are resolved as user:{id}:{path} for authenticated users, or ip:{ip}:{path} for guests.
• Throws 429 with rate limit headers if exceeded.
• Params: [maxRequests, minutes]. Defaults from config('limit.default').

6. signed

Purpose: Ensures URL signatures are valid.

• Returns 403 (JSON or error view) if the request signature is invalid.

7. verifyemail

Purpose: Restricts access to users with verified email addresses.

• Redirects to the verify.email route (web) or returns 403 JSON (API) if the user’s email is not verified.

8. mfa

Purpose: Enforces Multi-Factor Authentication.

• If MFA is enforced or the user has enabled MFA, triggers the MFA flow and redirects to the mfa.verify.show route.
• Skips if already verified in the current session (session()->get('mfa_passed')).

Filter Parameters

You can pass parameters to filters via the route definition:

route()->get('/api/data', ApiController::class)->filter(['limit:100,5']);

• For limit, this would allow 100 requests per 5 minutes.

Best Practices

• Order matters: Filters run in the order they’re listed.
• Return a Response: To halt further processing, return a Response from before().
• Chainable: Filters from groups and routes are merged and deduplicated.
• Testing: CSRF filter is disabled in test environment.

Summary Table