Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • SensioLabs Professional services to help you with Symfony
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Bundles
  4. NelmioCorsBundle
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • Installation
  • Configuration
  • Cookbook
    • How to ignore preflight requests on New Relic?

NelmioCorsBundle

Edit this page

NelmioCorsBundle

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

If you need it, check this flow chart image to have a global overview of entire CORS workflow.

Installation

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

1
$ composer require nelmio/cors-bundle

The bundle should be automatically enabled by Symfony Flex. If you don't use Flex, you'll need to manually enable the bundle by adding the following line in the config/bundles.php file of your project:

1
2
3
4
5
6
7
8
<?php
// config/bundles.php

return [
    // ...
    Nelmio\CorsBundle\NelmioCorsBundle::class => ['all' => true],
    // ...
];

If you don't have a config/bundles.php file in your project, chances are that you're using an older Symfony version. In this case, you should have an app/AppKernel.php file instead. Edit such file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = [
            // ...

            new Nelmio\CorsBundle\NelmioCorsBundle(),
        ];

        // ...
    }

    // ...
}

Configuration

Symfony Flex generates a default configuration in config/packages/nelmio_cors.yaml.

The options defined under defaults are the default values applied to all the paths that match, unless overridden 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
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: ~
        skip_same_as_origin: true
    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.

expose_headers can be set to * to accept any value as long as allow_credentials is false as per the specification.

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.

Cookbook

How to ignore preflight requests on New Relic?

On specific architectures with a mostly authenticated API, preflight request can represent a huge part of the traffic.

In such cases, you may not need to monitor on New Relic this traffic which is by the way categorized automatically as unknown by New Relic.

A request listener can be written to ignore preflight requests:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
use Symfony\Component\HttpKernel\Event\FilterResponseEvent;

class PreflightIgnoreOnNewRelicListener
{
    public function onKernelResponse(FilterResponseEvent $event)
    {
        if (!extension_loaded('newrelic')) {
            return;
        }

        if ('OPTIONS' === $event->getRequest()->getMethod()) {
            newrelic_ignore_transaction();
        }
    }
}

Register this listener, and voilà!

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:
    Symfony Code Performance Profiling

    Symfony Code Performance Profiling

    Code consumes server resources. Blackfire tells you how

    Code consumes server resources. Blackfire tells you how

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Wojciech Międzybrodzki, a Symfony contributor

    Thanks Wojciech Międzybrodzki (@wojciechem) for being a Symfony contributor

    1 commit • 2 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Algolia