README

Browsers send batched reports — CSP violations, deprecations, network errors, crashes, and more — to a configured endpoint. This package registers that endpoint, decodes the payload, and dispatches Laravel events for each report type.

Requirements

• PHP 8.3+
• Laravel 13+

Installation

composer require audunru/reporting-api

The service provider is auto-discovered. The package registers a POST /reports route automatically.

Sending reports from a browser

Legacy CSP reports (application/csp-report)

Set the report-uri directive in your Content-Security-Policy header:

Content-Security-Policy: default-src 'self'; report-uri /reports

With spatie/laravel-csp:

// config/csp.php
'report_uri' => env('CSP_REPORT_URI', '/reports'),

Modern Reporting API (application/reports+json)

Use Reporting-Endpoints and report-to to send batched reports in the modern format:

Reporting-Endpoints: default="/reports"
Content-Security-Policy: default-src 'self'; report-to default

The modern format supports additional report types beyond CSP violations (deprecations, network errors, crashes, etc.).

With spatie/laravel-csp, add Directive::REPORT_TO in your Policy class:

use Spatie\Csp\Directive;
use Spatie\Csp\Policies\Basic;

class MyPolicy extends Basic
{
    public function configure(): void
    {
        parent::configure();
        $this->add(Directive::REPORT_TO, 'default');
    }
}

Also apply the reporting-endpoints middleware (see Middleware) so the Reporting-Endpoints header is sent to browsers alongside the CSP header.

For legacy browser fallback (Firefox and Safari do not support report-to), also set report_uri in config/csp.php. Modern browsers ignore report-uri when report-to is present, so each browser uses the right format automatically:

// config/csp.php
'report_uri' => env('CSP_REPORT_URI', '/reports'),

Getting started

When a report arrives the package dispatches a Laravel event based on the report type. The package ships two ready-made listeners — LogCspViolation and LogReport — that you can register directly in AppServiceProvider::boot():

use audunru\ReportingApi\Contracts\ReportEvent;
use audunru\ReportingApi\Events\CspViolationReceived;
use audunru\ReportingApi\Listeners\LogCspViolation;
use audunru\ReportingApi\Listeners\LogReport;
use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::listen(CspViolationReceived::class, LogCspViolation::class);
    Event::listen(ReportEvent::class, LogReport::class);
}

LogCspViolation logs CSP violations as warning. LogReport logs every other report type as info, with the full raw report in the log context. Neither is registered automatically.

Both log to the stack channel by default. Override protected string $channel to redirect to a different channel:

class MyCspViolationListener extends LogCspViolation
{
    protected string $channel = 'security';
}

Filtering noise with shouldExclude()

Browser extensions routinely trigger CSP reports. Override shouldExclude() in a subclass to filter them out:

// app/Listeners/MyCspViolationListener.php
namespace App\Listeners;

use audunru\ReportingApi\DTOs\CspViolationReport;
use audunru\ReportingApi\Listeners\LogCspViolation;

class MyCspViolationListener extends LogCspViolation
{
    private const EXTENSION_SCHEMES = [
        'chrome-extension://',
        'moz-extension://',
        'safari-extension://',
    ];

    protected function shouldExclude(CspViolationReport $report): bool
    {
        $blocked = $report->body->blockedURL ?? '';

        foreach (self::EXTENSION_SCHEMES as $scheme) {
            if (str_starts_with($blocked, $scheme)) {
                return true;
            }
        }

        return false;
    }
}

LogReport supports the same pattern via its Report base type:

// app/Listeners/MyReportListener.php
namespace App\Listeners;

use audunru\ReportingApi\DTOs\Report;
use audunru\ReportingApi\Listeners\LogReport;

class MyReportListener extends LogReport
{
    protected function shouldExclude(Report $report): bool
    {
        return $report->type === 'csp-violation'; // handled separately
    }
}

Register your subclasses the same way:

use audunru\ReportingApi\Contracts\ReportEvent;
use audunru\ReportingApi\Events\CspViolationReceived;
use App\Listeners\MyCspViolationListener;
use App\Listeners\MyReportListener;
use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::listen(CspViolationReceived::class, MyCspViolationListener::class);
    Event::listen(ReportEvent::class, MyReportListener::class);
}

Middleware

The package registers a reporting-endpoints middleware alias that adds the Reporting-Endpoints header to responses. Browsers use this header to discover where to POST their reports.

Apply it to specific routes or route groups:

Route::middleware('reporting-endpoints')->group(function () {
    Route::get('/', HomeController::class);
});

To add it globally to all web routes (Laravel 11+, bootstrap/app.php):

use audunru\ReportingApi\Http\Middleware\AddReportingEndpointsHeader;
use Illuminate\Foundation\Configuration\Middleware;

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        AddReportingEndpointsHeader::class,
    ]);
})

The header value uses the path from your config:

Reporting-Endpoints: default="/reports"

Configuration

Publish the config file to customise the endpoint path and throttle limit:

php artisan vendor:publish --tag=reporting-api-config

Reference

Dispatched events

Event interface

All event classes implement audunru\ReportingApi\Contracts\ReportEvent and expose:

Report DTOs

getReport() returns a typed DTO that extends audunru\ReportingApi\DTOs\Report, with properties common to all report types:

Each specific report DTO also has a typed body property whose class matches the report type:

Body classes are plain PHP objects with nullable readonly properties matching the W3C specification for that report type. For example, CspViolationReportBody exposes blockedURL, effectiveDirective, disposition, documentURL, originalPolicy, and so on.