fyre/csrf

A CSRF protetion library.

v5.0.1 2024-12-11 08:32 UTC

Requires

• fyre/config: ^4.1
• fyre/container: ^1.0
• fyre/middleware: ^6.0
• fyre/server: ^4.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.59
• fyre/php-cs-fixer-config: ^1.0
• phpunit/phpunit: ^11

MIT

• elusivecodes

README

FyreCSRF is a free, open-source CSRF protection library for PHP.

Table Of Contents

• Installation
• Basic Usage
• Methods
• Middleware

Installation

Using Composer

composer require fyre/csrf

In PHP:

use Fyre\Security\CsrfProtection;

Basic Usage

• $container is a Container.
• $config is a Config.

$csrfProtection = new CsrfProtection($container, $config);

Default configuration options will be resolved from the "Csrf" key in the Config.

• $options is an array containing the configuration options.
  • cookie is an array containing CSRF cookie options.
    • name is a string representing the cookie name, and will default to "CsrfToken".
    • expires is a number representing the cookie lifetime, and will default to 0.
    • domain is a string representing the cookie domain, and will default to "".
    • path is a string representing the cookie path, and will default to "/".
    • secure is a boolean indicating whether to set a secure cookie, and will default to true.
    • httpOnly is a boolean indicating whether to the cookie should be HTTP only, and will default to false.
    • sameSite is a string representing the cookie same site, and will default to "Lax".
  • salt is a string representing the CSRF session key and will default to "_csrfToken".
  • field is a string representing the CSRF token field name, and will default to "csrf_token".
  • header is a string representing the CSRF token header name, and will default to "Csrf-Token".
  • skipCheck is a Closure that accepts a ServerRequest as the first argument.

$container->use(Config::class)->set('Csrf', $options);

Autoloading

It is recommended to bind the CsrfProtection to the Container as a singleton.

$container->singleton(CsrfProtection::class);

Any dependencies will be injected automatically when loading from the Container.

$csrfProtection = $container->use(CsrfProtection::class);

Methods

Before Response

Update the ClientResponse before sending to client.

$response = $csrfProtection->beforeResponse($request, $response);

Check Token

Check CSRF token.

• $request is the ServerRequest.

$csrfProtection->checkToken($request);

Get Cookie Token

Get the CSRF cookie token.

$cookieToken = $csrfProtection->getCookieToken();

Get Field

Get the CSRF token field name.

$field = $csrfProtection->getField();

Get Form Token

Get the CSRF form token.

$formToken = $csrfProtection->getFormToken();

Get Header

Get the CSRF token header name.

$header = $csrfProtection->getHeader();

Middleware

use Fyre\Security\Middleware\CsrfProtectionMiddleware;

• $csrfProtection is a CsrfProtection.

$middleware = new CsrfProtectionMiddleware($csrfProtection);

Any dependencies will be injected automatically when loading from the Container.

$middleware = $container->build(CsrfProtectionMiddleware::class);

Handle

Handle a ServerRequest.

• $request is a ServerRequest.
• $next is a Closure.

$response = $middleware->handle($request, $next);

This method will return a ClientResponse.