README

A PSR-15 CORS middleware for Slim Framework 4, requiring PHP 8.5.

Spiritual successor to tuupola/cors-middleware (unmaintained) — same array-based options and behavior, rebuilt as a small, dependency-free PSR-15 middleware with no legacy baggage.

Install

Published on Packagist.

composer require apigopro/slim-cors-middleware

Basic usage

use SlimCors\CorsMiddleware;

$app->add(new CorsMiddleware([
    'origin'         => ['https://app.example.com', 'https://*.example.com'],
    'methods'        => ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
    'headers.allow'  => ['Authorization', 'Content-Type'],
    'headers.expose' => ['X-Request-Id'],
    'credentials'    => true,
    'cache'          => 86400,
]));

Add this before (outer to) your auth middleware, so preflight OPTIONS requests get answered without ever reaching auth checks or route handlers — browsers send preflight requests without credentials or custom auth headers, so they'd otherwise fail auth for no reason.

$app->add(new CorsMiddleware([/* ... */]));   // outermost
$app->add(new JwtAuthMiddleware([/* ... */])); // runs after CORS

How it works

• No Origin header → not a cross-origin request, passed through untouched.
• Origin present, not preflight → the wrapped handler runs as normal, then Access-Control-Allow-Origin (and friends) get added to the response.
• Preflight (OPTIONS + Access-Control-Request-Method header present) → answered directly with a 204, without calling the rest of the middleware stack or your route handler at all.
• Preflight requesting a method not in methods → rejected with 405 and an Allow header listing what is allowed (or your custom error response).
• Origin not in the allow-list → rejected with 401 (or your custom error response).

Options

Wildcard origin patterns

new CorsMiddleware([
    'origin' => [
        'https://app.example.com',
        'https://*.staging.example.com', // any staging subdomain
    ],
]);

* matches any sequence of characters within a single pattern; it isn't a full glob/regex language, just a simple prefix/suffix/subdomain wildcard.

Migrating from tuupola/cors-middleware

• Namespace: Tuupola\Middleware\CorsMiddleware → SlimCors\CorsMiddleware.
• logger option removed. Wire up your own logging in the error callback if you need it.
• error callback signature is unchanged: ($request, $response, array $arguments).
• Everything else — origin, methods, headers.allow, headers.expose, credentials, cache — behaves the same way.

Testing

composer install
composer test

Covers: pass-through for non-CORS requests, allowed/disallowed origins, wildcard origin patterns (including the credentials + * interaction), preflight short-circuiting, method validation (405 for disallowed methods, wildcard * methods, case-insensitive matching), configured vs. reflected Access-Control-Allow-Headers, Access-Control-Expose-Headers, and custom error callbacks for both origin and method rejections.

License

MIT.