nelmio/cors-bundle

Adds CORS (Cross-Origin Resource Sharing) headers support in your Symfony2 application

Installs: 2 692 105

Dependents: 53

Suggesters: 6

Stars: 372

Watchers: 18

Forks: 45

Open Issues: 12

Type:symfony-bundle

1.5.3 2017-04-24 09:12 UTC

README

About

The NelmioCorsBundle allows you to send Cross-Origin Resource Sharing headers with ACL-style per-URL configuration.

If you want to have a global overview of CORS workflow, you can browse this image.

Features

  • Handles CORS preflight OPTIONS requests
  • Adds CORS headers to your responses

Installation

Require the nelmio/cors-bundle package in your composer.json and update your dependencies.

$ composer require nelmio/cors-bundle

Add the NelmioCorsBundle to your application's kernel:

    public function registerBundles()
    {
        $bundles = array(
            // ...
            new Nelmio\CorsBundle\NelmioCorsBundle(),
            // ...
        );
        // ...
    }

Configuration

The defaults are the default values applied to all the paths that match, unless overriden in a specific URL configuration. If you want them to apply to everything, you must define a path with ^/.

This example config contains all the possible config values with their default values shown in the defaults key. In paths, you see that we allow CORS requests from any origin on /api/. One custom header and some HTTP methods are defined as allowed as well. Preflight requests can be cached for 3600 seconds.

    nelmio_cors:
        defaults:
            allow_credentials: false
            allow_origin: []
            allow_headers: []
            allow_methods: []
            expose_headers: []
            max_age: 0
            hosts: []
            origin_regex: false
            forced_allow_origin_value: ~
        paths:
            '^/api/':
                allow_origin: ['*']
                allow_headers: ['X-Custom-Auth']
                allow_methods: ['POST', 'PUT', 'GET', 'DELETE']
                max_age: 3600
            '^/':
                origin_regex: true
                allow_origin: ['^http://localhost:[0-9]+']
                allow_headers: ['X-Custom-Auth']
                allow_methods: ['POST', 'PUT', 'GET', 'DELETE']
                max_age: 3600
                hosts: ['^api\.']

allow_origin and allow_headers can be set to * to accept any value, the allowed methods however have to be explicitly listed. paths must contain at least one item.

If origin_regex is set, allow_origin must be a list of regular expressions matching allowed origins. Remember to use ^ and $ to clearly define the boundaries of the regex.

By default, the Access-Control-Allow-Origin response header value is the Origin request header value (if it matches the rules you've defined with allow_origin), so it should be fine for most of use cases. If it's not, you can override this behavior by setting the exact value you want using forced_allow_origin_value.

Be aware that even if you set forced_allow_origin_value to *, if you also set allow_origin to http://example.com, only this specific domain will be allowed to access your resources.

Note: If you allow POST methods and have HTTP method overriding enabled in the framework, it will enable the API users to perform PUT and DELETE requests as well.

License

Released under the MIT License, see LICENSE.