barryvdh / laravel-cors
Adds CORS (Cross-Origin Resource Sharing) headers support in your Laravel application
Fund package maintenance!
barryvdh
Installs: 14 081 439
Dependents: 189
Suggesters: 4
Security: 0
Stars: 5 525
Watchers: 90
Forks: 521
Open Issues: 20
Language:JavaScript
Requires
- php: >=7.2
- asm89/stack-cors: ^2.0.1
- illuminate/contracts: ^6|^7|^8|^9
- illuminate/support: ^6|^7|^8|^9
- symfony/http-foundation: ^4|^5
- symfony/http-kernel: ^4.3.4|^5
Requires (Dev)
- laravel/framework: ^6|^7|^8
- orchestra/testbench-dusk: ^4|^5|^6
- phpunit/phpunit: ^6|^7|^8
- squizlabs/php_codesniffer: ^3.5
- dev-master / 2.0.x-dev
- v2.0.3
- v2.0.2
- v2.0.1
- v2.0.0
- v2.0.0-beta3
- v2.0.0-beta2
- v2.0.0-beta1
- 1.0.x-dev
- v1.0.6
- v1.0.5
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
- 0.11.x-dev
- v0.11.4
- v0.11.3
- v0.11.2
- v0.11.1
- v0.11.0
- v0.10.1
- v0.10.0
- v0.9.3
- v0.9.2
- v0.9.1
- v0.9.0
- v0.8.6
- v0.8.5
- V0.8.4
- v0.8.3
- v0.8.2
- v0.8.1
- v0.8.0
- v0.7.3
- v0.7.2
- v0.7.1
- v0.7.0
- v0.6.0
- v0.5.0
- v0.4.0
- 0.3.x-dev
- v0.3.0
- 0.2.x-dev
- v0.2.3
- v0.2.2
- v0.2.1
- v0.2.0
- v0.1.2
- v0.1.1
- v0.1
- dev-barryvdh-test-laravel9
- dev-test-single
- dev-feat-prependmiddleware
- dev-feat-requesthandled
- dev-feat-middlewaretest
- dev-feat-browsertests
- dev-feat-actions
- dev-feat-groupmiddleware
- dev-v1-backport
This package is auto-updated.
Last update: 2021-01-07 11:09:36 UTC
README
Implements https://github.com/asm89/stack-cors for Laravel
About
The laravel-cors
package allows you to send Cross-Origin Resource Sharing
headers with Laravel middleware configuration.
If you want to have a global overview of CORS workflow, you can browse this image.
Upgrading from 0.x / barryvdh-laravel-cors
When upgrading from 0.x versions, there are some breaking changes:
- A new 'paths' property is used to enable/disable CORS on certain routes. This is empty by default, so fill it correctly!
- Group middleware is no longer supported, use the global middleware
- The vendor name has changed (see installation/usage)
- The casing on the props in
cors.php
has changed from camelCase to snake_case, so if you already have acors.php
file you will need to update the props in there to match the new casing.
Features
- Handles CORS pre-flight OPTIONS requests
- Adds CORS headers to your responses
- Match routes to only add CORS to certain Requests
Installation
Require the fruitcake/laravel-cors
package in your composer.json
and update your dependencies:
composer require fruitcake/laravel-cors
If you get a conflict, this could be because an older version of barryvdh/laravel-cors or fruitcake/laravel-cors is installed. Remove the conflicting package first, then try install again:
composer remove barryvdh/laravel-cors fruitcake/laravel-cors composer require fruitcake/laravel-cors
Global usage
To allow CORS for all your routes, add the HandleCors
middleware at the top of the $middleware
property of app/Http/Kernel.php
class:
protected $middleware = [ \Fruitcake\Cors\HandleCors::class, // ... ];
Now update the config to define the paths you want to run the CORS service on, (see Configuration below):
'paths' => ['api/*'],
Configuration
The defaults are set in config/cors.php
. Publish the config to copy the file to your own config:
php artisan vendor:publish --tag="cors"
Note: When using custom headers, like
X-Auth-Token
orX-Requested-With
, you must set theallowed_headers
to include those headers. You can also set it to['*']
to allow all custom headers.
Note: If you are explicitly whitelisting headers, you must include
Origin
or requests will fail to be recognized as CORS.
Options
Option | Description | Default value |
---|---|---|
paths | You can enable CORS for 1 or multiple paths, eg. ['api/*'] |
array() |
allowed_origins | Matches the request origin. Wildcards can be used, eg. *.mydomain.com |
array('*') |
allowed_origins_patterns | Matches the request origin with preg_match . |
array() |
allowed_methods | Matches the request method. | array('*') |
allowed_headers | Sets the Access-Control-Allow-Headers response header. | array('*') |
exposed_headers | Sets the Access-Control-Expose-Headers response header. | false |
max_age | Sets the Access-Control-Max-Age response header. | 0 |
supports_credentials | Sets the Access-Control-Allow-Credentials header. | false |
allowed_origins
, allowed_headers
and allowed_methods
can be set to ['*']
to accept any value.
Note: For
allowed_origins
you must include the scheme when not using a wildcard, eg.['http://example.com', 'https://example.com']
. You must also take into account that the scheme will be present when usingallowed_origins_patterns
.
Note: Try to be a specific as possible. You can start developing with loose constraints, but it's better to be as strict as possible!
Note: Because of http method overriding in Laravel, allowing POST methods will also enable the API users to perform PUT and DELETE requests as well.
Lumen
On Lumen, just register the ServiceProvider manually in your bootstrap/app.php
file:
$app->register(Fruitcake\Cors\CorsServiceProvider::class);
Also copy the cors.php config file to config/cors.php
and put it into action:
$app->configure('cors');
Global usage for Lumen
To allow CORS for all your routes, add the HandleCors
middleware to the global middleware and set the paths
property in the config.
$app->middleware([ // ... Fruitcake\Cors\HandleCors::class, ]);
Common problems
Error handling, Middleware order
Sometimes errors/middleware that return own responses can prevent the CORS Middleware from being run. Try changing the order of the Middleware and make sure it's the first entry in the global middleware, not a route group. Also check your logs for actual errors, because without CORS, the errors will be swallowed by the browser, only showing CORS errors.
Authorization headers / Credentials
If your Request includes an Authorization header or uses Credentials mode, set the supports_credentials
value in the config to true. This will set the Access-Control-Allow-Credentials Header to true
.
Echo/die
If you echo()
, dd()
, die()
, exit()
, dump()
etc in your code, you will break the Middleware flow. When output is sent before headers, CORS cannot be added. When the scripts exits before the CORS middleware finished, CORS headers will not be added. Always return a proper response or throw an Exception.
Disabling CSRF protection for your API
If possible, use a route group with CSRF protection disabled.
Otherwise you can disable CSRF for certain requests in App\Http\Middleware\VerifyCsrfToken
:
protected $except = [ 'api/*' ];
License
Released under the MIT License, see LICENSE.