How to Use CORS in Laravel API: Simple Setup Guide

To use CORS in a Laravel API, install and configure the fruitcake/laravel-cors package or use Laravel's built-in CORS support in app/Http/Middleware/HandleCors.php. Then, publish the config file and set allowed origins, methods, and headers in config/cors.php to control cross-origin requests.

Syntax

Laravel handles CORS through middleware that intercepts HTTP requests and adds the necessary headers to allow cross-origin access.

The main parts are:

• HandleCors middleware: Processes CORS headers.
• config/cors.php: Configuration file where you specify allowed origins, methods, headers, and other options.
• Kernel.php: Middleware registration to apply CORS globally or to specific routes.

php

<?php
// config/cors.php
return [
    'paths' => ['api/*'],
    'allowed_methods' => ['*'],
    'allowed_origins' => ['*'],
    'allowed_headers' => ['*'],
    'exposed_headers' => [],
    'max_age' => 0,
    'supports_credentials' => false,
];

Example

This example shows how to enable CORS for all API routes in Laravel using the built-in middleware and default configuration.

php

<?php
// 1. Ensure middleware is registered in app/Http/Kernel.php
protected $middleware = [
    // ... other middleware ...
    \Fruitcake\Cors\HandleCors::class,
];

// 2. Publish the config file (run in terminal):
// php artisan vendor:publish --provider="Fruitcake\Cors\CorsServiceProvider"

// 3. Edit config/cors.php to allow all origins and methods
return [
    'paths' => ['api/*'],
    'allowed_methods' => ['*'],
    'allowed_origins' => ['*'],
    'allowed_headers' => ['*'],
    'exposed_headers' => [],
    'max_age' => 0,
    'supports_credentials' => false,
];

// 4. Now, any request to routes under /api/* will have CORS headers allowing cross-origin access.

Output

When you make a cross-origin request to your Laravel API under /api/*, the response will include headers like:
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: *

Common Pitfalls

Common mistakes when using CORS in Laravel include:

• Not registering the HandleCors middleware globally or on API routes, so headers are not added.
• Setting allowed_origins to ['*'] but also enabling supports_credentials to true, which is invalid.
• Forgetting to publish and customize the config/cors.php file after installing the package.
• Not handling preflight OPTIONS requests properly, causing CORS errors.

Example of a wrong config and fix:

php

<?php
// Wrong config: allows credentials with wildcard origin
return [
    'paths' => ['api/*'],
    'allowed_methods' => ['*'],
    'allowed_origins' => ['*'],
    'allowed_headers' => ['*'],
    'supports_credentials' => true, // This causes errors
];

// Fix: specify exact origins when using credentials
return [
    'paths' => ['api/*'],
    'allowed_methods' => ['*'],
    'allowed_origins' => ['https://example.com'],
    'allowed_headers' => ['*'],
    'supports_credentials' => true,
];

Quick Reference

Setting	Description	Example Value
paths	API routes to apply CORS to	['api/*']
allowed_methods	HTTP methods allowed	['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'] or ['*']
allowed_origins	Origins allowed to access API	['https://example.com'] or ['*']
allowed_headers	Headers allowed in requests	['Content-Type', 'Authorization'] or ['*']
supports_credentials	Allow cookies/auth headers	true or false
max_age	Seconds browser caches preflight	0 or 3600

Key Takeaways

Enable CORS in Laravel by registering the HandleCors middleware and configuring config/cors.php.

Set allowed origins, methods, and headers carefully to control cross-origin access.

Avoid using wildcard origins with credentials enabled to prevent CORS errors.

Publish the CORS config file after installing the package to customize settings.

Ensure preflight OPTIONS requests are handled by the middleware for smooth CORS support.