Cors

HTTP access

Let the right frontends talk to your API.

Leaf CORS gives you a small, explicit configuration layer for browser access, preflight requests, credentials, and allowed origins.

app()->cors([

'origin' => ['https://app.example.com'],

'methods' => ['GET', 'POST'],

]);

Using Leaf MVC?

Use the MVC CORS guide when your configuration lives with the rest of your application environment.

Open MVC CORS ->

CORS is the browser security layer that decides which origins can read responses from your app. Since CORS is a common pain point for web developers, Leaf provides a first-party integration that takes care of the repetitive setup for you.

Setting Up

You can install the CORS module through the Leaf CLI or with composer.

Leaf CLI

leaf install cors

Composer

composer require leafs/cors

Enabling CORS

After installing the cors module, Leaf automatically links it to your app, so it can be used directly on the Leaf instance as the cors() method.

Functional Mode

app()->cors();

// ... your app

Class Mode

$app = new Leaf\App();
$app->cors();

// ... your app

This will allow all users from any website to access your app, even if they are on a website you didn't explicitly allow. If you want to restrict access to your app, you can pass in an array of options to the cors() method.

app()->cors([
  'origin' => ['http://example.com', 'http://example.org'],
  'methods' => ['GET', 'POST'],
]);

This will only allow users from http://example.com and http://example.org to access your app using the GET and POST methods. You can find a list of all available options below.

Origins are matched exactly, so each configured origin must be a full origin including the scheme, like https://example.com. A bare domain like example.com or any other partial value will not match. Matching the full origin is what keeps look-alike domains from being treated as yours.

If you want to allow a whole family of origins, such as every subdomain of a site, you can use a regular expression written as a string:

app()->cors([
  'origin' => '/^https:\/\/(.*\.)?example\.com$/',
]);

This will allow https://example.com and any of its subdomains, like https://app.example.com. You can also mix exact origins and regex strings in an array. When a specific origin matches, Leaf reflects the request's origin in the Access-Control-Allow-Origin header; with origin set to '*', the header is a literal *.

Credentials and origins

If you set credentials to true, pair it with explicit origins rather than '*'. Browsers reject credentialed responses that allow every origin.

Configuration Options

The cors() method takes in an array of options. Here are the available options:

• origin: Configures the Access-Control-Allow-Origin CORS header. Possible values:

  • String - set origin to a specific origin, including the scheme. For example if you set it to "https://example.com" only requests from "https://example.com" will be allowed. Origins are matched exactly; partial values like "example.com" will not match.
  • Regex string - set origin to a regular expression written as a string, which will be tested against the request origin. If it matches, the request origin will be reflected. For example '/^https:\/\/(.*\.)?example\.com$/' will allow "https://example.com" and any of its subdomains.
  • Array - set origin to an array of valid origins. Each origin can be an exact origin or a regex string. For example ['https://example1.com', '/^https:\/\/(.*\.)?example2\.com$/'] will accept requests from "https://example1.com" or from "example2.com" and its subdomains.

• credentials: Configures the Access-Control-Allow-Credentials CORS header. Set to true to pass the header, otherwise it is omitted. When enabling credentials, use explicit origins rather than '*', since browsers reject credentialed responses that allow every origin.

• methods: Configures the Access-Control-Allow-Methods CORS header. Expects a comma-delimited string (ex: 'GET,PUT,POST') or an array (ex: ['GET', 'PUT', 'POST']).

• allowedHeaders: Configures the Access-Control-Allow-Headers CORS header. Expects a comma-delimited string (ex: 'Content-Type,Authorization') or an array (ex: ['Content-Type', 'Authorization']). If not specified, defaults to reflecting the headers specified in the request's Access-Control-Request-Headers header.

• exposedHeaders: Configures the Access-Control-Expose-Headers CORS header. Expects a comma-delimited string (ex: 'Content-Range,X-Content-Range') or an array (ex: ['Content-Range', 'X-Content-Range']). If not specified, no custom headers are exposed.

• maxAge: Configures the Access-Control-Max-Age CORS header. Set to an integer to pass the header, otherwise it is omitted.

• preflightContinue: Pass the CORS preflight response to the next handler.

• optionsSuccessStatus: The status code returned for successful preflight OPTIONS requests, since some legacy browsers (IE11, various SmartTVs) choke on 204. Set it to 200 if you need to support those clients.

The default configuration is the equivalent of:

{
  "origin": "*",
  "methods": "GET,HEAD,PUT,PATCH,POST,DELETE",
  "allowedHeaders": "*",
  "exposedHeaders": "",
  "credentials": false,
  "maxAge": null,
  "preflightContinue": false,
  "optionsSuccessStatus": 204,
}