# basecom/magento2-csp-split-header

> Magento 2 module to split oversized CSP headers into multiple headers.

`composer require basecom/magento2-csp-split-header`

Canonical URL: https://packagento.com/basecom/magento2-csp-split-header

## At a glance

- **Vendor**: basecom (https://packagento.com/basecom.md)
- **Latest version**: 1.0.7 — released 2025-03-24
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/basecom/magento2-csp-split-header and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require basecom/magento2-csp-split-header:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

Magento 2 module to split oversized CSP headers into multiple headers.

## README

<div align="center">

[![Packagist][ico-version]][link-packagist]
[![Software License][ico-license]](LICENSE)
![Supported Magento Versions][ico-compatibility]

</div>

---

> [!IMPORTANT]  
> As of Magento 2.4.7 it is no longer possible to deactivate the Magento CSP module.

With a growing _Content Security Policies_ (CSP) whitelist, the problem can arise that the
headers `Content-Security-Policy-Report-Only` and/or `Content-Security-Policy` become so large that they exceed the
maximum permitted size of a header field, causing the web server to not process the response any further.

The CSP mechanism allows multiple policies to be specified for a resource, including via the `Content-Security-Policy`
header, the `Content-Security-Policy-Report-Only` header and a `meta`
element [[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#multiple_content_security_policies)].
__Therefore, the headers can be specified more than once.__

This is where the module comes into play. It implements an _after method plugin_ for the
method `Magento\Csp\Model\Policy\Renderer\SimplePolicyHeaderRenderer::render`, which replaces the existing CSP headers
via the method `\Magento\Framework\App\Response\HttpInterface::setHeader`. The header is read, split so that the syntax
remains valid, and replaced by the new headers. The result is a separate header for each directive, each of which should
no longer exceed the maximum permitted length of the web server.

> [!TIP]
> If the headers are too large even after splitting, try to identify unnecessary Magento modules and remove them.

### Installation

1. Install it into your Magento 2 project with composer:

    ```console
    composer require basecom/magento2-csp-split-header
    ```

2. Enable module

    ```console
    bin/magento setup:upgrade
    ```

### Configuration

| Config                                                      | Default Value  | Description                                                |
|-------------------------------------------------------------|----------------|------------------------------------------------------------|
| `basecom_csp_split_header/settings/header_splitting_enable` | 0 _(disabled)_ | enables (1) / disables (0) the splitting of the CSP header |
| `basecom_csp_split_header/settings/max_header_size`         | 8000           | maximum allowed header field size                          |

These values can be updated in the system configuration under `Basecom -> Content Security Policy -> Enable`.

### Example

1. CSP splitting _disabled_

    ```HTTP
    Content-Security-Policy: default-src 'self' https://example.com; connect-src 'none'; script-src https://example.com/;                          
    ```

2. CSP splitting _enabled_

    ```HTTP
    Content-Security-Policy: default-src 'self' https://example.com; 
    Content-Security-Policy: connect-src 'none'; 
    Content-Security-Policy: script-src https://example.com/;                          
    ```

### Known Issues

#### CSP header is not split correctly ([#5](https://github.com/basecom/magento2-csp-split-header/issues/5))

Lower the maximum allowed header field size threshold in the config `basecom_csp_split_header/settings/max_header_size`.

#### Varnish 503 error ([#7](https://github.com/basecom/magento2-csp-split-header/issues/7))

Increase the Varnish header size`http_resp_hdr_len`. The default value is 8kb.

### Contributing

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

### Security

If you discover any security related issues, please email <magento@basecom.de> instead of using the issue tracker.

### License

The MIT License (MIT). Please see [License File](LICENSE) for more information.

### Copyright

&copy; 2024 basecom GmbH & Co. KG

[ico-version]: https://img.shields.io/packagist/v/basecom/magento2-csp-split-header.svg?style=flat-square
[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square
[ico-compatibility]: https://img.shields.io/badge/magento-2.4-brightgreen.svg?logo=magento&longCache=true&style=flat-square

[link-packagist]: https://packagist.org/packages/basecom/magento2-csp-split-header

## Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.1.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

### [Unreleased]

#### Added

#### Changed

#### Removed

#### Fixed

### [1.0.7] - 2025-03-24

#### Added

- Added `Known issues` section in the README

#### Changed

- Changed the default value of `basecom_csp_split_header/settings/max_header_size` from 8190 to 8000.

### [1.0.6] - 2024-10-07

#### Fixed

- Fix duplicate policy and reduce number of splits. [@mfickers](https://github.com/mfickers) [#4](https://github.com/basecom/magento2-csp-split-header/pull/4)

### [1.0.5] - 2024-08-27

#### Added

- Added missing tab ID in system.xml. [@eneskirca](https://github.com/eneskirca) [#3](https://github.com/basecom/magento2-csp-split-header/pull/3)

### [1.0.4] - 2024-08-08

#### Changed

- Changed max_header_size from 8000 to the Apache default of 8190.

### [1.0.3] - 2024-08-07

#### Added

- Added GitHub action to automatically set tag.

### [1.0.2] - 2024-08-05

#### Added

- Added README.

### [1.0.1] - 2024-08-02

#### Fixed

- Fixed issue where the fetch directive was added twice to the CSP header content.

### [1.0.0] - 2024-08-02

[1.0.7]: https://github.com/basecom/magento2-csp-split-header/compare/v1.0.6...v1.0.7
[1.0.6]: https://github.com/basecom/magento2-csp-split-header/compare/v1.0.5...v1.0.6
[1.0.5]: https://github.com/basecom/magento2-csp-split-header/compare/v1.0.4...v1.0.5
[1.0.4]: https://github.com/basecom/magento2-csp-split-header/compare/v1.0.3...v1.0.4
[1.0.3]: https://github.com/basecom/magento2-csp-split-header/compare/v1.0.2...v1.0.3
[1.0.2]: https://github.com/basecom/magento2-csp-split-header/compare/v1.0.1...v1.0.2
[1.0.1]: https://github.com/basecom/magento2-csp-split-header/compare/v1.0.0...v1.0.1
[1.0.0]: https://github.com/basecom/magento2-csp-split-header/releases/tag/v1.0.0

## Recent Versions

| Version | Released |
|---|---|
| 1.0.7 | 2025-03-24 |
| 1.0.6 | 2024-10-07 |
| 1.0.5 | 2024-08-27 |
| 1.0.4 | 2024-08-08 |
| 1.0.3 | 2024-08-07 |
| 1.0.2 | 2024-08-06 |
| 1.0.1 | 2024-08-05 |
| 1.0.0 | 2024-08-02 |

## Dependencies

### Require

| Package | Constraint |
|---|---|
| magento/framework | * |
| magento/module-backend | * |
| magento/module-config | * |
| magento/module-csp | * |
| php | ~8.1 |

## Quality

Latest release (1.0.7) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | Pass |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Warning | 2 | 2 warnings (ruleset: Magento2) |
| PHPMD | Warning | 1 | 1 rule violation (UnusedPrivateField:1) |
| Cpd | Pass | 0 |  |
| Composer validate | Info | 5 | valid; 5 advisory notes (composer validate --strict) |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 2 | 2 | – | – |
| 2.4.8 | – | 2 | 2 | – |
| 2.4.9 | – | – | 2 | 2 |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["basecom/magento2-csp-split-header"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

basecom is a Magento 2 vendor on Packagento. See https://packagento.com/basecom.md for their full catalogue.