The spatie/laravel-csp package manages Content Security Policy (CSP) headers in Laravel applications by allowing configuration through a published config file (`config/csp.php`) and middleware registration. It provides flexibility to handle CSP headers differently based on environment settings and other conditions.
How CSP Headers Are Handled in Different Environments
- Enable/Disable CSP Based on Environment Variable: The package uses the `enabled` configuration option, which is typically set via an environment variable `CSP_ENABLED`. This allows you to globally enable or disable CSP headers depending on the environment (e.g., enabled in production, disabled in local or testing environments). For example:
php
'enabled' => env('CSP_ENABLED', true),
This means you can set `CSP_ENABLED=false` in your `.env` file for local development to disable CSP headers without changing code[1].
- Report-Only Mode for Testing: The package supports "report-only" CSP policies through `report_only_presets` and `report_only_directives` config keys. This mode allows you to test new or modified CSP rules without enforcing them, by sending violation reports to a specified URI (`report_uri`) without blocking content. This is useful in staging or development environments before fully enabling CSP enforcement in production[1].
- Handling CSP During Hot Reloading: There is a configuration option `enabled_while_hot_reloading` (default false) that controls whether CSP headers are added when using tools like Vite's hot module replacement. This helps avoid CSP conflicts during local development when assets are dynamically served[1].
- Nonce Generation Control: The package can generate nonces for inline scripts and styles to allow safe inline execution. This is controlled by `nonce_enabled` (default true) and can be disabled in environments where nonce handling is problematic or inline styles/scripts are allowed via `'unsafe-inline'` directives[1].
Middleware Registration and Policy Selection
- CSP headers are added by registering the `Spatie\Csp\AddCspHeaders` middleware globally or on specific routes/groups. This middleware reads the config and applies the CSP headers accordingly.
- You can specify different CSP presets (policy classes) globally in the config or override them per route by passing a preset class to the middleware, allowing environment-specific or route-specific CSP policies:
php
Route::get('my-page', 'MyController')->middleware(AddCspHeaders::class . ':' . MyCustomPreset::class);
This enables fine-grained control over CSP policies depending on the environment or route context[1][6].
Summary
- The package uses environment variables (`CSP_ENABLED`, `CSP_REPORT_URI`, `CSP_ENABLED_WHILE_HOT_RELOADING`, `CSP_NONCE_ENABLED`) to toggle CSP headers and features per environment.
- It supports report-only mode for safe testing of policies.
- Middleware can be applied globally or per route, with the ability to specify different CSP presets dynamically.
- Nonce generation can be enabled or disabled based on environment needs.
- Hot reloading environments can have CSP disabled to avoid development conflicts.
This design provides a flexible and environment-aware approach to managing CSP headers in Laravel applications using spatie/laravel-csp[1][2][6].
Citations:
[1] https://github.com/spatie/laravel-csp
[2] https://spatie.be/blog/releasing-laravel-csp-3-and-a-call-for-contributors
[3] https://stackoverflow.com/questions/77821829/issue-when-implementing-csp-on-existing-laravel-project-eval-and-inline-style
[4] https://github.com/spatie/laravel-csp/blob/main/UPGRADE.md
[5] https://scalybee.com/laravel-content-security-policy-safeguarding-web-application/
[6] https://laravel-news.com/laravel-content-security-policies
[7] https://univahost.com/blog/laravel-application/
[8] https://stackoverflow.com/questions/75977506/laravel-csp-content-security-policy-frontegg-ui-integrate-issue
[9] https://stackoverflow.com/questions/78864184/enable-nonce-to-laravel-official-packages