README

phputil/cors

🔌 CORS middleware for phputil/router

Unit-tested ✔
Well-documented 📖
Syntax compatible with expressjs/cors 🎯

Installation

Requires phputil/router v0.2.14+

composer require phputil/cors

Usage

Basic usage

require_once 'vendor/autoload.php';
use phputil\router\Router;
use function phputil\cors\cors; // Step 1: Declare the namespace usage for the function.
$app = new Router();

$app->use( cors() ); // Step 2: Invoke the function to use it as a middleware.

$app->get( '/', function( $req, $res ) {
    $res->send( 'Hello' );
} );
$app->listen();

API

function cors( array|CorOptions $options ): callable;

$options can be an array or an object from the class CorOptions. All its keys/attributes are optional:

`origin`

Configures the response header Access-Control-Allow-Origin, which indicates the allowed origin.
Allowed types: bool, string, array.
true, the default value, reflects the Origin request header - that is, it allows any origin.
false makes it to return '*' as the header value.
A non-empty string value (e.g. 'mydomain.com') restricts the Origin to the defined value.
A non-empty array value indicates that Origin values are allowed.
When the Origin request header is not sent and the option origin is true, it will return * - aiming to accept any origin. Other options will block the request.
Using * may not work when using credentials or using httpS. Prefer sending the request header Origin whenever possible.

Note: The returned status code for an origin that is not in the configured list is 403 (Forbidden).

`credentials`

Configures the response header Access-Control-Allow-Credentials.
Allowed types: bool.
true, the default value, makes it to include the header.
false makes it to omit the header.
This header is important if your application uses cookies or some kind of authentication header.

`methods`

Configures the response header Access-Control-Allow-Methods.
Allowed types: string, array.
The default value is GET,HEAD,OPTIONS,POST,PUT,DELETE,PATCH when the request header Access-Control-Request-Method is not defined.
When the request header Access-Control-Request-Method is defined, the response header Access-Control-Allow-Methods will return the received method, unless the option methods is defined.
HTTP methods in a string must be separated by comma.

`allowedHeaders`

Configures the response header Access-Control-Allow-Headers.
Allowed types: string, array.
The default value is '*', meaning to accept any request header.
HTTP headers in a string must be separated by comma.

`exposedHeaders`

Configures the response header Access-Control-Expose-Headers.
Allowed types: string, array.
The default value is '' (empty string), meaning to not include the header.
HTTP headers in a string must be separated by comma.

`maxAge`

Configures the response header Access-Control-Max-Age.
Allowed types: int, null.
The default value is null, meaning to not include the header.
An int value means the number of seconds that a preflight request can be cached (by the browser).

Example

Using an array:

$options = [
    'origin' => 'mydomain.com',
    'methods' => 'GET,POST'
];

$app->use( cors( $options ) );

Using the class CorOptions, that has nestable builder methods with the prefix with:

use phputil\cors\CorsOptions; // Needed

$options = ( new CorsOptions() )
    ->withOrigin( 'mydomain.com' )
    ->withMethods( 'GET,POST' );

$app->use( cors( $options ) );

phputil / cors

Maintainers

Details