superpowers-sage:acorn-middleware

Middleware & Authentication

When to use

• Protecting Acorn routes with authentication (JWT, API tokens, custom guards)
• Request preprocessing: rate limiting, CSRF validation, locale detection
• Response postprocessing: adding headers, logging, caching
• Role / capability checks before a controller runs
• Route-specific authorization groups

When NOT to use

• Filtering native WordPress admin pages or register_rest_route() endpoints — middleware does NOT run there; use add_action('admin_init') / rest_pre_dispatch instead
• Template-hierarchy front-end pages (pages, archives, single posts) — use template_redirect action
• Business logic that should live in a service class
• Authentication for REST endpoints that bypass Acorn routes — extend wp-rest-api skill guidance instead

Prerequisites

• Acorn installed with a working routes/web.php or routes/api.php
• RouteServiceProvider booted
• For JWT: firebase/php-jwt installed via lando theme-composer require firebase/php-jwt

What Middleware Does in Acorn

Middleware filters HTTP requests before they reach route controllers — the same pipeline concept as Laravel. Each middleware inspects or transforms the request, then either passes it forward or returns a response early.

Critical distinction: Middleware only runs on Acorn-registered routes (defined in routes/web.php or routes/api.php). It does NOT intercept native WordPress requests (admin pages, REST API endpoints registered via register_rest_route(), or front-end page loads handled by the template hierarchy). Use add_action/add_filter hooks for WordPress-native requests.

Quick Start

# 1. Generate a middleware class
lando acorn make:middleware EnsureJsonResponse

# Or use the helper script (see Scripts section)
bash skills/acorn-middleware/scripts/create-middleware.sh MyMiddleware --type=filter

// app/Http/Middleware/EnsureJsonResponse.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class EnsureJsonResponse
{
    public function handle(Request $request, Closure $next): Response
    {
        $request->headers->set('Accept', 'application/json');
        return $next($request);
    }
}