gadwinn / csrf
CSRF protection with single-use tokens, keyed token stacks (multi-tab friendly) and an optional PSR-15 middleware.
Requires
- php: >=8.3
Requires (Dev)
- phpdocumentor/shim: *
- phpstan/phpstan: *
- phpunit/phpunit: *
- povils/phpmnd: *
- psr/http-message: ^1.1 || ^2.0
- psr/http-server-handler: ^1.0
- psr/http-server-middleware: ^1.0
- roave/security-advisories: dev-latest@dev
- squizlabs/php_codesniffer: *
Suggests
- psr/http-message: Required to use the PSR-15 CSRF middleware (^1.1 || ^2.0)
- psr/http-server-handler: Required to use the PSR-15 CSRF middleware (^1.0)
- psr/http-server-middleware: Required to use the PSR-15 CSRF middleware (^1.0)
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 11:12:20 UTC
README
A paranoid-level CSRF protection library with flexible token management for PHP 8.3+.
Solves the classic conflict between single-use tokens (security) and multi-tab browsing (UX) through a keyed stack storage system.
Installation
composer require gadwinn/csrf
Requirements
- PHP >= 8.3
Session Configuration via SessionConfig
SessionTokenStorage starts the session itself when none is active. Pass it a SessionConfig to apply your session policy before session_start() - this is the recommended approach for production:
use G\Csrf\CsrfManager; use G\Csrf\TokenGenerator\RandomTokenGenerator; use G\Csrf\TokenStorage\SessionConfig; use G\Csrf\TokenStorage\SessionTokenStorage; $storage = new SessionTokenStorage(new SessionConfig( name: '__Secure-app_session', savePath: '/var/lib/php/sessions/myapp', cacheLimiter: 'nocache', cookieLifetime: 0, cookiePath: '/', cookieDomain: 'example.com', cookieSecure: true, cookieHttponly: true, cookieSamesite: 'Strict', )); $csrf = new CsrfManager(new RandomTokenGenerator(), $storage);
The session key names are also configurable:
new SessionTokenStorage(new SessionConfig(sessionKey: '_app_csrf', defaultKey: '_global'));
Session settings are applied only when the session is not yet active. If you start the session yourself before instantiation, the session settings are ignored (the session is already configured).
The session is checked again on every operation: in a long-running worker (FrankenPHP worker mode…), the same storage instance reopens the session of each new request by itself.
All SessionConfig options
| Parameter | PHP function | Default |
|---|---|---|
sessionKey |
(internal $_SESSION key) |
'_csrf_tokens' |
defaultKey |
(default token name) | '_default' |
name |
session_name() |
null (skip) |
savePath |
session_save_path() |
null (skip) |
moduleName |
session_module_name() |
null (skip) |
cacheLimiter |
session_cache_limiter() |
null (skip) |
cacheExpire |
session_cache_expire() |
null (skip) |
cookieLifetime |
session_set_cookie_params() |
null (skip) |
cookiePath |
session_set_cookie_params() |
null (skip) |
cookieDomain |
session_set_cookie_params() |
null (skip) |
cookieSecure |
session_set_cookie_params() |
null (skip) |
cookieHttponly |
session_set_cookie_params() |
null (skip) |
cookieSamesite |
session_set_cookie_params() |
null (skip) |
Manual Session Configuration
SessionTokenStorage calls session_start() automatically if no session is active. This is convenient but not recommended in production : calling session_start() without options uses PHP's defaults, which are often too permissive.
For better security, start the session yourself before instantiating the storage, using the PHP session configuration functions:
session_name('__Secure-app_session'); session_save_path('/var/lib/php/sessions/myapp'); // isolated from other apps on the server session_set_cookie_params([ 'lifetime' => 0, // session cookie (expires on browser close) 'path' => '/', 'domain' => 'example.com', 'secure' => true, // HTTPS only 'httponly' => true, // not accessible via JavaScript 'samesite' => 'Strict', // blocks cross-site requests entirely ]); session_start();
When a session is already active, SessionTokenStorage skips its own session_start() call entirely and uses the existing session as-is.
session_set_cookie_params()andsession_name()must be called beforesession_start(), otherwise they have no effect.
Quick Start
use G\Csrf\CsrfManager; use G\Csrf\TokenGenerator\RandomTokenGenerator; use G\Csrf\TokenStorage\SessionTokenStorage; // Recommended: configure and start the session before instantiation session_set_cookie_params(['secure' => true, 'httponly' => true, 'samesite' => 'Strict']); session_start(); $csrf = new CsrfManager( new RandomTokenGenerator(), new SessionTokenStorage() ); // Generate a token and embed it in a form $token = $csrf->generateToken('contact_form'); echo '<input type="hidden" name="csrf_token" value="' . htmlspecialchars($token) . '">'; // Validate on form submission (token is consumed on first use) if ($csrf->isValid($_POST['csrf_token'], 'contact_form')) { // Valid - process the form }
Key Syntax
The $key parameter controls how tokens are stored. Three formats are supported:
null - Default token
$csrf->generateToken(); // store $csrf->isValid($token); // validate
A single token with no named key. Overwritten on each call to generateToken().
'name' - Named atomic token
$csrf->generateToken('login'); $csrf->isValid($token, 'login');
One token per key. Each new generation replaces the previous one. Suited for simple forms where only one active token is needed at a time.
'name[]' - Named stack (default limit)
$csrf->generateToken('checkout[]'); $csrf->isValid($token, 'checkout[]');
Maintains a stack of up to 10 tokens (default) for this key. Each generation pushes a new token; the oldest is dropped when the limit is reached. Each validation consumes exactly one token from the stack.
Suited for forms that may be open in multiple tabs simultaneously.
'name[n]' - Named stack (custom limit)
$csrf->generateToken('search[3]'); // stack of max 3 tokens $csrf->isValid($token, 'search[3]');
Same behavior as name[] with an explicit maximum size.
API Reference
CsrfManager
| Method | Description |
|---|---|
generateToken(?string $key): string |
Generate a token, store it, and return it |
isValid(string $token, ?string $key): bool |
Validate a token and consume it if valid |
getToken(?string $key): ?string |
Retrieve the current token without consuming it |
SessionTokenStorage
new SessionTokenStorage( config: new SessionConfig(), // storage keys and session settings defaultMaxTokens: 10, // default stack size for name[] syntax ttl: 1800 // token lifetime in seconds (default: 30 min) )
| Method | Description |
|---|---|
setToken(string $token, ?string $key): void |
Store a token |
getToken(?string $key): ?string |
Retrieve a token |
hasToken(string $token, ?string $key): bool |
Check if a token exists (timing-safe) |
deleteToken(string $token, ?string $key): void |
Delete a token (only if the value matches) |
consumeToken(string $token, ?string $key): bool |
Check and delete a token in one step |
A name is either a single token or a stack, never both: using 'form[]' while 'form' holds a single token throws a LogicException.
Expired tokens are cleaned up automatically on every operation.
RandomTokenGenerator
new RandomTokenGenerator(length: 32) // length in hexadecimal characters
Generates cryptographically secure hex tokens via random_bytes(). The length cannot be lower than RandomTokenGenerator::MIN_LENGTH (32 characters, 128 bits): a shorter one throws an InvalidArgumentException.
$generator->generate(); // returns a 32-character hex string
Extending
Both SessionTokenStorage and RandomTokenGenerator implement interfaces, making them easy to swap:
use G\Csrf\TokenStorage\TokenStorageInterface; class RedisTokenStorage implements TokenStorageInterface { // implement setToken, getToken, hasToken, deleteToken, consumeToken } $csrf = new CsrfManager(new RandomTokenGenerator(), new RedisTokenStorage(...));
Security Design
| Feature | Implementation |
|---|---|
| Cryptographic generation | random_bytes() + bin2hex() |
| Timing-attack protection | hash_equals() on all comparisons |
| Single-use enforcement | Token is deleted immediately after successful validation |
| Automatic expiry | TTL stored alongside each token; expired tokens removed on every operation |
| Stack overflow prevention | Oldest tokens pruned when stack limit is reached |
| Minimum entropy | Tokens shorter than 32 hex characters are refused |
Out of scope, left to the application: rate limiting of failed attempts and logging of CSRF failures (wrap CsrfManager or handle CsrfTokenMismatchException).
AJAX Usage
Include the token in the request body or a custom header:
fetch('/api/action', { method: 'POST', headers: { 'X-CSRF-Token': document.querySelector('[name=csrf_token]').value }, });
$token = $_SERVER['HTTP_X_CSRF_TOKEN'] ?? ''; if (!$csrf->isValid($token, 'api_action')) { http_response_code(403); exit; }
PSR-15 Middleware
The library includes an optional PSR-15 middleware (G\Csrf\Middleware) that delegates CSRF protection to CsrfManager. It requires psr/http-message, psr/http-server-handler, and psr/http-server-middleware - install them only if you use the middleware.
composer require psr/http-message psr/http-server-handler psr/http-server-middleware
How it works
On every supervised request (POST, PUT, PATCH, DELETE), the middleware:
- Reads the token from the
_tokenfield of the parsed body, thenX-CSRF-Tokenheader, thenX-XSRF-Tokenheader - Reads the CSRF key from the PSR-7 request attribute
csrf_key - Calls
CsrfManager::isValid($token, $key)- which validates and consumes the token in one step - Passes to the next handler if valid, or calls the failure handler if not
All other methods (GET, HEAD, OPTIONS, …) pass through without any check.
Quick Start
use G\Csrf\CsrfManager; use G\Csrf\TokenGenerator\RandomTokenGenerator; use G\Csrf\TokenStorage\SessionTokenStorage; use G\Csrf\Middleware\CsrfMiddleware; session_set_cookie_params(['secure' => true, 'httponly' => true, 'samesite' => 'Strict']); session_start(); $csrf = new CsrfManager(new RandomTokenGenerator(), new SessionTokenStorage()); $middleware = new CsrfMiddleware($csrf);
Configuration via CsrfConfig
Override the defaults with a CsrfConfig:
use G\Csrf\Middleware\CsrfConfig; use G\Csrf\Middleware\CsrfMiddleware; $middleware = new CsrfMiddleware($csrf, config: new CsrfConfig( tokenField: '_csrf', supervisedMethods: ['POST', 'PUT'], ));
| Parameter | Default | Description |
|---|---|---|
tokenKeyAttribute |
'csrf_key' |
PSR-7 request attribute name |
tokenField |
'_token' |
POST body field name |
tokenHeaders |
['X-CSRF-Token', 'X-XSRF-Token'] |
Headers checked in order |
supervisedMethods |
['POST', 'PUT', 'PATCH', 'DELETE'] |
Methods requiring validation |
Token Key
The middleware reads the token key from the PSR-7 request attribute CsrfMiddleware::TOKEN_KEY_ATTRIBUTE ("csrf_key"):
$request = $request->withAttribute(CsrfMiddleware::TOKEN_KEY_ATTRIBUTE, 'checkout');
If the attribute is absent or not a string, the middleware falls back to null (unnamed token slot).
Custom Failure Handler
By default, FailureRequestHandler throws a G\Csrf\Exception\CsrfTokenMismatchException (to be turned into a 403 response by your error handling). Replace it with any RequestHandlerInterface:
use Psr\Http\Message\{ServerRequestInterface, ResponseInterface}; use Psr\Http\Server\RequestHandlerInterface; class CsrfFailureHandler implements RequestHandlerInterface { public function handle(ServerRequestInterface $request): ResponseInterface { return (new ResponseFactory())->createResponse(403); } } $middleware = new CsrfMiddleware($csrf, new CsrfFailureHandler());
License
MIT, see LICENSE.