DEV Community: Shakil Alam

How We Implemented Content Security Policy (CSP) in Our Laravel App

Shakil Alam — Fri, 08 May 2026 13:08:47 +0000

Our pentest report had one line that stopped us cold:

"Application does not implement Content-Security-Policy headers. XSS payloads executed without restriction."

We had Sanctum, CSRF tokens, input validation — all the standard Laravel security checklist items. But we had no CSP. And without it, a single successful XSS attack could exfiltrate session cookies, inject malicious scripts, or silently redirect users to attacker-controlled pages — all from our own domain.

This is the story of how we added CSP to a production Laravel application without breaking anything, how we built a violation reporting pipeline, and the things we wish we'd known before starting.

What's in this guide

This post is written to be useful regardless of where you're starting from:

Never heard of CSP? Start from the top. The first two sections give you the mental model before any code appears.
Know what CSP is but haven't implemented it? Jump to The Implementation.
Already running CSP and want to tighten it or add reporting? Jump to CSP Violation Reporting or the Pre-Enforcement Checklist.

What Content Security Policy Actually Does

When a browser loads a page, it executes whatever scripts, styles, fonts, and images are on it — regardless of where they came from. That's what makes XSS dangerous: if an attacker manages to inject a <script> tag into your HTML, the browser runs it without question.

CSP is an HTTP response header that changes this. It tells the browser: "Only trust resources from these specific sources. Anything else — block it."

Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-abc123'; object-src 'none'

With that header in place, even if an attacker injects a <script> tag, the browser refuses to execute it. The tag has no valid nonce — a cryptographically random token generated fresh for each request. Scripts carrying the matching nonce run. Everything else is blocked.

New to this? MDN has the definitive CSP reference if you want to go deeper on any specific directive.

What Is a Nonce?

You'll see the word "nonce" throughout this post, so let's settle it quickly before writing any code.

A nonce (short for number used once) is a random string generated fresh on every single page load. The server puts it in the CSP header, and also stamps it onto every <script> or <style> block it trusts:

// In the HTTP header the server sends:
Content-Security-Policy: script-src 'nonce-k8Hv2mXpQ3'

// On the script tag in your HTML:
<script nonce="k8Hv2mXpQ3">...</script>

The browser sees both, checks they match, and runs the script. If an attacker injects a <script> tag, it has no nonce — or the wrong one — so it gets blocked. Since the nonce changes on every request, an attacker who somehow saw yesterday's nonce can't reuse it today.

Why not just use a static secret key? Because a static value could be cached, leaked in logs, or extracted from your source code. A nonce only needs to survive one request. After that, it's worthless.

What a nonce is not:

It is not a replacement for input sanitisation. A nonce stops injected scripts from running. It doesn't stop them from being stored in your database.
It is not encryption. Anyone who can see the page source can see the nonce — that's fine, because it expires the moment the request ends.
It is not a CSRF token. They look similar in concept but solve completely different problems.

That's it. When you see nonce="{{ $cspNonce }}" in templates below, it simply means: "the server trusts this specific block."

The Naive Approach (and Why It Fails)

Most teams discover CSP when a security audit flags it, then reach for the quickest fix: a static header in nginx.conf or apache.conf.

This works for about five minutes. Then the inline JavaScript breaks. Alpine.js stops. Livewire stops. Any <script> block that doesn't come from a separate file gets blocked. The knee-jerk reaction is:

script-src 'self' 'unsafe-inline'

Done. Everything works again. And CSP is now completely useless — 'unsafe-inline' means any inline script can run, including one an attacker injected.

The correct approach is a nonce-based CSP generated per request inside Laravel, where every trusted inline script carries a token only the server knows. That's what we built.

The Mindset Shift: Write CSP-Friendly Code

Before writing a single line of middleware, you need to change how you write templates. CSP doesn't just enforce a header — it enforces discipline about where your code lives.

Move JavaScript out of your HTML. Event handler attributes are the main offender:

<!-- ❌ This is blocked by any sensible CSP -->
<button onclick="submitForm()">Submit</button>
<script>function submitForm() { ... }</script>

<!-- ✅ This is CSP-friendly — JS lives in an external file -->
<button id="submit-btn">Submit</button>
<script src="/js/form.js"></script>

Move styles out of your HTML too. The style="" attribute on elements cannot carry a nonce — there's no mechanism to whitelist individual instances. Your only options with a strict policy are "allow all of them" or "block all of them." Build the habit of using CSS classes from the start.

For inline code you genuinely can't move — a config value JavaScript needs, critical above-the-fold CSS — the nonce is your escape hatch:

<script nonce="{{ $cspNonce }}">
    window.APP_ENV = "{{ config('app.env') }}";
</script>

A nonce is generated fresh on every request. An attacker can't predict it. A script they inject has no nonce, so it gets blocked even if everything else fails.

Pro Tip: Never hardcode a nonce, never reuse one. Generate it with random_bytes() — not uniqid(), not md5(time()).

Just want the output without the reading? I built a free Laravel CSP Generator — toggle your CDNs and integrations, and it generates the full policy string, the PHP middleware method, and an adaptive pre-enforcement checklist live. Come back here for the why behind each decision.

The Implementation

We put all security headers in one SecureHeadersMiddleware rather than spreading logic across nginx.conf, .htaccess, and multiple middleware files.

Step 1: Generate the Nonce and Share It

php artisan make:middleware SecureHeadersMiddleware

<?php

declare(strict_types=1);

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Vite;
use Illuminate\Support\Facades\View;
use Symfony\Component\HttpFoundation\Response;

class SecureHeadersMiddleware
{
    // Disable in local/testing to avoid log noise from developer browsers
    // full of extensions. Automatically driven by the current environment.
    private bool $allowReporting;

    public function __construct()
    {
        $this->allowReporting = !app()->environment(['local', 'testing']);
    }

    public function handle(Request $request, Closure $next): Response
    {
        $nonce = base64_encode(random_bytes(16));

        // Share with all Blade templates automatically — no manual passing needed
        View::share('cspNonce', $nonce);

        // Tell Vite to inject this nonce on its bootstrapping inline script.
        // Skip this and @vite() silently breaks under a strict CSP.
        Vite::useCspNonce($nonce);

        /** @var Response $response */
        $response = $next($request);

        $this->addContentSecurityPolicy($response, $nonce, $request);
        $this->addClickjackingProtection($response);
        $this->addStrictTransportSecurity($response, $request);
        $this->addMiscSecurityHeaders($response);
        $this->removeUnwantedHeaders($response);

        if ($this->allowReporting && $this->supportsReportTo($request)) {
            $this->addCspReportingEndpoint($response);
        }

        return $response;
    }
}

Two ordering rules matter here. The nonce must be generated before $next($request) because the view renders during that call. The headers are set after because they need the response object. Swap either and things break silently.

Step 2: Define the CSP Policy

protected function addContentSecurityPolicy(Response $response, string $nonce, Request $request): void
{
    $isLocal = app()->environment('local');

    $policy = [
        "default-src 'self'",
        "script-src 'self' 'nonce-{$nonce}' https://cdn.jsdelivr.net https://cdnjs.cloudflare.com https://embed.tawk.to",
        "style-src 'self' 'nonce-{$nonce}' https://fonts.googleapis.com https://cdnjs.cloudflare.com",
        "style-src-elem 'self' 'nonce-{$nonce}' https://fonts.googleapis.com https://cdnjs.cloudflare.com",
        "style-src-attr 'none'",
        "font-src 'self' data: https://fonts.gstatic.com https://cdnjs.cloudflare.com",
        "img-src 'self' data: https://cdn.jsdelivr.net https://cdnjs.cloudflare.com https://your-cdn.example.com",
        "frame-src 'self' https://your-video-host.example.com",

        // Vite's HMR uses a WebSocket on localhost — only needed in local dev.
        // Never ship localhost entries to production.
        "connect-src 'self'" . ($isLocal ? " ws://localhost:5173 wss://localhost:5173" : ""),

        "object-src 'none'",
        "base-uri 'self'",
        "frame-ancestors 'none'",
    ];

    // upgrade-insecure-requests on a local HTTP server triggers confusing
    // mixed-content errors that have nothing to do with your code.
    if (!$isLocal) {
        $policy[] = 'upgrade-insecure-requests';
    }

    if ($this->allowReporting) {
        $policy[] = 'report-uri /api/csp-violation-report';
    }

    $response->headers->set('Content-Security-Policy', implode('; ', $policy));
}

Directive reference — what each one actually does:

Directive	What it controls	Our value
`default-src`	Fallback for any type not explicitly listed	`'self'`
`script-src`	JavaScript execution	`'self'` + nonce + CDN allowlist
`style-src`	CSS `@import` rules within stylesheets; base fallback	`'self'` + nonce + CDN allowlist
`style-src-elem`	`<link rel="stylesheet">` and `<style>` blocks	`'self'` + nonce + CDN allowlist
`style-src-attr`	Inline `style=""` attributes	`'none'` (blocked entirely)
`font-src`	Font files	`'self'` + data URIs + Google Fonts
`img-src`	Images	`'self'` + data URIs + CDN
`frame-src`	`<iframe>` sources	`'self'` + trusted video host
`connect-src`	`fetch()`, XHR, WebSockets, SSE	`'self'` + localhost WS in dev
`object-src`	Browser plugins (Flash, Java)	`'none'`
`base-uri`	The `<base>` tag's `href`	`'self'`
`frame-ancestors`	Who can embed this page in an iframe	`'none'`

default-src 'self' means anything not covered by a specific directive falls back to same-origin only.

script-src is where most of the work happens. The nonce is per-request, cryptographically random, and unpredictable. In CSP Level 3, the presence of a nonce automatically overrides 'unsafe-inline' for supporting browsers — so even if you add it as a temporary fallback, modern browsers ignore it in favour of nonce validation.

connect-src controls everything your JavaScript can talk to: fetch(), XMLHttpRequest, WebSockets, and Server-Sent Events. Vite's Hot Module Replacement uses a WebSocket on localhost:5173 to push changes to your browser during development. Without it in connect-src, HMR fails silently and you're doing hard refreshes all day. In production, that entry must not appear — hence the environment check.

object-src 'none' blocks Flash and all other browser plugins. There's no reason to allow these in 2026.

base-uri 'self' prevents an attacker from injecting <base href="https://evil.com">, which would silently redirect all relative URLs — links, form actions, script paths — to their server.

frame-ancestors 'none' is clickjacking protection at the CSP level: your pages cannot be embedded in iframes on other domains. Stronger than X-Frame-Options for modern browsers; we keep X-Frame-Options too for legacy ones.

upgrade-insecure-requests tells the browser to automatically upgrade HTTP sub-resource requests to HTTPS. We skip it in local development because it causes confusing mixed-content errors on a plain HTTP dev server.

Deep Dive: `style-src`, `style-src-elem`, and `style-src-attr`

Most developers assume these three are aliases for the same thing and only set style-src. They're not — and that misunderstanding is what causes hours of debugging when styles randomly break.

The one-line summary: style-src is the fallback. style-src-elem controls <style> blocks and <link> tags. style-src-attr controls style="" attributes on elements. Set all three explicitly, or the browser decides how to inherit, which is rarely what you want.

Here's the breakdown:

style-src is the base rule that covers everything CSS-related when the more specific directives aren't set. Even when you do set the others, style-src still governs one thing they don't: CSS @import rules inside your own stylesheets. @import url('https://fonts.googleapis.com/...') is controlled by style-src, not style-src-elem.

style-src-elem controls two things: <link rel="stylesheet"> tags and <style> blocks. The important detail is that <style> blocks can carry a nonce, so you can precisely whitelist only the inline styles you wrote:

{{-- Trusted — nonce matches the header --}}
<style nonce="{{ $cspNonce }}">
    .hero { background: url('/img/hero.jpg') center/cover; }
</style>

{{-- Blocked — no nonce --}}
<style>.injected { color: red; }</style>

External stylesheets via <link href="..."> don't need a nonce — they're controlled by the domain allowlist. Nonces only apply to inline content.

style-src-attr controls only the inline style="" attribute on HTML elements — and this is the problem child. style="" attributes cannot carry a nonce. There is no way to whitelist specific ones. Your only two options are 'unsafe-inline' (trusts all of them, including anything injected) or 'none' (blocks all of them). We use 'none'.

style-src       → CSS @import in files + base fallback  → 'self' + nonce + CDN
style-src-elem  → <link> tags + <style> blocks          → nonce-gated
style-src-attr  → style="" attributes                   → 'none', blocked entirely

Before you enable this: audit your JavaScript-driven UI libraries. Drag-and-drop, tooltips, and modals commonly set style="top: 48px; left: 200px" dynamically — every one of them will break under style-src-attr 'none'. Run in report-only mode first and your logs will tell you exactly which libraries are the offenders before anything breaks in production.

Step 3: Use the Nonce in Blade

{{-- Vite assets — no nonce attribute needed on the tag itself.
     Vite::useCspNonce() in the middleware handles the inline bootstrapper. --}}
@vite(['resources/css/app.css', 'resources/js/app.js'])

{{-- Inline script blocks you write manually --}}
<script nonce="{{ $cspNonce }}">
    const config = @json($appConfig);
</script>

{{-- Inline style blocks --}}
<style nonce="{{ $cspNonce }}">
    .hero { background: url('/img/hero.jpg') center/cover; }
</style>

{{-- Livewire v2 --}}
@livewireScripts(['nonce' => $cspNonce])

{{-- Livewire v3 --}}
@livewireScriptConfig(['nonce' => $cspNonce])

One thing to be clear on: <script src="..."> and <link rel="stylesheet" href="..."> tags pointing to external files do not need a nonce attribute. The browser permits them if their domain is on the allowlist. Nonces exist purely for inline content that has no domain to verify against.

Step 4: Add the Rest of the Security Header Stack

CSP is one layer. The same middleware handles the remaining browser security headers — each in a focused method:

protected function addClickjackingProtection(Response $response): void
{
    // Legacy browsers fall back to this; modern ones use frame-ancestors from CSP
    $response->headers->set('X-Frame-Options', 'DENY');
}

protected function addStrictTransportSecurity(Response $response, Request $request): void
{
    // Check X-Forwarded-Proto too — without this, HSTS is never sent when
    // you're behind a load balancer that terminates SSL before Laravel sees the request
    $isHttps = $request->isSecure()
        || strcasecmp((string) $request->header('X-Forwarded-Proto', ''), 'https') === 0;

    if (!$isHttps) {
        return;
    }

    $response->headers->set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');
}

protected function addMiscSecurityHeaders(Response $response): void
{
    // Prevents browsers from MIME-sniffing a response away from the declared content-type
    $response->headers->set('X-Content-Type-Options', 'nosniff');

    // Controls what's sent in the Referer header on navigation
    $response->headers->set('Referrer-Policy', 'strict-origin-when-cross-origin');

    // Deprecated and ignored by modern browsers, but harmless to include
    $response->headers->set('X-XSS-Protection', '1; mode=block');

    // Restrict access to sensitive browser APIs
    $response->headers->set('Permissions-Policy', 'geolocation=(), microphone=(self), camera=(self), payment=(), fullscreen=*');
}

protected function removeUnwantedHeaders(Response $response): void
{
    // Both calls are needed: Symfony's header management and PHP's header() function
    // operate at different levels. Without both, X-Powered-By: PHP/8.x can still leak.
    foreach (['X-Powered-By', 'Server'] as $header) {
        $response->headers->remove($header);
        @header_remove($header);
    }
}

Step 5: Register the Middleware

// Laravel 11 — bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \App\Http\Middleware\SecureHeadersMiddleware::class,
    ]);
})

// Laravel 10 — app/Http/Kernel.php
protected $middlewareGroups = [
    'web' => [
        // ...
        \App\Http\Middleware\SecureHeadersMiddleware::class,
    ],
];

Attaching it to the web group means your JSON API routes — which don't render Blade views — don't receive an unnecessary CSP header. For high-throughput APIs that's a meaningful separation.

CSP Violation Reporting — Your Early Warning System 🚨

Running CSP without a reporting endpoint is like setting a burglar alarm with no monitoring. You need to know when the policy blocks something — to catch misconfigurations before users do, and to detect real injection attempts.

What a Violation Report Looks Like

When a browser blocks something, it POSTs a JSON payload to your report endpoint. Here's what that looks like:

{
  "csp-report": {
    "document-uri": "https://yourapp.com/dashboard",
    "referrer": "",
    "violated-directive": "script-src-elem",
    "effective-directive": "script-src-elem",
    "original-policy": "default-src 'self'; script-src 'self' 'nonce-abc123'",
    "blocked-uri": "https://evil.com/injected.js",
    "status-code": 200
  }
}

The blocked-uri tells you what was blocked. The violated-directive tells you which rule caught it. Together they tell you immediately whether this is a legitimate resource you forgot to allowlist or something that should never have been there.

Hosted alternative: If you'd rather not build your own reporting pipeline, report-uri.com by Scott Helme is a dedicated CSP report collection and analysis service. It handles noise filtering, dashboards, and alerting for you.

The Route

// routes/api.php
Route::post('/csp-violation-report', [CspReportController::class, 'store'])
    ->middleware('throttle:5');

throttle:5 limits to 5 reports per minute per IP. Without rate limiting, an attacker can flood your logging infrastructure by triggering violations in a loop — exhausting disk space or burying real threats in noise.

The Controller

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Api;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\RateLimiter;

class CspReportController
{
    public function store(Request $request)
    {
        $body = json_decode($request->getContent(), true);
        $report = $body['csp-report'] ?? $body ?? [];

        if (empty($report) || !is_array($report)) {
            return response()->noContent();
        }

        $json = json_encode($report);
        $ip = $request->ip();
        $blockedUri = data_get($report, 'blocked-uri', '');
        $violatedDirective = data_get($report, 'violated-directive', '');

        // Browser extensions are the biggest source of CSP noise.
        // Ad blockers, password managers, and DevTools extensions all fire reports.
        // They're not actionable — filter them immediately.
        if (
            str_contains($json, 'chrome-extension://') ||
            str_contains($json, 'moz-extension://') ||
            str_contains($json, 'safari-extension://')
        ) {
            return response()->noContent();
        }

        // Low-risk: usually your own code or a library doing something non-standard.
        // Review weekly, not immediately.
        $lowRiskUris = ['about:blank', 'blob:', 'data:', 'inline', 'eval'];

        if (in_array($blockedUri, $lowRiskUris)) {
            Log::channel('csp_low')->info('Low-risk CSP violation', compact('ip', 'report'));
            return response()->noContent();
        }

        // High-risk: an external domain, an unknown script, potentially injected content.
        // Log with full context. Alert if sustained.
        Log::channel('csp_high')->warning('High-risk CSP violation', compact('ip', 'report'));

        $this->checkForThresholdAlert($ip, $blockedUri, $violatedDirective);

        return response()->noContent();
    }

    protected function checkForThresholdAlert(string $ip, string $uri, string $directive): void
    {
        // Same IP, same directive, 10+ times in 60 seconds = probe, not noise.
        $key = "csp_alert:$ip:{$directive}:$uri";

        if (RateLimiter::tooManyAttempts($key, 10)) {
            Log::alert('CSP threshold exceeded — possible active attack', [
                'ip'        => $ip,
                'uri'       => $uri,
                'directive' => $directive,
            ]);
            return;
        }

        RateLimiter::hit($key, 60);
    }
}

Log Channels

// config/logging.php
'csp_low' => [
    'driver' => 'single',
    'path'   => storage_path('logs/csp-low-risk.log'),
    'level'  => 'info',
],

'csp_high' => [
    'driver' => 'single',
    'path'   => storage_path('logs/csp-high-risk.log'),
    'level'  => 'warning',
],

Separate files let you set different retention policies — low-risk logs rotate weekly, high-risk logs stay for 90 days. In production, wire Log::alert() into Slack or PagerDuty so a spike in high-risk violations at 2 AM wakes someone up.

The Modern Report-To Header

For Chrome 70+, Edge 79+, and Firefox 60+, the Reporting API (Report-To header) is more efficient than report-uri — reports are batched, and the endpoint is cached so the browser sends reports even from pages that didn't include the header.

protected function supportsReportTo(Request $request): bool
{
    $ua = $request->header('User-Agent', '');

    return (bool) preg_match(
        '/(Chrome\/([7-9][0-9]|[1-9][0-9]{2,}))|(Firefox\/(6[0-9]|[7-9][0-9]|[1-9][0-9]{2,}))|(Edg\/([7-9][0-9]|[1-9][0-9]{2,}))|(Version\/(1[3-9]|[2-9][0-9])) Safari\//',
        $ua
    );
}

protected function addCspReportingEndpoint(Response $response): void
{
    $reportTo = [
        'group'              => 'csp-endpoint',
        'max_age'            => 10886400, // 126 days — browser caches this endpoint
        'endpoints'          => [
            ['url' => url('/api/csp-violation-report')],
        ],
        'include_subdomains' => true,
    ];

    $response->headers->set('Report-To', json_encode($reportTo, JSON_UNESCAPED_SLASHES));
}

We keep report-uri in the CSP policy as a fallback for browsers that don't support the Reporting API. Both can coexist.

Pre-Enforcement Checklist

Run through this before switching from report-only to enforcement mode:

[ ] Vite::useCspNonce($nonce) is called before $next($request) in the middleware
[ ] @vite(), @livewireScripts(), and @livewireScriptConfig() all pass the nonce
[ ] Every hand-written inline <script> block has nonce="{{ $cspNonce }}"
[ ] Every hand-written inline <style> block has nonce="{{ $cspNonce }}"
[ ] onclick="", onsubmit="", and other event handler attributes are removed from templates
[ ] style="" attributes are replaced with CSS classes (or the library using them is documented)
[ ] All CDN domains you load from are in the appropriate allowlist
[ ] connect-src includes your API endpoints, WebSocket hosts, and analytics targets
[ ] connect-src does not include localhost in your production policy
[ ] The violation report endpoint is live, throttled, and log channels are configured
[ ] Report-only mode has run in production for at least one week with no new high-risk violations

Deploy Safely: Start in Report-Only Mode

If you're adding CSP to an existing app, don't jump straight to enforcement. Swap the header name first:

// Change this:
$response->headers->set('Content-Security-Policy', implode('; ', $policy));

// To this, temporarily:
$response->headers->set('Content-Security-Policy-Report-Only', implode('; ', $policy));

The browser reports violations but blocks nothing. Run it in production for one to two weeks and watch csp-high-risk.log. Every entry is either a resource to allowlist or evidence of something that should never have been there. Once the log goes quiet, flip back to Content-Security-Policy.

This step is what separates a smooth rollout from an angry support queue.

Verify your headers: Use securityheaders.com to grade your response headers. Use Google's CSP Evaluator to check your policy for common weaknesses. Both are free.

What We'd Do Differently

Drop X-XSS-Protection. It's deprecated and ignored by modern browsers. Older IE versions had a bug where it could be exploited. We kept it because it doesn't actively hurt anything, but new implementations shouldn't bother.

Separate concerns if your team is large. Bundling all headers in one middleware works well for us, but a dedicated CspMiddleware is easier to unit test and simpler to replace later. Spatie's laravel-csp package gives you a structured, per-policy-class approach with first-class test support if you want to skip the custom build entirely.

Use hashes for truly static inline content. If you have a small piece of inline CSS that can't move to a stylesheet — a background colour from a database value, for example — CSP supports SHA-256 hashes as an alternative to nonces. You precompute the hash of the exact string and whitelist it. Surgical precision with no runtime overhead.

Explicitly exclude the api group from the middleware. Our implementation attaches the middleware to the web group, which already keeps it off pure API routes. If your app registers any routes globally — or if you ever move to a flat route file — API responses will silently start receiving a CSP header they don't need. Being explicit with a group exclusion is safer than relying on registration order:

// Laravel 11 — bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \App\Http\Middleware\SecureHeadersMiddleware::class,
    ]);
    // api group intentionally excluded — JSON responses don't need CSP
})

The Result

After two weeks in report-only mode and one afternoon of allowlist tuning, we flipped to enforcement. Our security headers score went from D to A+ on securityheaders.com.

Since then, csp-high-risk.log has caught two incidents where a third-party CDN attempted to inject tracking scripts we never authorised. The middleware caught what code review wouldn't have.

If you want to configure your own policy without writing it from scratch, the Laravel CSP Generator lets you do it visually — toggle your CDNs, integrations, and environment settings, and it outputs the full policy string and PHP middleware method ready to paste. The pre-enforcement checklist is built in and adapts to whatever you've configured.

CSP isn't a silver bullet — it's one layer in a defence-in-depth approach alongside CSRF protection, input validation, prepared statements, and HTTPS. But unlike most defences, it actively stops an entire class of attacks at the browser level, rather than hoping your application-layer defences caught everything upstream.

Start in report-only mode today. Watch your logs for a week. Then enforce. 🚀

Get the Quick Reference PDF

If you want a single document to keep open while you're building — the full directive reference, the pre-enforcement checklist, common mistakes, and quick-start snippets — I put it all in a 4-page PDF.

Drop your email below and it'll land in your inbox immediately. No series, no spam — just the PDF.

→ Get the Laravel CSP Quick Reference PDF

4 pages · All 13 directives · Pre-enforcement checklist · 5 common mistakes · Free

Frequently Asked Questions

Does CSP break existing Laravel apps?

It can — specifically if you have inline scripts or styles without nonces. Use Content-Security-Policy-Report-Only first to surface everything that would be blocked, fix your templates, then switch to enforcement. This is the only safe migration path for an app that's already in production.

Do I need CSP if I already have CSRF protection?

Yes. They protect against different attacks. CSRF prevents forged requests originating from other domains. CSP prevents injected scripts from running on your domain. One does not substitute for the other.

Do I need CSP if my app has no user-generated content?

Yes. XSS doesn't require users to submit anything. A vulnerable dependency, a compromised CDN script, or a DOM-based XSS through a URL parameter are all real attack vectors that have nothing to do with user uploads.

My Vite HMR stopped working after I added CSP. What's wrong?

Two things to check. First, confirm Vite::useCspNonce($nonce) is called before $next($request). Second, confirm connect-src includes ws://localhost:5173 (or your Vite port) in your local environment. HMR uses a WebSocket and fails silently if that WebSocket connection is blocked.

What's the difference between report-uri and Report-To?

report-uri is the original mechanism and is widely supported. Report-To is the newer Reporting API — reports are batched, the endpoint URL is cached by the browser for months, and it covers more than just CSP. Use both: report-uri as the universal fallback, Report-To for modern browsers. Alternatively, skip rolling your own and use report-uri.com.

How do I debug CSP violations locally?

Open DevTools → Console. Every CSP violation logs the exact blocked resource and the violated directive. That's your fastest debugging tool. If you're in report-only mode, the same violations also appear without anything actually breaking.

How do I handle CSP with Livewire?

Livewire injects inline JavaScript that needs the nonce. For v2: @livewireScripts(['nonce' => $cspNonce]). For v3: @livewireScriptConfig(['nonce' => $cspNonce]). Both are shown in Step 3 above.

What about Google Analytics or Tag Manager?

Add https://www.googletagmanager.com to script-src and https://www.google-analytics.com to both script-src and connect-src. GTM's custom HTML tags require 'unsafe-inline', which weakens your policy — server-side GTM or direct GA4 integration are cleaner alternatives worth the migration cost.

Can I use Spatie's laravel-csp package instead of a custom middleware?

Absolutely. Spatie's package provides a structured, per-policy-class approach with built-in nonce support and first-class test utilities. Our custom middleware made sense for us because we wanted every security header in one place without a package dependency. Either approach is valid — choose based on your team's preference for control versus convention.

Have you implemented CSP on a production Laravel app? Whether you had a smooth rollout, hit a rough edge with a third-party library, or are still sitting in report-only mode wondering what to do next — drop a comment. I'd love to hear where you got stuck, or what blocked resources surprised you most when you first flipped it on.

Laravel External API Reliability: When Their System Goes Down

Shakil Alam — Mon, 04 May 2026 08:47:07 +0000

TL;DR — Third-party APIs will go down. This article walks through building a Laravel trait that makes your failure policy explicit per model (not buried in a catch block), adds a recovery path for failed syncs, and handles idempotency so retries don't create duplicate records. Skip to The Sync Trait if you're already familiar with the problem.

Series: Part 4 of 4 — Laravel Architecture Patterns for Production

Reading time: ~9 minutes

Level: Intermediate — some Laravel experience helps, but key concepts are explained inline

Your code is correct. Your tests pass. Your application has been running fine for months.

Then a third-party API goes down at 2am on a Tuesday.

Registrations fail. Transaction syncs fail. Verification flows return 500s. Your queue fills with retry jobs. Users see errors they cannot act on. When the API comes back two hours later, you have a backlog of failed operations and no systematic way to recover them.

None of this was a failure of your code. It was a failure of your design to account for something that was always going to happen.

The question is not how to prevent third-party outages — you cannot. The question is: when they happen, does your system behave, or does it just fail?

What you will build

A trait that makes the fallback decision explicit in the model — not buried in a catch block
A fail-loud default with a deliberate opt-in to fail-silent, per model
A recovery pattern so failed syncs become retryable, not permanent data loss
An answer to the idempotency question — what happens if the local write fails after the external API already succeeded?

The problem with try-catch at the call site

New to traits? A PHP trait is a reusable block of methods you can use inside any class. Think of it as copy-pasting methods in, except the language handles it cleanly. In Laravel, traits are commonly added to Eloquent models to share behaviour across them.

The instinctive approach to external API failures is to wrap the call in try-catch and handle it there:

try {
    $externalApi->createUser($attributes);
} catch (Exception $e) {
    Log::error($e->getMessage());
    // Proceed anyway? Throw? Return false?
}

This is not wrong — it is incomplete. The catch block becomes the moment you are forced to decide what the system should do when the API fails, under pressure, in the middle of writing unrelated code.

That decision gets made inconsistently across call sites, often defaults to "log and continue" because it is easiest, and is invisible to anyone reading the model or service that defines the business rules.

A better approach: make the fallback behaviour explicit at the model level, not the call site.

The sync trait: making resilience decisions visible

The core idea is a trait on Eloquent models that wraps API calls and exposes the failure strategy as an overridable method.

Create the file at app/Traits/SyncsWithExternalApi.php. Every model that calls an external API will use it.

New to Laravel's HTTP client? Laravel ships with a wrapper around Guzzle called Http::. It handles timeouts, headers, retries, and response checking in a clean, readable API. See the official docs →

trait SyncsWithExternalApi
{
    /**
     * The default: fail loud. Silence requires an explicit opt-in.
     *
     * This is deliberate — the safe default is to surface failures,
     * not hide them. Models that can tolerate temporary sync failures
     * should override this method and return true.
     */
    public function shouldContinueWithoutSync(): bool
    {
        return false;
    }

    /**
     * Each model using this trait must implement createURL() and updateURL()
     * returning the external endpoint for that resource. For example:
     *
     * protected function createURL(): string
     * {
     *     return config('services.external_api.base_url') . '/users';
     * }
     */
    public static function createWithExternalApi(array $attributes): self
    {
        $url = (new static())->createURL();

        $response = Http::connectTimeout(3)  // 3s to establish the TCP connection
            ->timeout(30)                    // 30s maximum total request time
            ->withHeaders([
                'X-Requested-With' => 'XMLHttpRequest',
                'X-Forwarded-For'  => request()->ip(),
                'X-Request-ID'     => Context::get('request_id'), // see note below
            ])
            ->post($url, $attributes);

        if ($response->failed()) {
            logger()->error('External API failed on create', [
                'url'      => $url,
                'status'   => $response->status(),
                'response' => $response->json(),
            ]);

            if ((new static())->shouldContinueWithoutSync()) {
                // Explicit opt-in to fail-silent: proceed with local write only
                return static::create($attributes);
            }

            throw new Exception('External API unavailable.');
        }

        // Note: this only checks the HTTP status code, not the response body.
        // Some APIs return 200 OK with {"success": false} — add body validation
        // here based on what your specific API returns. See "What this does not solve".
        return static::create($attributes);
    }
}

Laravel version note: Context::get('request_id') requires Laravel 11 (Illuminate\Support\Facades\Context). On Laravel 9 or 10, replace with: request()->attributes->get(RequestLogger::REQUEST_ID_ATTRIBUTE, '')

Why two timeout values?

Http::connectTimeout(3)->timeout(30)

These cover two separate failure modes:

connectTimeout(3) — aborts if the TCP handshake takes more than 3 seconds. Catches unresponsive hosts before any data is sent.
timeout(30) — aborts if the total request takes more than 30 seconds. Catches a server that accepted the connection and then stalled.

Without either, a request to an unresponsive host may wait 75+ seconds for the OS to give up — blocking your worker the entire time. Setting both is cheap insurance.

On SSL verification: You may see withoutVerifying() in some codebases. This disables SSL certificate checking and is only appropriate for internal private-network services. For any public external API, leave SSL verification on. It costs nothing and catches real problems: expired certificates, man-in-the-middle attacks, DNS hijacking.

Tracing failures across systems with a request ID

Notice the X-Request-ID header on every outgoing call. This single line is worth a brief aside.

When a sync fails and you are debugging with the third-party team, "can you look up request ID a3f2c1... on your end?" takes seconds. "It was a POST to your /users endpoint, around 14:30, the payload had these fields..." takes several minutes and depends on their log retention.

When both systems log the same ID, the conversation is immediate instead of archaeological.

->withHeaders([
    'X-Request-ID' => Context::get('request_id'),
])

One header. Costs nothing in normal operation. Correlation IDs are a standard observability pattern — if you are not already using them, this is a good place to start.

`shouldContinueWithoutSync()` — a business decision in code

This method is the most important design element in the trait. It is not a technical setting — it encodes a business rule:

If this integration fails, is the primary operation still valid without it?

The name matters. ignoreException sounds like you are suppressing an error. shouldContinueWithoutSync says exactly what it answers: can this model exist locally before the external system knows about it?

Consider two models using the same trait with opposite answers:

// KYC verification — the external check IS the operation.
// If the API fails, the verification has not happened.
// Proceeding silently would mean skipping a compliance step.
class Ekyc extends Model
{
    use SyncsWithExternalApi;

    // No override — shouldContinueWithoutSync() defaults to false.
    // A failed API call is a failed operation. Full stop.
}

// Stock transfer — the external system is a secondary record-keeper.
// Your database is the source of truth.
// A temporary outage is acceptable if you retry the sync later.
class StockTransfer extends Model
{
    use SyncsWithExternalApi;

    public function shouldContinueWithoutSync(): bool
    {
        return true; // Explicit opt-in to fail-silent
    }
}

Same trait. Opposite behaviour. The difference is documented in the code — not buried in a service class comment somewhere.

Why default to false? Fail-loud surfaces problems. Fail-silent hides them. Defaulting to silence means every model that has not thought about this will eat errors quietly. Defaulting to loud means a developer has to explicitly say "yes, I have thought about this, and silent failure is acceptable here."

What a complete model looks like

The trait expects each model to implement three methods alongside the policy setting: createURL(), updateURL(), and optionally requiredAttributes(). Here is StockTransfer with all the pieces assembled:

class StockTransfer extends Model
{
    use SyncsWithExternalApi;

    // Policy: can exist locally before the external system knows.
    // Failed syncs queue a retry rather than failing the operation.
    public function shouldContinueWithoutSync(): bool
    {
        return true;
    }

    // Where to create a new transfer in the external system
    protected function createURL(): string
    {
        return config('services.core_banking.url') . '/transfers';
    }

    // Where to update an existing transfer.
    // Return an array if multiple endpoints need to be notified.
    protected function updateURL(): string|array
    {
        return config('services.core_banking.url') . '/transfers/' . $this->external_id;
    }

    // Fields required in EVERY update payload — not just what changed.
    // The external system uses these to locate the record on their end.
    protected function requiredAttributes(): array
    {
        return [
            'external_id' => $this->external_id,
            'account_ref' => $this->account->external_ref,
        ];
    }
}

The contract the trait expects: createURL() and updateURL() say where to send data. requiredAttributes() says what the external system always needs to receive alongside any change. shouldContinueWithoutSync() says what happens when the endpoint is unreachable.

Handling updates across multiple endpoints

Some models need to notify more than one external endpoint on update. The trait handles this by normalising the URL list:

public function updateDetailWithExternalApi(array $data, ?bool $shouldContinueWithoutSync = null): bool
{
    $urls = $this->updateURL();

    // Accept a single string or an array — both work the same way
    if (is_string($urls)) {
        $urls = [$urls];
    }

    foreach ($urls as $url) {
        // requiredAttributes() injects fields that must always accompany updates,
        // so call sites don't have to remember to include them
        $payload = array_merge($this->requiredAttributes(), $data);

        $response = Http::connectTimeout(3)
            ->timeout(30)
            ->withHeaders([
                'X-Requested-With' => 'XMLHttpRequest',
                'X-Forwarded-For'  => request()->ip(),
                'X-Request-ID'     => Context::get('request_id'),
            ])
            ->post($url, $payload);

        if ($response->failed() || ($response->json()['success'] ?? true) === false) {
            logger()->error('External sync failed on update', [
                'url'    => $url,
                'status' => $response->status(),
                'data'   => $data,
            ]);

            $proceed = $shouldContinueWithoutSync ?? $this->shouldContinueWithoutSync();

            if ($proceed) {
                return $this->update($data);
            }

            throw new Exception("Sync failed for {$url}: " . $response->status());
        }
    }

    return $this->update($data);
}

Why the ?bool $shouldContinueWithoutSync = null parameter? The model-level method sets the default. But callers sometimes need to override it for a specific context — a reconciliation job, for instance, might set shouldContinueWithoutSync: true on models that normally fail loud, because the job's purpose is to retry failures and hard-failing the whole batch over one record defeats that purpose. The parameter gives callers that flexibility without touching the model.

What happens to failed syncs

The trait handles the moment of failure. Recovery is a separate concern — deliberately so.

When a model creates locally because the API was down, you have data your external system does not know about. Eventually this needs to reconcile. Two complementary approaches:

Approach 1: Queued delayed retry (start here)

When a model proceeds locally because the API was down, queue a retry job immediately — but with a delay. The delay matters: if the API just went down, hitting it again in five seconds is pointless.

What is a job class? In Laravel, a job is a class that does background work. Create one with php artisan make:job SyncRecordWithExternalApi. It receives the record ID, loads the model, and calls the external API. The queue worker picks it up and runs it outside the request cycle.

Update the fail-silent branch in your trait to dispatch the retry alongside the local write:

if ((new static())->shouldContinueWithoutSync()) {
    $record = static::create($attributes);

    // Do not retry immediately — the API just failed.
    // Wait 5 minutes, then attempt the sync again.
    // SyncRecordWithExternalApi is a job class you create:
    // php artisan make:job SyncRecordWithExternalApi
    SyncRecordWithExternalApi::dispatch($record->id)
        ->onQueue('sync')
        ->delay(now()->addMinutes(5));

    return $record;
}

New to queues? Laravel's queue system defers work to a background worker process. See the official docs →. For jobs that communicate with external APIs, use a dedicated queue (.onQueue('sync')) so a third-party outage does not back up your other work.

Approach 2: Scheduled reconciliation (add after you've seen one outage)

A nightly job that checks for any records that were never synced — a safety net for anything that slipped through after retries were exhausted:

// Runs nightly via Laravel's scheduler
$unsynced = Model::whereNull('synced_at')->cursor();
foreach ($unsynced as $record) {
    SyncRecordWithExternalApi::dispatch($record->id)->onQueue('sync');
}

Add a synced_at column to any model where shouldContinueWithoutSync() returns true. Set it when the sync succeeds. That gives you an instant view of unsynced records and makes the reconciliation job trivial to write.

Start with the delayed retry. Add the scheduled reconciliation after you have seen your first real outage and understand your actual failure volume. Both together is more resilient than either alone.

Choosing neither — logging the error and moving on — means the inconsistency is permanent unless someone notices and manually resolves it. The cost of building the recovery path is small. The cost of skipping it compounds silently.

The edge case: what if the local write fails?

Show this trait to a more experienced engineer and the first question is usually:

What happens if the local create() fails after the external API already succeeded?

The API has the record. Your database does not. You have introduced inconsistency in the other direction.

The complete solution requires two things working together:

Wrap the local write in a database transaction so it can roll back cleanly on failure.
Send an idempotency key with the external API call, so a retry does not create a duplicate on their end.

What is an idempotency key? It is a unique identifier you generate before making an API call and send as a header. If the request fails and you retry with the same key, the external API recognises it as a repeat and returns the original result — without creating a duplicate record. Stripe's idempotency docs are a good reference for how this works in practice.

public static function createWithExternalApi(array $attributes): self
{
    $url = (new static())->createURL();

    // Generate the key before the call.
    // On retry, send the same key — the external API returns
    // the same result without creating a duplicate.
    $idempotencyKey = Str::uuid()->toString();

    $response = Http::connectTimeout(3)
        ->timeout(30)
        ->withHeaders([
            'X-Idempotency-Key' => $idempotencyKey,
            'X-Request-ID'      => Context::get('request_id'),
        ])->post($url, $attributes);

    if ($response->failed()) {
        // API failed before writing — safe to retry with the same key
        throw new Exception('External API unavailable.');
    }

    // API succeeded. Wrap the local write in a transaction so it can
    // roll back cleanly if something goes wrong (e.g. a validation error
    // or a database constraint). If the transaction fails, retrying the
    // whole operation with the same idempotency key is safe — the API
    // won't create a duplicate on the next attempt.
    return DB::transaction(function () use ($attributes) {
        return static::create($attributes);
    });
}

Check your API's documentation. Not all external APIs support idempotency keys — it depends on the provider. When they are available, use them. Without them, the only safe option after a partial failure is manual reconciliation, and manual steps under incident pressure go wrong.

What this does not solve

A pattern is a floor, not a ceiling. Be clear about its limits:

200 responses with error payloads. $response->failed() checks the HTTP status code. Some APIs return 200 OK with {"success": false} in the body. The update method above checks for this, but the create method does not — add body validation based on what your specific API returns.
Silent data corruption. A successful response does not guarantee the data was stored correctly. For critical operations, validate the response body against what you sent.
Partial writes on the external end. Some APIs accept a request, return success, and write only part of the data. Only end-to-end testing and periodic reconciliation catches this.
Providers that don't support idempotency keys. Nothing in this pattern solves the duplicate-create problem if the external API does not support them.

Where you end up

If you apply this consistently, one thing changes: the fallback decision is not made under pressure at 2am. It was made when the model was written, by someone who understood the business rule, and it is readable in the code by anyone who comes after them.

shouldContinueWithoutSync() on each model. Logged context on every failure. A recovery path built in, not improvised.

The 2am outage will still happen. This just means you will have a plan when it does.

Before you ship — checklist

[ ] Every Http:: call has both connectTimeout() and timeout() set explicitly
[ ] withoutVerifying() is not present on any call to a public external API
[ ] shouldContinueWithoutSync() return value is a conscious decision per model — not left as the default by accident
[ ] Models where shouldContinueWithoutSync() is true have a synced_at column and a recovery path (queued retry, scheduled reconciliation, or both)
[ ] Every failed sync logs: URL, status code, response body, and the payload sent
[ ] X-Request-ID is passed as a header on all outgoing API calls
[ ] requiredAttributes() is defined on any model that must include identifying fields in every update
[ ] Idempotency keys are used for any external API that supports them

The key insight: The fallback decision — fail loud or continue without sync — is a business rule, not a technical setting. Encoding it as a named method on the model (shouldContinueWithoutSync()) makes the decision readable in the code, consistent across every call site, and impossible to forget to make.

Previous: Part 3 — Secure File Uploads

What this series built

Part 1 turned "we don't know what changed" into a traceable system: field-level diffs, append-only logs, request IDs that correlate across every log channel, and permission failures visible before they become incidents.

Part 2 moved from "dispatch and hope" to intentional queue design: topology that separates work by characteristics, job constructors that carry IDs not snapshots, retry strategies matched to actual failure modes.

Part 3 replaced a single file-type check with seven independent ones — each named, each closing a specific attack vector.

Part 4 made "what happens when their API goes down?" answerable before it becomes an incident.

The common thread: decisions that are usually made implicitly — or not at all until something breaks — made explicit in code, with the reasoning attached.

Secure File Uploads: Seven Checks and Why Each One Exists

Shakil Alam — Fri, 01 May 2026 13:26:57 +0000

Part 3 of 4 — Laravel Architecture Patterns for Production
~9 min read · Security · Middleware · File handling

A file upload is the moment you hand control to an untrusted user.

Everything else in your application — form inputs, query parameters, JSON — is text. You validate it, sanitize it, store it in a database. A file upload is arbitrary binary data from a source you cannot verify, about to be written to your filesystem. The surface area is different. The failure modes are different. The consequences are different.

Most tutorials cover the happy path: accept the file, store it, return a URL. The problem is never the happy path.

Rename a PHP file to image.jpg. Upload it. Many Laravel applications accept it — because getClientOriginalExtension() returns jpg and getClientMimeType() returns image/jpeg. Both values the client provided. Neither verified by the server.

This is how webshells get uploaded. This is how stored XSS gets planted in SVG files. This is the gap.

The fix is seven independent checks, each closing a specific attack vector. The reason for seven — not one — is that no single check catches everything. A determined attacker probes each layer individually. Defense in depth means removing the easy paths at each layer.

What you will build

A middleware that validates seven independent properties of every uploaded file, each one named and explained
Server-side MIME detection using finfo — not the browser's claim
A unique name strategy that removes user-controlled strings from your filesystem paths entirely
A storage pattern where no uploaded file is ever directly reachable via HTTP

The validation pipeline

Upload arrives
       │
       ▼
  1. Filename sanitization
     blocks: path traversal · double extensions · null bytes · hidden files
       │
       ▼
  2. Extension allowlist
     blocks: file types with no legitimate use case
       │
       ▼
  3. Client MIME allowlist
     blocks: mismatched browser-reported content type
       │
       ▼
  4. Server MIME detection (finfo reads actual bytes)
     blocks: renamed files · spoofed extensions
       │
       ▼
  5. Extension ↔ MIME cross-check
     blocks: shell.php.jpg · mismatched pairs
       │
       ▼
  6. File size limit
     blocks: denial-of-service via oversized uploads
       │
       ▼
  7. Magic bytes check
     blocks: crafted files · polyglot attacks
       │
       ▼
  Stored as unique name in storage/ — never in public/

The middleware

The validation runs as middleware applied to upload routes. All validation aborts with 400 and a user-readable message:

class SecureFileUpload
{
    // Only what your application genuinely needs — keep this narrow
    protected array $allowedExtensions = ['jpg', 'jpeg', 'png', 'pdf', 'docx', 'xlsx', 'csv'];

    protected array $allowedMimeTypes = [
        'image/jpeg', 'image/png', 'application/pdf',
        'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
        'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
        'text/csv', 'text/plain', 'application/vnd.ms-excel',
    ];

    // Maps each allowed extension to its permitted server-detected MIME types
    protected array $extensionMimeMap = [
        'jpg'  => ['image/jpeg'],
        'jpeg' => ['image/jpeg'],
        'png'  => ['image/png'],
        'pdf'  => ['application/pdf'],
        'docx' => ['application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
        'xlsx' => ['application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
        'csv'  => ['text/csv', 'text/plain', 'application/vnd.ms-excel'],
    ];

    protected int $maxFileSizeKb;

    public function __construct()
    {
        $this->maxFileSizeKb = (int) config('files.upload_max_kb', 5120); // Default 5MB
    }

    public function handle(Request $request, Closure $next)
    {
        foreach ($request->allFiles() as $file) {
            $this->walkFiles($file);
        }
        return $next($request);
    }

    protected function walkFiles($file): void
    {
        if (is_array($file)) {
            foreach ($file as $f) {
                $this->walkFiles($f);
            }
            return;
        }
        if ($file instanceof UploadedFile) {
            $this->validateFile($file);
        }
    }

    // Orchestrates all seven checks in order
    protected function validateFile(UploadedFile $file): void
    {
        $rawName    = $file->getClientOriginalName();
        $extension  = strtolower($file->getClientOriginalExtension());
        $clientMime = $file->getClientMimeType();

        // Check 1 — filename sanitization
        $this->sanitizeRawName($rawName);

        // Check 2 — extension allowlist
        if (!in_array($extension, $this->allowedExtensions, true)) {
            abort(400, "Files with .$extension extension are not supported.");
        }

        // Check 3 — client MIME allowlist
        if (!in_array($clientMime, $this->allowedMimeTypes, true)) {
            abort(400, 'Unrecognized file type. Ensure the file is not corrupted.');
        }

        // Check 4 — server-side MIME detection
        $serverMime = $this->detectServerMime($file);

        // Check 5 — extension ↔ MIME cross-check
        if (!$this->isMimeAllowedForExtension($extension, $serverMime)) {
            abort(400, "Extension '.$extension' does not match the file's content. "
                      . "Please ensure you have not renamed a file to a different extension.");
        }

        // Check 6 — size limit
        $sizeKb = (int) ceil($file->getSize() / 1024);
        if ($sizeKb > $this->maxFileSizeKb) {
            $maxMb  = round($this->maxFileSizeKb / 1024, 1);
            $fileMb = round($sizeKb / 1024, 1);
            abort(400, "File too large. Maximum is {$maxMb}MB. Your file is {$fileMb}MB.");
        }

        // Check 7 — magic bytes
        $this->lightweightMagicChecks($file, $extension);
    }

    protected function isMimeAllowedForExtension(string $extension, string $serverMime): bool
    {
        $allowed = $this->extensionMimeMap[$extension] ?? [];
        return in_array($serverMime, $allowed, true);
    }
}

The error messages matter. "Invalid file type" forces a support ticket. "Only one dot is allowed in the filename (e.g. document.pdf)" tells the user exactly what is wrong. When legitimate users trigger these checks by accident — and they will — specificity is the difference between a solvable problem and frustrated churn.

Check 1 — Filename sanitization

Before any content check, validate the name itself. Filenames are a distinct attack surface:

protected function sanitizeRawName(string $name): string
{
    if (mb_strlen($name, 'UTF-8') > 100) {
        abort(400, 'Filename too long. Please use 100 characters or fewer.');
    }

    // Path traversal: ../../etc/passwd
    if (preg_match('#[\\\\/]|^\.+$#', $name)) {
        abort(400, 'Filename cannot contain path separators.');
    }

    // Null bytes and control characters
    if (preg_match('/[\x00-\x1F\x7F]/', $name)) {
        abort(400, 'Filename contains invalid characters. Please rename the file.');
    }

    // Double-dot path traversal
    if (str_contains($name, '..')) {
        abort(400, "Filename cannot contain '..'.");
    }

    // Double-extension attack: shell.php.jpg
    // The browser sees .jpg, the server may execute .php
    if (substr_count($name, '.') > 1) {
        abort(400, "Only one dot allowed in the filename (e.g. 'document.pdf').");
    }

    // Hidden files: .htaccess, .env
    if (str_starts_with($name, '.')) {
        abort(400, 'Filenames cannot start with a dot.');
    }

    // Strict allowlist: letters, numbers, underscores, dashes, one dot, spaces
    if (!preg_match('/^[a-zA-Z0-9_\-\. ]+$/', $name)) {
        abort(400, 'Filename contains unsupported characters. Use letters, numbers, dashes, and underscores.');
    }

    return $name;
}

The double-extension rule is the highest-value check here. shell.php.jpg gets past a simple extension check because the last extension is .jpg. One dot, full stop.

Checks 2 and 3 — Extension and client MIME allowlisting

Both are necessary, even though neither is sufficient alone:

if (!in_array($extension, $this->allowedExtensions, true)) {
    abort(400, "Files with .$extension extension are not supported.");
}

if (!in_array($clientMime, $this->allowedMimeTypes, true)) {
    abort(400, 'Unrecognized file type. Ensure the file is not corrupted.');
}

Why both? An attacker who crafts a file with an allowed extension might supply an unexpected MIME type. An attacker who spoofs the MIME type might use a disallowed extension. Checking both raises the bar.

Why keep the allowlist narrow? Every extension you permit is an attack surface you are accepting. If your application does not need .svg uploads, remove it. If it does not need .zip, remove it. The default should be minimal; expansion should require a specific business case.

Check 4 — Server-side MIME detection

This is the check that actually matters. The previous two trusted the client. This one reads the file:

protected function detectServerMime(UploadedFile $file): string
{
    // finfo reads the file's actual bytes from the filesystem.
    // It does not care what the browser claimed.
    // A PHP file renamed to .jpg will be identified as text/x-php, not image/jpeg.
    $finfo = new \finfo(FILEINFO_MIME_TYPE);
    $mime  = $finfo->file($file->getRealPath());

    // Edge case: finfo correctly identifies CSV as text/plain (it is plain text).
    // But text/plain is not in the CSV slot on the allowlist.
    // The extension provides the context needed to resolve this.
    if ($mime === 'text/plain'
        && strtolower($file->getClientOriginalExtension()) === 'csv') {
        return 'text/csv';
    }

    return (string) $mime;
}

Why does the CSV edge case matter? A naive implementation would either reject all CSVs (wrong MIME type) or add text/plain to the global allowlist (which permits uploading arbitrary text files, including PHP in some environments). The explicit edge case handles the ambiguity without either problem.

Check 5 — Cross-checking extension against detected MIME

The check that closes the most common attack vector. The extensionMimeMap defined on the class is what makes this work — each allowed extension maps to the MIME types finfo legitimately returns for that format:

// CSV legitimately maps to multiple MIME types because different tools
// and operating systems report it differently. The map accommodates
// known variation without widening the gap for other formats.
'csv' => ['text/csv', 'text/plain', 'application/vnd.ms-excel'],

A file with extension .jpg whose finfo-detected MIME is text/x-php fails this check. The extension says one thing; the bytes say another. That inconsistency is the signal.

Check 6 — Size limits

The size check in validateFile() above reads the limit from config:

$this->maxFileSizeKb = (int) config('files.upload_max_kb', 5120);

Store the limit in config('files.upload_max_kb') rather than hardcoding it. This lets you adjust per environment — tighter on free tier plans, looser for premium users — without touching the middleware. The error message surfaces both the maximum and the actual file size so the user knows exactly what to change.

Check 7 — Magic bytes

The final layer reads the file's opening bytes directly:

protected function lightweightMagicChecks(UploadedFile $file, string $ext): void
{
    $fp   = @fopen($file->getRealPath(), 'rb');
    $head = @fread($fp, 8) ?: '';
    @fclose($fp);

    // Every valid PDF begins with %PDF-
    if ($ext === 'pdf' && !str_starts_with($this->bytesToAscii($head), '%PDF-')) {
        abort(400, 'This PDF appears to be corrupted or invalid.');
    }

    // PNG has a fixed 8-byte signature defined in the spec
    if ($ext === 'png' && $head !== "\x89PNG\r\n\x1a\n") {
        abort(400, 'This PNG appears to be corrupted or invalid.');
    }

    // JPEG starts with FF D8 FF
    if (in_array($ext, ['jpg', 'jpeg'], true)) {
        if (!str_starts_with($head, "\xFF\xD8\xFF")) {
            abort(400, 'This JPEG appears to be corrupted or invalid.');
        }
    }

    // DOCX, XLSX, PPTX are ZIP archives with a PK header
    if (in_array($ext, ['docx', 'xlsx', 'pptx', 'zip'], true)) {
        if (!preg_match('/^PK(\x03\x04|\x05\x06|\x07\x08)/', $head)) {
            abort(400, 'This Office document appears corrupted or invalid.');
        }
    }
}

protected function bytesToAscii(string $bytes): string
{
    // Strip non-printable characters for string comparison (e.g. "%PDF-")
    return preg_replace('/[^\x20-\x7E]/', '', $bytes) ?? '';
}

Why 8 bytes? Magic byte signatures are typically 2–8 bytes. Reading the first 8 captures all common signatures without reading a meaningful chunk of the file.

A note on coverage: this check covers the formats most commonly exploited — PDF, PNG, JPEG, and Office documents. It is a structural sanity check, not a full file parser. Its job is to catch files where the opening bytes contradict the claimed format. It does not replace the MIME detection and cross-check above — all seven checks work together.

SVG: the format that deserves extra attention

SVG files are XML. XML can contain <script> tags. A valid, well-formed SVG with embedded JavaScript is a stored XSS vector — if you accept it from one user and serve it inline to another, you have created a script injection path. The OWASP File Upload Cheat Sheet covers this and other format-specific risks in depth.

Three options:

Sanitize on upload — strip script tags and event handlers before storing. Complex to do correctly and easy to get wrong.
Force download — serve SVGs with Content-Disposition: attachment, preventing inline browser rendering and therefore script execution.
Remove SVGs from the allowlist — the safest option if there is no specific business requirement.

If you do not have a defined reason to accept user-uploaded SVGs, option 3 takes one line and eliminates the risk entirely.

Always generate a unique name before saving

Regardless of the validation outcome, the filename used for storage should never be the one the user provided:

public static function uniqueName($file, $postfix = ''): string
{
    if ($file instanceof UploadedFile) {
        $file = $file->getClientOriginalName();
    }

    $extension = self::getExtension($file);

    $nameWithoutExtension = Str::of($file)
        ->replaceLast(".$extension", '')
        ->replace(' ', '_');

    if ($nameWithoutExtension->length() > 100) {
        $nameWithoutExtension = $nameWithoutExtension->substr(0, 100);
    }

    $nameWithoutExtension = $nameWithoutExtension . $postfix;

    if (!method_exists(Str::class, 'transliterate')) {
        $nameWithoutExtension = preg_replace('/[^\x20-\x7E]/', '_', $nameWithoutExtension);
        return $nameWithoutExtension . '_' . uniqid() . '.' . $extension;
    }

    return Str::transliterate($nameWithoutExtension) . '_' . uniqid() . '.' . $extension;
}

uniqid() is microsecond-based and not cryptographically random. It is sufficient here because it combines with the sanitized filename prefix — two simultaneous uploads of report.pdf produce report_6601a1f3b8e42.pdf and report_6601a1f3b8e43.pdf, with no collision. If your application requires stronger uniqueness guarantees — for example, if filenames are ever used as access tokens — substitute Str::uuid(). That is a one-line change and the stronger default.

uniqueName() depends on two helper methods. Here are simple implementations to drop into the same File class:

public static function getExtension(string|UploadedFile $file): string
{
    if ($file instanceof UploadedFile) {
        return strtolower($file->getClientOriginalExtension());
    }

    return strtolower(pathinfo($file, PATHINFO_EXTENSION));
}

public static function getHash(UploadedFile $file): string
{
    // SHA-256 of the file contents — useful for detecting duplicate uploads
    // and verifying file integrity when serving back to users
    return hash_file('sha256', $file->getRealPath());
}

And in the media trait:

public function addMediaAs(
    UploadedFile $file,
    string $collection = 'default',
    string $name = null
): Media {
    $uniqueName = $name ?? File::uniqueName($file);

    return $this->medias()->create([
        'name'       => $file->getClientOriginalName(), // Original name for display
        'file_name'  => $uniqueName,                    // Unique name for storage
        'mime_type'  => $file->getMimeType(),
        'path'       => $file->storeAs(
                            $this->getMediaPath($collection),
                            $uniqueName,
                            $this->getMediaDisk($collection)
                        ),
        'disk'       => $this->getMediaDisk($collection),
        'file_hash'  => File::getHash($file),
        'collection' => $collection,
        'size'       => $file->getSize(),
    ]);
}

Why keep the original name in name but use the unique name for path? The display name — shown to the user in the UI — should be what they uploaded. The storage path should have no connection to any user-provided string. The two concerns are separate.

Where files live after validation

Store outside the web root — in storage/ — and serve through a controller that enforces authorization:

public function stream(Media $media): StreamedResponse
{
    // Authorization on every file access — no direct URL bypasses this
    $this->authorize('view', $media);

    return Storage::disk($media->disk)->response(
        $media->path,
        $media->name,
        ['Content-Type' => $media->mime_type]
    );
}

Why never public/? A file in public/ is directly reachable via HTTP — no authorization, no application code in the path. If a file with a server-executable extension reaches public/ because validation has layers that can be circumvented, it can be executed by guessing its URL. Files in storage/ have no direct URL. Everything goes through the controller.

Registering the middleware

Apply SecureFileUpload to upload routes only — never globally, since running all seven checks on every request that has no file would add overhead for no reason.

// Laravel 11 — routes/web.php or routes/api.php
Route::post('/upload', [MediaController::class, 'store'])
    ->middleware(\App\Http\Middleware\SecureFileUpload::class);

// Or as a group if you have multiple upload endpoints
Route::middleware(\App\Http\Middleware\SecureFileUpload::class)->group(function () {
    Route::post('/media/upload', [MediaController::class, 'store']);
    Route::post('/documents/upload', [DocumentController::class, 'store']);
});

// Laravel 10 and earlier — same route syntax works, or alias it
// in app/Http/Kernel.php under $routeMiddleware:
// 'secure.upload' => \App\Http\Middleware\SecureFileUpload::class,
// Then use ->middleware('secure.upload') in your routes

The key insight from this article: No single file validation check catches everything. getClientMimeType() trusts the browser. getClientOriginalExtension() trusts the browser. Only finfo reads the actual bytes. Seven independent checks layered together — each blocking a different attack path — is what makes upload validation meaningfully secure rather than just present.

Before you ship — checklist

[ ] SecureFileUpload middleware is applied to upload routes only — not globally
[ ] allowedExtensions and allowedMimeTypes are minimal — only what the application genuinely needs
[ ] finfo server-side MIME detection is running (not just trusting getClientMimeType())
[ ] extensionMimeMap covers every extension in allowedExtensions
[ ] Magic bytes check covers JPEG in addition to PDF, PNG, and Office formats
[ ] SVG is either removed from the allowlist or served with Content-Disposition: attachment
[ ] File::uniqueName() is called before every storeAs() — original filename never used as storage path
[ ] Files are stored in storage/ — nothing uploaded goes into public/
[ ] File access goes through a controller that calls $this->authorize()

Previous: Part 2 — Queue Architecture

Laravel Queue Architecture: Designing Background Work That Holds Up

Shakil Alam — Fri, 24 Apr 2026 17:21:11 +0000

Part 2 of 4 — Laravel Architecture Patterns for Production
~9 min read · Queue design · Job architecture · Background processing

Background jobs are one of those features that feel solved the moment they work. You dispatch, it runs in the background, life is good. The framework handles it.

The illusion holds until scale arrives. Then a password reset email sits behind a 90-second video compression job. A job that hits a flaky external API fails, retries, fails, retries — consuming worker processes while real work waits. A bulk operation dispatches 5,000 jobs at once and the queue system staggers under the spike. A crash halfway through a file operation leaves corrupted data you do not notice for three days.

None of these are framework failures. They are design failures — decisions that were not made explicitly, so they defaulted to the wrong thing.

This article is about the decisions, and the reasoning behind them.

What you will learn

Why passing an Eloquent model to a job constructor is wrong — and what to pass instead
How to design a queue topology before you are forced to by a problem
What retry strategy to use for transient, rate-limited, and permanent failures
How to write file operations that leave no corrupted state when a job crashes mid-write

The mental model: a queue is not a to-do list

Most queue problems come from treating a queue as a simple list — things go in, things come out, in order. That model works fine for small volumes. It breaks under pressure.

The more accurate mental model: a queue is a work contract between the part of your system that knows something needs to happen and the part that will do it — separated by time, by process restarts, and by failures. The job payload is a self-contained instruction. It cannot assume anything about the context that created it still exists.

That one shift — from "list of tasks" to "self-contained work contract" — makes the rest of this article's decisions feel obvious rather than arbitrary.

What to put in a job constructor — and what not to

The most frequent queue mistake is passing an Eloquent model to a job constructor:

// This seems fine. It is not.
CompressVideo::dispatch($media);

When a job is dispatched, its constructor arguments are serialized into the queue payload. Laravel's SerializesModels trait handles this by storing the model's class and primary key — and re-fetching the model when the job runs. That sounds correct, but consider: the job might run 30 seconds later. Or three hours later if the queue is backed up. The record may have been updated, soft-deleted, or had its status changed in the time between dispatch and execution.

If the job carries a serialized model, it works with the snapshot from dispatch time. If the job carries an ID, it fetches current data at execution time.

class CompressMediaVideo implements ShouldQueue
{
    public function __construct(private readonly int $mediaId) {}

    public function handle(VideoCompressorService $compressor): void
    {
        // Fetch fresh at execution time, not stale from dispatch time
        $media = Media::findOrFail($this->mediaId);

        if (!str_starts_with($media->mime_type, 'video/')) {
            return; // State may have changed since dispatch — handle gracefully
        }

        $compressor->compress($media);
    }
}

Pass IDs, not models. The job's responsibility is to do a unit of work starting from first principles — not to continue a conversation that started somewhere else.

The single responsibility principle, applied to jobs

A job class should do one thing. This sounds obvious. It is regularly violated.

The problem with jobs that do multiple things: when one part fails, the whole job fails. If a job compresses a video, updates the database, sends a notification, and syncs to an external system, and the external sync times out — the compression was done, but the job retries and runs compression again. The retry was meant to retry the sync. You have wasted CPU, potentially introduced a duplicate notification, and made the job's retry behaviour unpredictable.

The cleaner design — one job per responsibility, chained. Note that the constructor is still required on each class:

class CompressMediaVideo implements ShouldQueue
{
    public function __construct(private readonly int $mediaId) {}

    public function handle(VideoCompressorService $compressor): void
    {
        $media = Media::findOrFail($this->mediaId);
        $compressor->compress($media);

        // Compression done — dispatch the next unit of work independently
        UpdateMediaMetadata::dispatch($this->mediaId)->onQueue('default');
    }
}

Each job is independently retryable. A failure in metadata update does not re-run compression. You can add monitoring per job type and scale workers for specific job types independently.

Queue topology: the decision nobody makes until they have to

A single default queue works until it does not. The moment you have both time-sensitive operations (password resets, OTPs) and long-running operations (report generation, bulk compression) on the same queue, you have a priority problem the queue itself cannot solve.

The topology decision — which queues exist and what runs on each — should be made before the first job is deployed, not when a user complains their OTP never arrived because it was stuck behind a batch export.

A practical topology:

Queue	Purpose	Acceptable delay
`critical`	Password resets, OTPs, security alerts	None — delay means users cannot access the system
`default`	Notifications, status updates, lightweight tasks	A few seconds
`media`	Video compression, image processing	Minutes — slow and CPU-intensive
`sync`	External API sync jobs	Variable — isolate third-party failures
`reports`	Bulk exports, large queries	Can take minutes — must never starve other queues

Workers listen to queues in priority order:

# Critical has its own dedicated worker — nothing else competes
php artisan queue:work redis --queue=critical --timeout=30

# This worker handles default first, then media if default is empty
php artisan queue:work redis --queue=default,media --timeout=120

# Sync worker — isolated so third-party failures never affect your own queues
php artisan queue:work redis --queue=sync --timeout=60

# Reports isolated — slow timeouts do not affect other workers
php artisan queue:work redis --queue=reports --timeout=600

Why isolate sync? External API reliability is outside your control. If a third-party goes down and you are retrying aggressively, those retry jobs accumulate in the queue. On a shared queue, they compete for worker processes with your own jobs. An isolated sync queue means a third-party outage only affects sync workers — your application's own background work continues unaffected.

If you are on Redis and can run a dashboard, Laravel Horizon gives you queue depth, throughput, and failed job monitoring out of the box. If you are on a database driver or a locked environment, a php artisan queue:failed count in a scheduled log check covers the essentials.

Retry strategy: not all failures are equal

The default retry behaviour — try N times, then give up — is right for some jobs and wrong for others. Thinking about failure modes before writing the job saves you from the wrong defaults.

Transient failures

Database hiccups, brief network timeouts — things that will probably succeed on retry:

public int $tries  = 3;
public int $backoff = 5; // Wait 5 seconds between retries

Rate-limited or service-down failures

External API unavailable, rate limit hit — back off with increasing delays:

public int $tries = 5;

public function backoff(): array
{
    // 30s, 60s, 120s, 240s, 480s between retries
    return [30, 60, 120, 240, 480];
}

public function retryUntil(): \DateTime
{
    // Regardless of tries, give up after 24 hours
    // Prevents zombie jobs accumulating during prolonged outages
    return now()->addHours(24);
}

Permanent failures

Malformed input, a record that will never exist — do not retry at all:

public int $tries = 1;

public function failed(\Throwable $e): void
{
    // Alert immediately — this needs human attention, not retry
    logger()->critical('Permanent job failure', [
        'job'   => static::class,
        'error' => $e->getMessage(),
    ]);
}

Why timeout and tries are different things, and why it matters: A job that hits $timeout is killed and returns to the queue — it counts as a retry. A job that exhausts $tries goes to failed_jobs. If you set timeout = 120 and tries = 3 on a job that consistently takes 130 seconds, it will time out three times and land in failed_jobs — never completing, consuming three worker-slots in the process.

Common mistake: Setting $timeout lower than the job's typical execution time. Every time the job runs, it gets killed before finishing, counts as a retry, and eventually exhausts $tries without ever succeeding. If a job needs 90 seconds, give it at least 120. The timeout is a safety net, not a target.

Processing large backlogs: the Artisan command pattern

When you need to dispatch jobs for thousands of existing records — a backlog compression, a data migration, a bulk recalculation — the dispatch mechanism is as important as the job itself.

The pattern: an Artisan command that chunks through the database and dispatches jobs incrementally, with a --dry-run option before you commit to anything:

class ProcessBacklogCommand extends Command
{
    protected $signature = 'media:compress-videos
        {--id=      : Process a single record by ID}
        {--dry-run  : Show what would run without dispatching anything}
        {--chunk=200: Records per batch}';

    public function handle(): void
    {
        // If --id is provided, scope the query to that single record
        $query = Media::query()
            ->where('mime_type', 'like', 'video/%')
            ->whereNull('compressed_at')
            ->when($this->option('id'), fn ($q) => $q->where('id', $this->option('id')));

        $total = $query->count();
        $this->info("Found {$total} records to process.");

        if ($this->option('dry-run')) {
            $this->info('Dry run complete — no jobs dispatched.');
            return;
        }

        $dispatched = 0;
        $query->chunkById((int) $this->option('chunk'), function ($batch) use (&$dispatched) {
            foreach ($batch as $record) {
                CompressMediaVideo::dispatch($record->id)->onQueue('media');
                $dispatched++;
            }
            $this->info("Dispatched {$dispatched} jobs so far...");
        });

        $this->info("Done. Total dispatched: {$dispatched}");
    }
}

Why chunkById instead of chunk? Laravel's chunk() uses SQL OFFSET — which means the database must count and skip N rows before returning the next batch. On a table with a million rows, the 500th batch requires skipping 100,000 rows. It gets progressively slower. chunkById uses WHERE id > $lastSeen LIMIT $chunk — a keyset cursor. The query time is constant regardless of position. For large tables, this is the difference between a command that completes in minutes and one that times out.

Why --dry-run as a first-class option? Because the first time you run a bulk dispatch against production data, you want to see what would happen before it happens. --dry-run costs nothing to add and saves numerous "I did not realise it would dispatch 40,000 jobs" moments.

Atomic file operations: designing for crashes

Any job that writes a file must assume it will crash mid-write. At scale, it happens. The question is what state the system is in when it does.

Write directly to the target path: a crash leaves a partial, corrupted file where the original was. The damage is permanent until manual intervention.

Write to a temporary file, then rename:

$inputPath = $media->full_path;
$tempPath  = $inputPath . '.tmp.' . uniqid();

// All writes go here — a crash here leaves the original untouched
$this->runFFmpeg($inputPath, $tempPath);

// Only replace if the output is actually better
if (filesize($tempPath) >= filesize($inputPath)) {
    @unlink($tempPath);
    return; // Original was already optimal — do not replace it
}

// rename() is atomic on POSIX filesystems — this either completes
// or does not happen. There is no in-between state.
rename($tempPath, $inputPath);

Why compare sizes before replacing? Re-encoding an already-compressed file can produce a larger output — the encoding overhead outweighs the savings. Always verify the output is an improvement before discarding the original.

Why is rename() atomic? On Linux and macOS, rename() is a single filesystem syscall. The kernel guarantees it either moves the file or does not — there is no half-way state where the destination file is partially written. The old file remains intact until the new one is fully in place.

The shape of a well-designed job

Bringing it together:

class CompressMediaVideo implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries   = 3;
    public int $timeout = 120;
    public int $backoff = 60;

    // Takes an ID, not a model
    public function __construct(private readonly int $mediaId) {}

    public function handle(VideoCompressorService $compressor): void
    {
        // Fetches fresh at execution time
        $media = Media::findOrFail($this->mediaId);

        // Guards for state changes since dispatch
        if (!str_starts_with($media->mime_type, 'video/')) {
            return;
        }

        $compressor->compress($media);
    }

    // Failure handling is not an afterthought
    public function failed(\Throwable $exception): void
    {
        logger()->error('Video compression failed after all retries', [
            'media_id' => $this->mediaId,
            'error'    => $exception->getMessage(),
        ]);
    }
}

This job takes an ID not a model, fetches fresh data at execution time, guards against state changes since dispatch, has a meaningful failed() handler, and has timeout, retry, and backoff values that reflect actual job characteristics — not framework defaults.

The key insight from this article: Queue failures are almost never framework failures — they are design failures. Passing IDs not models, setting explicit timeout and retry values, and separating work by queue type are decisions that should be made before the first job is deployed, not after the first incident.

Before you ship — checklist

[ ] Queue topology is defined — not everything on default
[ ] Every job constructor takes an ID, not an Eloquent model
[ ] Every job has $tries, $timeout, and $backoff explicitly set — not left to framework defaults
[ ] Every job has a failed() method that logs meaningful context
[ ] $timeout is comfortably higher than the job's typical execution time
[ ] Bulk dispatch commands use chunkById, not chunk
[ ] Bulk commands have a --dry-run option
[ ] Any job that writes a file writes to .tmp first, then rename() — never directly to the target path

Previous: Part 1 — The Audit Trail

The Audit Trail: Building a System That Remembers

Shakil Alam — Fri, 17 Apr 2026 16:33:26 +0000

Part 1 of 4 — Laravel Architecture Patterns for Production
~10 min read · Compliance · Model logging · Request tracing

A transaction record had been modified.

The amount was different from what the user had submitted. Support escalated it. The user denied changing anything. The developer who last touched the code was on leave. We looked at the database — the record had an updated_at from two days ago and a different value than expected. That was everything we had.

No who. No which fields. No context about what request caused it.

We had a working application. We did not have a system that remembered anything.

That was the incident that made us build this.

What you will build

A request ID generated in middleware that automatically appears in every log line for that request — no manual threading required
Field-level model diffs that capture what changed from and to, not just that a record was updated
Append-only log files segmented to stay fast at millions of records
A Gate hook that logs failed permission checks before they become incidents

What an audit trail actually needs to prove

Before writing code, it is worth being precise about what you are building — because "audit trail" means different things in different contexts, and the requirements determine the architecture.

If you need a queryable, database-backed audit log with a ready-made API, spatie/laravel-activitylog is the standard choice and it is well built. What follows is for when your requirements go further — append-only guarantees, field-level diffs, and audit records that are genuinely hard to tamper with.

In a compliance-heavy environment — fintech, healthcare, any regulated domain — an audit trail needs to answer four questions about any data change:

Who made the change (user ID, IP address, user agent)
What changed — not "the record was updated," but which fields, from what value to what
When it changed
Why it is trustworthy — the audit record itself cannot be quietly modified

Most implementations get the first three. The fourth is where they fail, and it is the one that matters most in an actual audit.

Here is the problem with a database audit table: your application code writes to it. That means your application code can also UPDATE it. A table that application code can modify is not an immutable record — it is a mutable history. An auditor who understands this will ask how you prevent tampering, and "we trust our own code" is not a satisfying answer.

This shapes the decision to use file-based logging. But first, there is a more foundational problem: correlation.

The request ID: one thread through every log

A model change does not happen in isolation. It happens during a request — a specific HTTP call from a specific user at a specific moment. Without connecting the model change to that request, you have timestamped facts with no story between them.

The solution is a request ID: a UUID generated at the start of every request and written into every log line that request produces.

Before building the middleware class, add the request and query channels to config/logging.php:

// config/logging.php
'channels' => [

    // ... your existing channels ...

    'request' => [
        'driver' => 'daily',
        'path'   => storage_path('logs/request.log'),
        'level'  => 'debug',
        'days'   => 90,        // Retain 90 days — adjust to your compliance requirement
    ],

    'query' => [
        'driver' => 'daily',
        'path'   => storage_path('logs/query.log'),
        'level'  => 'debug',
        'days'   => 30,
    ],

],

Then the middleware:

class RequestLogger
{
    public const HEADER_NAME          = 'X-Request-Id';
    public const REQUEST_ID_ATTRIBUTE = 'request_id';

    public function handle(Request $request, Closure $next): Response
    {
        $requestId = (string) Str::uuid();

        // Store in request attributes for internal access within the same request
        $request->attributes->set(self::REQUEST_ID_ATTRIBUTE, $requestId);
        // Also set as a header — downstream systems and the browser can read it
        $request->headers->set(self::HEADER_NAME, $requestId);

        // shareContext injects request_id into every Log:: call
        // for the rest of this request automatically — no manual threading required
        Log::shareContext(['request_id' => $requestId]);

        $startedAt = hrtime(true); // Monotonic clock — more accurate than microtime()
        $response  = $next($request);
        $response->headers->set(self::HEADER_NAME, $requestId);

        $this->logRequest($request, $response, $requestId, $startedAt);

        return $response;
    }

    private function logRequest(
        Request $request,
        Response $response,
        string $requestId,
        int $startedAt
    ): void {
        Log::channel('request')->info('request.completed', [
            'request_id'  => $requestId,
            'method'      => $request->method(),
            'path'        => $request->getPathInfo(),
            'status'      => $response->getStatusCode(),
            'duration_ms' => round((hrtime(true) - $startedAt) / 1_000_000, 2),
            'user_id'     => $request->user()?->getAuthIdentifier(),
            'ip'          => $request->ip(),
        ]);
    }
}

// Laravel 11 — bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\App\Http\Middleware\RequestLogger::class);
})

// Laravel 10 and earlier — app/Http/Kernel.php
protected $middleware = [
    // ...
    \App\Http\Middleware\RequestLogger::class,
];

Every log entry your application writes from this point on will now include the request ID automatically. Here is what a request log entry looks like in storage/logs/request.log:

{
  "message": "request.completed",
  "request_id": "9d4e2f1a-83bc-4a7c-b291-7e5f3d9a1c84",
  "method": "PATCH",
  "path": "/transactions/1101",
  "status": 200,
  "duration_ms": 43.2,
  "user_id": 42,
  "ip": "192.168.1.10",
  "level": "info",
  "level_name": "INFO"
}

And a model change log entry in storage/logs/activities/transactions/1100/transaction_1101.log:

{
  "event": "updated",
  "request_id": "9d4e2f1a-83bc-4a7c-b291-7e5f3d9a1c84",
  "time": "2024-03-15 14:32:07",
  "model_id": 1101,
  "changes": {
    "amount": { "old": "5000.00", "new": "500.00" }
  },
  "user_id": 42,
  "ip": "192.168.1.10",
  "user_agent": "Mozilla/5.0 ..."
}

The same request_id appears in both files. That is the correlation. When a support ticket says "something changed on Transaction 1101," you grep that ID across both logs and have the complete picture immediately.

Why Log::shareContext() instead of passing the ID manually everywhere? shareContext() injects the given data into every Log:: call for the rest of the request lifecycle automatically. You do not thread the request ID through your services, model observers, or Gate hooks. Whatever you log, the request ID is already there.

Why UUID instead of a random integer? A six-digit random int has a real collision probability under concurrent load. A UUID is 128 bits of randomness — collision is not a realistic concern. The ID also goes into the response header (X-Request-Id), so a user who raises a support ticket can include it and you find the exact request in seconds.

Why a single structured entry after the response rather than separate request-in and response-out entries? One entry per request gives you the complete picture — method, path, status code, duration — in one line without cross-referencing. The hrtime(true) monotonic clock is more accurate for duration measurement than microtime() because it is not affected by system clock adjustments.

A note on X-Forwarded-For: When your application sits behind a load balancer, request()->ip() returns the proxy's IP, not the user's. The TrustProxies middleware resolves this — once configured, request()->ip() returns the real client IP. Pass it to external API calls so downstream system logs also record the real user, not your server's address.

Slow queries: while you are here, add this

This is a separate concern from the audit trail — but since you are already setting up logging infrastructure, it costs almost nothing to add and consistently pays off the first time a performance problem hits production.

The idea: log slow queries with severity levels matched to how serious the slowness actually is.

// AppServiceProvider.php
// Scope this to non-production environments or behind a config flag
// in high-traffic systems — DB::listen fires on every query.
if (config('app.debug') || config('logging.query_listener')) {
    DB::listen(function ($query) {
        $time = $query->time;

        match(true) {
            $time > 10000 => Log::channel('query')->critical("Extremely slow ({$time}ms)"),
            $time > 1000  => Log::channel('query')->error("Very slow ({$time}ms)"),
            $time > 100   => Log::channel('query')->warning("Slow ({$time}ms)"),
            default       => null, // Fast queries add noise without value
        };
    });
}

Why map duration to log level? Because log levels mean something — or they should. If everything is info, nothing stands out. A 12-second query logged as critical will trigger any alert rule that fires on critical log entries without writing any additional monitoring code.

Why the config gate? DB::listen fires on every single query. In a high-traffic production environment, the overhead is real. Gate it behind app.debug or a dedicated config flag so you control when it runs.

The 100ms warning threshold is the fastest way to surface missing indexes and N+1 problems. You see the warning in the logs, you add the index, the warning stops. No user ever had to complain.

That said — this is optional. If you add nothing else from this section, the audit trail still works. The query listener is a low-cost addition that earns its place, not a requirement.

The model change logger

With a request ID threading through the system, model-level changes become meaningful entries in a traceable story rather than isolated database facts.

The implementation is a trait on any Eloquent model that needs auditing:

trait ModelChangeLogger
{
    public static function bootModelChangeLogger(): void
    {
        static::updating(function ($model) {
            $changed = array_diff_assoc(
                $model->getAttributes(),
                $model->getOriginal()
            );

            // updated_at is present in every update. It is never interesting.
            unset($changed['updated_at']);

            if (empty($changed)) {
                return;
            }

            // Build a field-level diff — not just the new values,
            // but what each field changed *from*
            $diff = [];
            foreach ($changed as $key => $newValue) {
                $diff[$key] = [
                    'old' => $model->getOriginal($key) ?? 'N/A',
                    'new' => $newValue,
                ];
            }

            $model->logChanges($diff, 'updated');
        });

        static::created(function ($model) {
            $model->logChanges($model->getAttributes(), 'created');
        });

        static::deleting(function ($model) {
            // Capture the full state before deletion — after deletion,
            // getAttributes() returns nothing useful
            $model->logChanges($model->getAttributes(), 'deleted');
        });
    }

    protected function prepareLogData(array $changes, string $event): array
    {
        // Mask sensitive fields before writing — log that they changed,
        // not what they changed to
        foreach ($this->maskedAttributes ?? [] as $attr) {
            if (isset($changes[$attr])) {
                $changes[$attr] = ['old' => '[REDACTED]', 'new' => '[REDACTED]'];
            }
        }

        return [
            'event'      => $event,
            'request_id' => request()->attributes->get(RequestLogger::REQUEST_ID_ATTRIBUTE, 'N/A'),
            'time'       => now()->toDateTimeString(),
            'model_id'   => $this->getKey(),
            'changes'    => $changes,
            'user_id'    => auth()->id(),
            'ip'         => request()->ip(),
            'user_agent' => request()->userAgent(),
        ];
    }

    // Override in each model to list fields that should never appear in plain text
    protected array $maskedAttributes = [];
}

A note on console context: When ModelChangeLogger runs inside a queued job or a scheduled command rather than an HTTP request, request()->attributes->get(REQUEST_ID_ATTRIBUTE) returns 'N/A' — that is the intentional fallback, not a bug. If you want correlation in background jobs, generate a job-level UUID in the job constructor and inject it via Log::shareContext() at the start of handle(), the same way RequestLogger does for HTTP requests.

Why getOriginal() rather than just the new values? Because "the amount field is now 500" is half the story. "The amount field changed from 5000 to 500" is evidence. In a dispute, the diff proves the change happened — not just the current state.

Why capture deleting before the delete, not after?

Common mistake: Using static::deleted instead of static::deleting for the deletion hook. deleted fires after the row is gone — getAttributes() returns nothing. Always use deleting.

deleting fires before the row is removed — the full record is still in memory. deleted fires after, and getAttributes() returns an empty array at that point.

File-based logs and the folder segmentation problem

Here is the decision that shapes the rest of the logging architecture: where do the log entries live?

The database option is tempting — it is queryable, indexable, and fits naturally into a Laravel application. The problem: any table your application can write to, your application can also modify. An UPDATE audit_logs is valid SQL. In a regulated environment, mutable audit records are a compliance liability.

Append-only log files are harder to tamper with. FILE_APPEND at the OS level means every write goes to the end — there is no update operation, only add. Combined with filesystem permissions where the web user can write but not delete, you have logs that are genuinely difficult to alter.

protected function logChanges(array $changes, string $event): void
{
    $logPath = $this->buildLogPath();

    file_put_contents(
        $logPath,
        json_encode($this->prepareLogData($changes, $event)) . PHP_EOL,
        FILE_APPEND | LOCK_EX  // LOCK_EX prevents concurrent writes corrupting the file
    );
}

Common mistake: Using FILE_APPEND alone. On a busy system where multiple requests modify records simultaneously, two processes can interleave their writes and corrupt a log entry. LOCK_EX acquires an exclusive lock — one write completes fully before the next begins. Both flags are required.

The folder structure problem: if you store each record's log in a folder named after the table, you eventually have transactions/ containing one file per transaction. A million transactions means a million files in one directory. Most filesystems handle this technically, but ls, backup tools, and directory enumeration operations become painfully slow.

The solution is segmentation — group records into subdirectories by ID range:

protected function buildLogPath(): string
{
    $id      = $this->getKey();
    $table   = $this->getTable();

    // Segment folder: floor to the nearest 100
    // IDs 1–99 → folder "0", IDs 100–199 → folder "100", IDs 1100–1199 → folder "1100"
    $segment = (int) (floor($id / 100) * 100);

    $folder = storage_path("logs/activities/{$table}/{$segment}");

    if (!is_dir($folder)) {
        mkdir($folder, 0755, true);
    }

    $filename = strtolower(class_basename($this)) . "_{$id}.log";

    return "{$folder}/{$filename}";
}

The result on disk:

storage/logs/activities/
    transactions/
        0/
            transaction_1.log
            transaction_42.log
        1100/
            transaction_1101.log
            transaction_1102.log
        1200/
            transaction_1200.log
    users/
        0/
            user_1.log

Each folder contains at most 100 files. Finding a specific record's history means knowing its ID — which you always do — and reading one file. The structure scales to any number of records without any folder becoming unwieldy.

Masking sensitive fields

An audit trail that contains plaintext national ID numbers or passwords creates its own compliance problem. In many jurisdictions, a log file with unredacted PII is treated like any other PII store — subject to retention limits, access controls, and deletion rights.

The approach here records that the field changed without recording what it changed to. An auditor can see that national_id was modified on Transaction 1101 at 14:32 by User 42 — which satisfies the audit requirement — without the log file holding the actual values.

Override $maskedAttributes on any model that stores sensitive data:

class Transaction extends Model
{
    use ModelChangeLogger;

    protected array $maskedAttributes = [
        'national_id',
        'card_number',
    ];
}

Where RBAC fits into this picture

Access control and audit trails are related problems. If you are logging who changed records, you should also log who tried to do something they were not allowed to.

Laravel's Gate provides a hook for exactly this:

Gate::after(function (User $user, string $ability, bool $result) {
    if (!$result) {
        // request_id is automatically included via Log::shareContext()
        // set in RequestLogger — no need to fetch it manually here
        Log::channel('request')->warning('Authorization denied', [
            'user_id' => $user->id,
            'ability' => $ability,
            'ip'      => request()->ip(),
        ]);
    }
});

Why log failures specifically? A successful authorization attempt is normal operation. A failed attempt is a signal — a user may be probing endpoints they should not have access to, or a compromised account may be attempting privilege escalation. The pattern across multiple failed attempts becomes early warning you would not have without this hook.

One design principle worth stating: design permissions around abilities, not role names. $user->can('transaction.approve') expresses what the user can do, regardless of what role label they carry. $user->role === 'admin' breaks the moment "admin" means different things in different contexts — and in growing systems, it always eventually does.

What you now have

Register RequestLogger as global middleware. Add ModelChangeLogger to any Eloquent model. Register the Gate::after hook.

Now: every request carries an ID. Every model change records who made it, which field changed from what value to what, when, and which request caused it. Failed permission checks are logged. Every log line across your stack shares a common correlation ID.

When a support ticket arrives saying "something changed on Transaction 1101," you open storage/logs/activities/transactions/1100/transaction_1101.log. You see the exact diff, the user who made it, the request ID. You grep that request ID in your request logs. You have the complete picture in under a minute.

That is the difference between an application that works and one that remembers.

The key insight from this article: A database audit table is mutable — your application code can UPDATE it. Append-only log files with a request ID threaded through every entry give you tamper-resistant, correlated records that answer who, what, and why in one grep.

Before you ship — checklist

[ ] RequestLogger registered as global middleware in bootstrap/app.php
[ ] ModelChangeLogger trait added to every model that handles sensitive or auditable data
[ ] $maskedAttributes defined on models that store PII (passwords, national IDs, card numbers)
[ ] storage/logs/activities/ is writable by the web user, not deletable
[ ] DB::listen is gated behind a config flag or app.debug — not running unconditionally in production
[ ] Gate::after hook registered in AuthServiceProvider
[ ] A grep for a known request ID returns results across both the request log and model change logs

Next: Part 2 — Queue Architecture: Designing Background Work That Holds Up

Laravel Architecture Patterns for Production

Shakil Alam — Fri, 17 Apr 2026 16:28:52 +0000

Most Laravel applications work. Routes respond, data gets saved, users can log in. The framework handles it.

Then the hard questions arrive. Can you prove that transaction wasn't tampered with? Or: what happens when a bulk operation dispatches 5,000 jobs overnight? Or: what happens to our users when that third-party API goes down?

These are the questions that separate a Laravel application that works from one that holds up.

This series is built from real production code — written after those questions were asked, after something went wrong, after a requirement changed in a way the original architecture couldn't handle. Every pattern came from a real system under real pressure: fintech, regulated environments, places where "it works" is not a sufficient answer.

Who this is for: You have shipped Laravel to production. You know the framework. Now you are being asked to make the system serious — audit-ready, reliable under load, and defensible under scrutiny. You want the reasoning behind the patterns so you can adapt them, not just the code to copy.

Requirements: PHP 8.0+ and Laravel 9+ for all four parts. Part 4 uses Illuminate\Support\Facades\Context, which requires Laravel 11 — a compatible fallback for earlier versions is shown in that article.

On scope: These patterns came from specific production environments and reflect specific tradeoffs. They are documented decisions, not universal prescriptions. Each article names the tradeoffs and labels the common mistakes so you can make an informed choice for your own context.

The Four Parts

Part 1 — The Audit Trail: Building a System That Remembers

~10 min read · Compliance · Model logging · Request tracing

A request ID generated in middleware that automatically appears in every log line for that request. Field-level model diffs that capture what changed from what value to what — not just that a record was updated. Append-only log files segmented to stay fast at scale. A Gate hook that logs failed permission checks before they become incidents.

A database audit table is mutable. Append-only files are not. That one sentence shapes the entire architecture.

Part 2 — Queue Architecture: Designing Background Work That Holds Up

~9 min read · Queue design · Job architecture · Background processing

Why passing an Eloquent model to a job constructor is the wrong call, and what to pass instead. How to design a queue topology before you are forced to by a problem. Retry strategies matched to transient, rate-limited, and permanent failures. File operations written to survive a crash mid-write.

A password reset email stuck behind a video compression job is not a queue problem. It is a topology problem.

Part 3 — Secure File Uploads: Seven Checks and Why Each One Exists

~9 min read · Security · Middleware · File handling

A middleware that validates seven independent properties of every uploaded file, each one named and explained. Server-side MIME detection using finfo — not the browser's claim. A unique name strategy that removes user-controlled strings from filesystem paths entirely. A storage pattern where no uploaded file is ever directly reachable via HTTP.

getClientMimeType() returns whatever the browser sent. finfo reads the actual bytes. Only one of those is a security check.

Part 4 — External API Reliability: When Their System Goes Down

~9 min read · Integration architecture · Resilience · Fault tolerance

A trait that makes the fallback decision — fail loud or fail silent — explicit in the model, not buried in a catch block. A recovery path for operations that completed externally but failed locally. The idempotency question, and why it matters when the database write fails after the external API already accepted the request.

The 2am outage will still happen. The question is whether your system has a designed response or an improvised one.

Each article stands on its own. But if you are reading from the start, Part 1 establishes a request ID that runs as a thread through every subsequent part.

How I Reduced Video Storage by 30GB/Day Using FFmpeg and Laravel

Shakil Alam — Tue, 07 Apr 2026 16:09:11 +0000

Most teams don't realize how expensive "just 30 seconds of video" can become — until it silently turns into terabytes of storage and a massive monthly bill.

That's exactly what happened to us.

We were storing millions of short verification clips, each only ~30 seconds long — but together, they were costing us hundreds of GBs every month.

Instead of throwing money at storage, we decided to fix the root problem.

The result?
👉 20–30 GB saved per day
👉 60% average compression
👉 Zero impact on review quality

At my company, we run a video-based verification flow — users record short clips (typically 30 seconds) that get reviewed by our team. Simple enough. But over time, those clips add up fast.

We had millions of recorded videos in storage with a retention requirement of 2–4 years. The storage bill kept climbing. The turning point came when I actually measured what we were storing — and realized we were saving far more data than we needed to.

This is the story of how I built a pipeline that now compresses 2,000+ videos per day and saves 20–30 GB of storage daily — without touching a single live file.

Real Numbers from Production

Before going into the how, here's what one day's run looks like on our compression dashboard:

Metric	Value
Videos processed	2,203
Total space saved	15.66 GB
Average compression ratio	62.1%
Best compression recorded	99.92%

An average reduction of 62% in file size. Some clips (usually silent or nearly-static ones) compress all the way to 99.9%. Even on a typical day, we're saving 15+ GB from a single cron run.

The Problem: Over-Engineered for the Wrong Use Case

Our original recording setup used browser defaults — high resolution, high framerate, stereo audio at 48kHz. Reasonable general-purpose settings, but completely overkill for a 30-second face verification clip.

When the backlog started growing into the millions of files, the cost became impossible to ignore. But before writing a single line of compression code, I needed to understand why the files were so large — and fix the source before compressing the backlog.

Step 1: Research, Experiment, Validate

I didn't just pick lower settings and ship them. I researched codec behavior, tested different bitrate and quality combinations, and — critically — validated with real recordings before touching user traffic.

The validation approach: Our verifiers (the people who review verification videos) also record their own video profiles. This was the perfect test population — small, controlled, and internal. I rolled out the new recording constraints to verifier accounts first and asked them to record 10-second clips, much longer than a typical verification video.

Why 10 seconds? Because problems with codec settings, device compatibility, or audio quality tend to hide in short clips but surface in longer ones. Buffer issues, audio sync drift, encoding artifacts under motion — these all become visible when you push the duration.

Once the verifier videos came back clean across a range of devices (Chrome on Android, Chrome on desktop, Safari on iOS), I had confidence the settings were correct. Only then did I roll them out to user-facing recording.

Step 2: Optimize Video Recording at the Source

Understanding Browser Codec Support (VP8 vs VP9)

Modern browsers support two primary video codecs for MediaRecorder:

VP8 — the older WebM codec. Widely supported across all browsers and platforms, including older Android devices. Less efficient compression than VP9 but extremely reliable.

VP9 — Google's newer codec. Significantly better compression at the same quality level, especially for low-motion content like talking heads. Supported in Chrome, Firefox, and most modern browsers, but not always available on older devices or in certain Safari contexts.

Why fallback matters: If you specify video/webm;codecs=vp9,opus and the browser or device doesn't support VP9, MediaRecorder will either throw an error or silently produce a broken file. A hardcoded codec choice that works on your test device will fail on some percentage of real users' devices. You need to probe support at runtime:

const mimeTypes = [
  'video/webm;codecs=vp9,opus',   // Best: VP9 video + Opus audio
  'video/webm;codecs=vp8,opus',   // Good: VP8 video + Opus audio
  'video/webm'                     // Fallback: browser chooses
];

const mimeType = mimeTypes.find(type => MediaRecorder.isTypeSupported(type)) || '';

MediaRecorder.isTypeSupported() checks at runtime whether the current browser/device combination actually supports a given MIME type. The list is ordered by preference — VP9 first, VP8 second, browser default last. Whatever the device supports, it gets the best available option.

The actual recording constraints

const constraints = {
  video: {
    width: { ideal: 640 },
    height: { ideal: 480 },
    frameRate: { ideal: 24 }
  },
  audio: {
    sampleRate: 16000,
    channelCount: 1,        // mono
    echoCancellation: true,
    noiseSuppression: true
  }
};

const mediaRecorder = new MediaRecorder(stream, {
  mimeType,
  videoBitsPerSecond: 1_000_000,    // 1 Mbps cap
  audioBitsPerSecond: 64_000         // 64 Kbps cap
});

Why each decision:

640×480 at 24fps — Sufficient to clearly identify a face. 30fps and 1080p are for content you'll watch repeatedly; a verification clip gets reviewed once.
16kHz mono audio — Voice intelligibility tops out around 8kHz. 16kHz captures speech clearly with half the data of 44.1kHz stereo. The verifier needs to hear what someone says, not enjoy high-fidelity audio.
1 Mbps video / 64 Kbps audio — A cap at the recorder level. Without this, VP8 in particular can spike well above reasonable bitrates on some devices.
echoCancellation + noiseSuppression — These reduce audio variance, which compresses better downstream. Noisy or echoey audio encodes less efficiently.

Step 3: Compress the Backlog

Fixing the source stopped the problem from growing. But millions of old files still existed at the original large sizes. I built a three-layer Laravel pipeline to work through them.

Layer 1 — Artisan Command

php artisan media:compress-videos --chunk=200 --dry-run

# or target a single video for testing:
php artisan media:compress-videos --id=202423

The command queries all records with a video/% MIME type, chunks them into batches of 200, and dispatches a queued job per video. The --dry-run flag lets you see what would be processed without doing anything — useful before running on production for the first time.

Layer 2 — Queued Job

class CompressMediaVideo implements ShouldQueue
{
    public int $tries = 3;
    public int $timeout = 120;

    public function handle(VideoCompressorService $compressor): void
    {
        $media = Media::findOrFail($this->mediaId);

        if (!str_starts_with($media->mime_type, 'video/')) {
            return; // skip safely
        }

        $compressor->compress($media);
    }
}

One job per video. If a job fails, it retries independently without affecting the others. The compression run can take months on a backlog of millions — having individual, retryable jobs means a server restart or a bad file doesn't set you back to zero.

Layer 3 — Deep Dive into FFmpeg Compression Strategy

This is where the actual compression happens. Some context on how it works:

What FFmpeg is doing: It reads the original WebM file (usually H.264 video + Opus audio, recorded by Chrome), re-encodes the video track using VP9, re-encodes the audio using Opus at a lower bitrate, and writes a new WebM container.

Why VP9 for compression? VP9 uses much more sophisticated algorithms than H.264 — it's better at identifying redundant information across frames and removing it. For a mostly-static scene like a person talking against a wall, VP9 can throw away enormous amounts of data while keeping the image perfectly clear to a human reviewer.

What CRF means: CRF (Constant Rate Factor) is quality-controlled encoding. Instead of targeting a specific bitrate, you specify a quality level and FFmpeg decides how many bits are needed to achieve it. Lower CRF = higher quality = larger file. Higher CRF = more compression = smaller file.

For VP9, CRF 33 is roughly "good quality." CRF 35 is "slightly aggressive." CRF 40+ starts to look visibly degraded. I chose CRF 35 because:

It's a face verification clip, not a film
The reviewer needs to see the face clearly, not count pores
Our production data confirms it works — the 62.1% average compression ratio came from CRF 35

$command = [
    'ffmpeg', '-i', $inputPath,
    '-c:v', 'libvpx-vp9',
    '-crf', '35',
    '-b:v', '0',           // Required for CRF mode in VP9
    '-c:a', 'libopus',
    '-b:a', '64k',
    '-y', $tempPath
];

Note: -b:v 0 is required when using CRF mode with libvpx-vp9. Without it, VP9 defaults to a target bitrate mode and ignores the CRF value.

Safe Processing with Atomic File Replacement

$exitCode = $process->run();

if ($exitCode !== 0) {
    @unlink($tempPath);
    // Log and store error output for debugging
    $media->update(['compressed_meta' => ['error' => $process->getErrorOutput()]]);
    return;
}

// Only replace the original after successful compression
rename($tempPath, $inputPath);

FFmpeg writes to a .tmp file first. If encoding fails for any reason — corrupt input, disk full, process killed — the original file is untouched. The rename() only happens after a confirmed successful exit code. In a pipeline processing millions of files, this matters.

The service also skips files that would grow: if the compressed output is larger than the original (which happens with already-optimized or very short files), saved_bytes is recorded as 0 and the original is kept. The dashboard's -130.33% low value represents exactly this case — a tiny file that got larger under re-encoding.

Step 4: Storage Lifecycle Management (Trash + Cleanup Strategy)

When a verification video is rejected and the user records a new one, we don't immediately delete the old clip. It gets moved to a trash/ directory. A weekly cron job permanently removes everything older than 7 days in trash.

This gives the ops team a recovery window without keeping rejected videos indefinitely. It also keeps the compression pipeline clean — trash videos are excluded from the compression queue since they're headed for deletion anyway.

Results

One day's run (March 11, 2026):

2,203 videos compressed
15.66 GB saved
62.1% average compression ratio

Projected at scale:

At ~20 GB/day average: 600 GB/month, 7+ TB/year
The backlog has millions of videos — this pipeline will run for months
New uploads are already smaller thanks to the recording constraint changes

Key Takeaways

Validate on internal users first. Rolling out recording changes to verifier accounts before users meant any issues would be caught internally. Testing with 30-second clips specifically surfaces problems that short clips hide.
Probe codec support at runtime. Never hardcode a MIME type. MediaRecorder.isTypeSupported() is a one-liner that ensures every device gets the best encoding it can handle.
CRF over bitrate caps. A fixed bitrate wastes bits on simple scenes and starves complex ones. CRF adapts to content — simple talking-head frames get very small, complex frames get what they need.
-b:v 0 is not optional for VP9 CRF. This trips up a lot of people. VP9 in FFmpeg defaults to bitrate mode; CRF only activates when you explicitly set -b:v 0.
Atomic writes protect your data. In bulk processing, things fail. Write to temp, verify success, then rename. Never write directly to the live path.
Queue per file, not per batch. Individual queued jobs make the pipeline restartable, observable, and fault-tolerant. A bad file fails in isolation; everything else keeps running.

I write about backend engineering and fintech systems at blog.shakiltech.com. If this was useful, the next post covers the Laravel queue architecture behind this pipeline.

Laravel Fast2SMS v2.0.0 — WhatsApp Support, Notification Channels & a Smarter DX

Shakil Alam — Sun, 29 Mar 2026 05:07:09 +0000

When I shipped v1, the goal was simple: send SMS to Indian phone numbers from Laravel without wrestling raw API arrays. v2.0.0 takes that same idea much further.

The headline is WhatsApp Business API support — text, images, documents, locations, templates, reactions, stickers, and interactive messages, all through the same familiar Fast2sms facade. Beyond that, v2 brings drop-in Laravel Notification Channels, a typed exception hierarchy, expressive testing utilities, and cost-saving guards that protect your wallet in production.

⚠️ This is a major release with breaking changes. See the Upgrade Guide before updating.

Let me walk you through what matters.

💬 WhatsApp Business API

This is the big one. Starting in v2.0.0, the package supports the Fast2SMS WhatsApp Business API through Fast2sms::whatsapp().

Send a plain text message:

use Shakil\Fast2sms\Facades\Fast2sms;

Fast2sms::whatsapp()
    ->to('9999999999')
    ->text('Your order has been shipped and is on its way!')
    ->send();

Send an image with a caption:

Fast2sms::whatsapp()
    ->to('9999999999')
    ->image('https://yourapp.com/invoice.png', caption: 'Your invoice for order #1042')
    ->send();

Send a document:

Fast2sms::whatsapp()
    ->to('9999999999')
    ->document('https://yourapp.com/receipt.pdf', filename: 'receipt.pdf')
    ->send();

Send a location:

Fast2sms::whatsapp()
    ->to('9999999999')
    ->location(lat: 28.6139, lng: 77.2090, name: 'New Delhi')
    ->send();

Send a registered template:

Fast2sms::whatsapp()
    ->to('9999999999')
    ->template(id: 'YOUR_TEMPLATE_ID', variables: ['John', 'Order #1042'])
    ->send();

React to a message, send a sticker, or build interactive button flows — the full WhatsApp API surface is available through the same fluent chain.

🔔 Laravel Notification Channels

v2 ships two drop-in notification channels: SmsChannel and WhatsAppChannel. Your existing notification classes work exactly the way you'd expect.

use Shakil\Fast2sms\Channels\SmsChannel;
use Shakil\Fast2sms\Channels\WhatsAppChannel;
use Shakil\Fast2sms\Messages\SmsMessage;
use Shakil\Fast2sms\Messages\WhatsAppMessage;

class OrderShipped extends Notification
{
    public function via($notifiable): array
    {
        return [SmsChannel::class, WhatsAppChannel::class];
    }

    public function toFast2sms($notifiable): SmsMessage
    {
        return SmsMessage::create()
            ->otp('Your OTP is 482910. Valid for 10 minutes.');
    }

    public function toWhatsApp($notifiable): WhatsAppMessage
    {
        return WhatsAppMessage::create()
            ->text('Your order has been shipped!');
    }
}

Add the routing methods to your User model and you're done:

public function routeNotificationForFast2sms(): string
{
    return $this->phone_number;
}

public function routeNotificationForWhatsapp(): string
{
    return $this->phone_number;
}

No facade, no manual number passing. Just idiomatic Laravel.

🧱 Typed Exception Hierarchy

In v1, every API failure threw a single Fast2smsException. In v2 you can catch exactly what you need:

use Shakil\Fast2sms\Exceptions\AuthenticationException;
use Shakil\Fast2sms\Exceptions\RateLimitException;
use Shakil\Fast2sms\Exceptions\InsufficientBalanceException;
use Shakil\Fast2sms\Exceptions\NetworkException;

try {
    Fast2sms::otp('9999999999', '845621');
} catch (InsufficientBalanceException $e) {
    // Notify your team — wallet is empty
} catch (RateLimitException $e) {
    // Back off and retry
} catch (AuthenticationException $e) {
    // API key is wrong or expired
} catch (NetworkException $e) {
    // Fast2SMS was unreachable
}

The full list of typed exceptions is in the changelog.

🧪 Rich Fake Assertions for Testing

v2 ships 16 assertion methods on Fast2smsFake so your feature tests are expressive and readable — no more inspecting raw recorded calls.

Fast2sms::fake();

// ... trigger your code ...

Fast2sms::assertSmsSentTo('9999999999');

Fast2sms::assertSmsSentTo('9999999999', fn ($sms) =>
    str_contains($sms->message, '482910')
);

Fast2sms::assertWhatsAppSentTo('9999999999');

Fast2sms::assertNothingSent();

// Clean up for tests that need real sending
Fast2sms::stopFaking();

💡 Fluent Message Builders with Credit Helpers

SmsMessage and WhatsAppMessage are first-class objects with named constructors and chainable setters. SmsMessage also ships with credit helpers so you can estimate cost before you send:

use Shakil\Fast2sms\Messages\SmsMessage;

$message = SmsMessage::create()
    ->withContent('Your appointment is confirmed for tomorrow at 10am.')
    ->withRoute(SmsRoute::QUICK);

$message->charCount();       // character count
$message->isUnicode();       // true if Unicode encoding is needed
$message->creditCount();     // SMS credits this will consume
$message->exceedsOneSms();   // true if longer than one SMS

No more guessing whether a long message costs 1 credit or 3.

🛡️ Cost-Saving Guards

v2 introduces a set of opt-in guards that protect your wallet in production. All are off by default — enable only what your use case needs in config/fast2sms.php:

Guard	What it does
Recipient deduplication	Strips duplicate numbers before every send
Invalid recipient stripping	Validates numbers and logs warnings instead of failing hard
Idempotency guard	Blocks the same message being sent twice within a TTL window
Rate throttle	Sliding-window per-minute cap via Laravel cache
Balance gate	Checks your wallet before sending; fires `LowBalanceDetected` when low
Batch splitting	Splits large recipient lists into chunks automatically

⚙️ New Artisan Commands

# List every event the package fires, with descriptions
php artisan fast2sms:events

# Generate an IDE helper file for full autocompletion
php artisan fast2sms:ide-helper

Run fast2sms:ide-helper once after install and get full autocompletion on every facade method in PhpStorm or VS Code.

🚀 Getting Started

Requirements: PHP ^8.3 (8.4 and 8.5 also tested), Laravel 11, 12, or 13.

composer require itxshakil/laravel-fast2sms

php artisan vendor:publish --tag=fast2sms-config

FAST2SMS_API_KEY="your-api-key"
FAST2SMS_DEFAULT_SENDER_ID="FSTSMS"
FAST2SMS_DEFAULT_ROUTE="dlt"

Upgrading from v1

The public sending API — Fast2sms::quick(), ::dlt(), ::otp(), and now ::viaWhatsApp() — is completely unchanged. Most v1 code will work without modification.

The breaking changes are in internals: exception types, DTOs, and return type hints. The full step-by-step migration is in UPGRADING.md.

Git Explained Simply — For People Who Have No Idea What It Is

Shakil Alam — Sun, 15 Mar 2026 08:44:59 +0000

You've seen the word Git everywhere.

Job listings. GitHub. Tutorials that just assume you already know what it means. Nobody ever stopped to explain it from scratch.

This post is that explanation.

No jargon. No assumed knowledge. By the end you'll know what Git is, why it exists, and how to make your first commit — in about 15 minutes.

What is Git?

Git is a tool that saves every version of your code — not just the latest one.

Here's a simple way to think about it:

Imagine you're writing an essay in Word. Every time you hit Save, the old version disappears. You only ever have the latest copy. Delete a paragraph and save — that paragraph is gone forever.

Now imagine you could hit a special kind of Save that:

Keeps every previous version, forever
Lets you go back to any version at any time
Lets you add a note explaining what you changed and why
Lets you try something risky without touching your working version

That's Git. For code instead of essays.

Why does this matter?

Without Git, developers end up doing things like:

Saving files as project_final.js, project_final_v2.js, project_ACTUAL_FINAL.js
Deleting something, realising they needed it, having no way to get it back
Two people editing the same file and overwriting each other's work
Being afraid to make changes because they might break something

Git solves all of these. That's why every professional developer uses it.

Git vs GitHub — they are not the same thing

This trips up almost everyone at first.

Git is a tool that runs on your computer. It tracks your code history. It's free, open source, and works completely offline.

GitHub is a website. It stores your Git history online, lets you share your code, and makes it easy to collaborate with other developers. Think of it like Google Drive, but built specifically for Git.

You can use Git without GitHub. But most developers use both together — Git on their machine to track changes, GitHub online to back up and share.

Five words you'll hear constantly

Before we touch any commands, here are the five terms that come up in almost every Git conversation. Read them once — you don't need to memorise them, just have a rough idea so they don't throw you when you see them.

Repository (repo)
A repository is just a project folder that Git is watching. That's it. When a developer says "clone the repo" or "push to the repo" they mean the project. Your my-first-project folder? Once you run git init inside it, that's a repository.

Commit
A commit is a snapshot — a permanent record of exactly what your code looked like at a specific moment. Every commit has a short message you write yourself, like "Add login page" or "Fix broken checkout button". Think of it as pressing Save, but instead of overwriting the last save, Git keeps every single one and lines them up in order. You can go back to any of them at any time.

Branch
Imagine you're writing a book and you want to try a completely different ending — but you don't want to delete the original. You'd make a copy, experiment on the copy, and if it works, swap it in. If it doesn't, throw it away.

That's a branch. It's a separate version of your project where you can make changes freely, without touching anything that's working. When you're happy with the changes, you merge the branch back in. If you hate it, you just delete the branch — your original code is completely untouched.

This is one of the most powerful things Git does, and you'll use it constantly once you get the hang of it.

Push
When you commit, the snapshot is saved on your computer only. Push is how you send those commits up to GitHub so they're backed up online and others can see them.

Computer → GitHub = Push

Pull
The opposite of push. If someone else on your team made changes and pushed them to GitHub, pull is how you get those changes down onto your computer.

GitHub → Computer = Pull

That's all five. After you've used Git for a day or two, these words will feel completely natural.

Your first 15 minutes with Git

Let's actually do it rather than just talk about it.

Step 1 — Install Git

Go to git-scm.com and download Git for your system. Install with the default options.

Open your terminal and check it worked:

git --version

If you see something like git version 2.43.0 — you're set.

Step 2 — Tell Git who you are

Git labels every commit with your name and email. Set them once:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

This only needs doing once per computer.

Step 3 — Create your first repository

mkdir my-first-project
cd my-first-project
git init

git init tells Git: start watching this folder. That's it — you now have a Git repository.

Step 4 — Add a file and make your first commit

Create a simple file:

echo "Hello, Git!" > hello.txt

Saving a file in Git is a two-step process:

Stage it — tell Git you want to include this file in the next snapshot:

git add hello.txt

Commit it — take the actual snapshot, with a message:

git commit -m "Add hello.txt"

You just made your first commit. Git has permanently recorded this moment.

Step 5 — Make a change and watch Git track it

Edit hello.txt — change the text to anything, save the file. Now run:

git status

Git tells you the file has changed. To see exactly what changed, line by line:

git diff

Lines you removed show in red. Lines you added show in green. Git caught everything automatically.

Commit the change:

git add hello.txt
git commit -m "Update the greeting"

Step 6 — Look at your history

git log --oneline

Both commits are listed. This list grows with every commit you ever make. It never gets deleted. That's your permanent history.

Why two steps? (The staging question everyone asks)

New developers always wonder why you can't just commit directly without staging first.

The staging step (git add) exists so you can choose exactly what goes into a commit. You might have changed five files but only want to save two of them right now. Staging gives you that precision.

It feels awkward the first few times. After a week it becomes automatic.

The one habit that makes all the difference

Commit small. Commit often.

Every time you finish one thing — not everything, just one small thing — make a commit. Every time the code is in a working state you want to remember, make a commit.

❌ Bad commit message	✅ Good commit message
`stuff`	`Add email validation to the signup form`
`fix`	`Fix broken checkout button on mobile`
`update`	`Update user profile to allow avatar uploads`

The message is not for Git. It's for you, six months from now, trying to figure out what you were thinking.

Most teams follow a format called Conventional Commits that makes messages consistent across the whole team. It's the single most impactful habit to build early: Commit Like a Pro: A Beginner's Guide to Conventional Commits

What to learn next

Set up Git properly for real projects
SSH keys, useful config, connecting to GitHub — the setup that makes Git work smoothly day to day:
Practical Git & GitHub Setup for Real-World Projects

git switch vs git checkout
You'll see both in tutorials. They do similar things — here's the difference:
Git Checkout vs Git Switch

How to recover anything you thought you deleted
Once you've used Git for a bit, this is the one that makes you feel invincible:
Git Reflog Explained: Recover Deleted Commits & Lost Work

Find exactly which commit broke something
Git has a built-in tool that searches your entire history automatically:
Git as Your Safety Net: The Confidence to Work Fearlessly

The full Git Mastery Series

When you're ready to go beyond the basics, this series takes you from how Git actually thinks to using it as your permanent safety net:

How Git Actually Thinks — the mental model that changes everything
Committing with Intention — writing commits that mean something
Branching Without Fear — working in parallel without breaking things
Collaboration That Doesn't Create Chaos — working with a team
Git as Your Safety Net — recovering from anything

If you want everything in one place — checklists, 80+ commands, hook templates, and a recovery playbook for when things go wrong — I put it all into a 23-page PDF you can keep open while you work.

Git Mastery Field Guide →

But start here. Get the basics under your fingers first. Everything else builds on top of this.

Questions? Drop them in the comments. There are no silly questions when you're just getting started.

Git as Your Safety Net: The Confidence to Work Fearlessly

Shakil Alam — Sun, 15 Mar 2026 08:29:50 +0000

Part 5 of the Git Mastery Series
← Part 4: Collaboration That Doesn't Create Chaos

By the time most developers reach this level of Git knowledge, they've already had the experience that makes everything click.

Maybe they ran git reset --hard and thought they lost a day's work. Maybe they deleted a branch too early. Maybe a rebase went sideways and they couldn't figure out how to get back to where they started. Maybe they pushed directly to main and spent an hour trying to undo it.

Those moments are terrifying when you don't know about Git's safety nets. Once you do, they become inconveniences — things you recover from in five minutes rather than crises.

This part isn't about new commands to memorize. It's about changing your relationship with Git entirely — from treating it as something to be careful around to using it as the thing that makes you less careful, because you know you can recover from almost anything.

Nothing Is Permanent Until the Garbage Collector Runs

Here's the most liberating thing to understand about Git: deleting a commit doesn't delete it.

When you run git reset --hard HEAD~3, you're moving the branch pointer backward three commits. The three commits you "deleted" are still in the object store. They still exist as objects in the .git folder. They're just not pointed to by any branch anymore.

Git's garbage collector (git gc) runs automatically every few hundred operations or when you explicitly call it. By default, it only removes objects that have been unreferenced for more than 90 days. You have a 90-day window to recover almost anything.

This means: you can be bold. Try risky rebases. Reset commits. Delete branches. Move things around. The cost of being wrong is usually five minutes of recovery, not lost work.

Reflog: Git's Black Box Recorder

git reflog is the command that has saved more careers than any other.

Every time HEAD moves — every commit, checkout, rebase, reset, merge, cherry-pick — Git records it in the reflog. This is completely separate from your commit history. It's a log of every position HEAD has ever been at, including states that no longer have a branch pointing to them.

git reflog

Output:

a3f8c9d HEAD@{0}: commit: fix(auth): handle null token on refresh
1b4e7a2 HEAD@{1}: rebase (finish): returning to refs/heads/feature/auth
9c4d2e1 HEAD@{2}: rebase (pick): feat(auth): add OTP verification
7a5b3f8 HEAD@{3}: rebase (pick): feat(auth): add login endpoint  
2e8d1c4 HEAD@{4}: checkout: moving from main to feature/auth
f3a9b7e HEAD@{5}: reset: moving to HEAD~3
8d2c5a1 HEAD@{6}: commit: add debug logging

See that HEAD@{5} — a reset: moving to HEAD~3? Those three commits you "deleted" are still accessible. HEAD@{6} is one of them. You can get back to that state:

# Recover from that reset
git reset --hard HEAD@{6}

# Or create a branch from that lost commit
git switch -c recovery/lost-work HEAD@{6}

Scenario: you deleted a branch before merging

# Find where the branch was
git reflog | grep "branch-name"
# or just scroll through and find the last commit on it

# Create a new branch at that commit
git switch -c feature/recovered-branch a3f8c9d

Scenario: rebase went wrong

# Before rebasing, note where you are
git log --oneline -1
# a3f8c9d feat: current state

# Rebase goes badly
git rebase main
# This looks completely wrong...

# Go back to before the rebase started
git reflog
# Find the entry just before "rebase (start)"
git reset --hard HEAD@{N}

The reflog only exists locally — it's not pushed to remote. So it won't help you recover something on another developer's machine. But for your own work, it's a complete audit trail.

The Commands That Feel Dangerous (And What They Actually Do)

git reset --hard

This is the one developers fear most. It moves the branch pointer and updates both the staging area and working directory to match the target commit. Any uncommitted changes are gone.

The key word: uncommitted. If your changes are committed, reset --hard doesn't lose them — it just makes them harder to find. Use git reflog to find the commit hash, then git reset --hard <that-hash> to get back.

If you had uncommitted changes, those are genuinely gone from Git's perspective. But your editor's local history (VS Code's timeline, IntelliJ's local history) often has them. Check there first.

git rebase

Rebase feels risky because it rewrites commit hashes. But here's what actually happens: Git creates new commits with the same changes but different parent hashes. The old commits still exist. Before any significant rebase, the reflog has your back:

# If rebase goes wrong, find where you were before it started
git reflog | head -20
# Find the "rebase (start)" entry and look one above it
git reset --hard HEAD@{N}

git push --force

This is actually dangerous on shared branches — you genuinely can overwrite someone else's work. But on your own feature branch? It's routine after an interactive rebase. The safe variant --force-with-lease checks that nobody else has pushed since you last fetched before allowing the force push.

git clean -fd

This removes untracked files and directories. Unlike most Git operations, this is genuinely irreversible — untracked files aren't in Git's object store, so they can't be recovered with reflog. Always run git clean -nd first (the dry run) to see exactly what would be deleted:

git clean -nd  # dry run — shows what would be deleted
git clean -fd  # actually delete

Stash: The Scratch Pad Between Branches

You're halfway through a feature when someone says there's a production bug that needs fixing immediately. Your working directory has changes everywhere. You don't want to commit half-finished work.

# Save current work
git stash

# Switch to main, fix the bug, push
git switch main
# ... fix bug ...
git switch feature/my-feature

# Get your work back
git stash pop

Stash saves your working directory and staging area state, and gives you a clean working directory. git stash pop restores it and removes the stash entry.

A few things most developers don't know about stash:

# Give the stash a meaningful name (you'll thank yourself later)
git stash push -m "halfway through payment refactor"

# See all stashes
git stash list
# stash@{0}: On feature/auth: halfway through payment refactor
# stash@{1}: On main: quick experiment

# Apply a specific stash (without removing it)
git stash apply stash@{1}

# Stash only specific files
git stash push -m "auth changes only" src/auth/

# Stash including untracked files
git stash -u

One warning: stashes are local. They're not pushed to remote. If you stash something on your laptop and switch to another machine, that stash doesn't exist there. Don't use stash as a long-term storage mechanism — it's a scratch pad, not a parking lot.

Cherry-Pick: Taking Exactly What You Need

Sometimes a commit exists on one branch and you need it on another, without merging the whole branch.

You fixed a critical bug on feature/auth but it's not merged yet. You need that fix on main today. Cherry-pick applies the exact changes from that commit onto your current branch:

# Get the commit hash
git log feature/auth --oneline
# a3f8c9d fix(auth): prevent session fixation on login

# Apply it to main
git switch main
git cherry-pick a3f8c9d

Git creates a new commit on main with the same changes but a different hash. The original commit on feature/auth is unchanged.

Cherry-pick is precise and powerful, but use it intentionally. If you find yourself cherry-picking many commits between branches regularly, that's usually a sign your branching strategy has a gap — there should be a path to get those changes merged properly rather than manually copied.

Bisect: Binary Search for the Bug That Snuck In

Something is broken. You don't know which commit introduced it. You know it worked last week. There might be 200 commits between "worked" and "broken."

git bisect runs a binary search through your history, cutting the search space in half at each step. 200 commits becomes 7–8 tests instead of 200.

git bisect start
git bisect bad                     # Current state is broken
git bisect good v2.1.0             # This tag was working

# Git checks out the midpoint commit
# Test your application...
# Working? 
git bisect good
# Broken?
git bisect bad

# After 7-8 steps, Git identifies the exact commit:
# a3f8c9d is the first bad commit

git bisect reset  # Return to original state

If you have a test that can verify the bug automatically, bisect becomes even more powerful:

git bisect run php artisan test --filter=UserAuthTest

Git checks out each midpoint, runs the test, and classifies it automatically. You can walk away and come back to the answer. This is how you debug a regression that crept in across a long sprint — not by reading every commit, but by letting Git find it for you.

Worktrees: Multiple Branches at Once Without Stashing

Here's a scenario: you're deep into a feature branch and need to check something on main — not just look at a file, but actually run the code. Normally you'd stash, switch, run, switch back, pop stash.

git worktree lets you check out a second branch into a separate folder, running both simultaneously:

# Check out main into a separate folder
git worktree add ../project-main main

# Now you have:
# /project              (your feature branch)
# /project-main         (main branch, fully checked out)

# Work in both simultaneously
cd ../project-main
php artisan serve --port=8001

# When done, remove the worktree
git worktree remove ../project-main

Each worktree shares the same .git folder — they're not separate repositories. Changes committed in one worktree are immediately visible in the other. This is particularly useful for reviewing a colleague's PR while staying on your own branch, or comparing behavior between branches in real-time.

Building a Git Workflow You Actually Trust

The developers who use Git most confidently aren't the ones who know the most commands. They're the ones who've built habits that mean they rarely need recovery procedures in the first place.

A few habits that, combined, create a workflow with almost no risk:

Commit often. Small, atomic commits are easier to revert, cherry-pick, and understand. A commit every 30–60 minutes of real work is not too often. It's exactly right.

Branch before you start anything. Ten seconds. Every time. The habit that makes main always deployable.

Push your branches regularly. A branch that only exists on your laptop is lost if your laptop dies. Push feature branches daily even if they're not ready to merge.

Check git status before destructive operations. Before reset --hard, clean -fd, or anything that might lose uncommitted changes, run git status. Take two seconds to read what you'd be throwing away.

Learn git reflog's address by heart. When something goes wrong, git reflog is almost always the first thing to check. It should be a reflex.

The Freedom That Comes From Understanding

The relationship most developers have with Git is one of cautious navigation — running commands that seem to work, avoiding the ones that seem dangerous, hoping nothing goes wrong.

The relationship you can have with Git is entirely different: active, confident, fearless. You run experiments knowing you can undo them. You rebase complex histories knowing you can restore the original with reflog. You delete branches knowing you can recover them from the object store. You reset commits knowing you can find them again.

That confidence changes how you work. You try bolder refactors because you know you can undo them. You explore unfamiliar parts of a codebase more freely because you can revert your exploration. You commit half-finished thoughts because you'll clean them up before the PR.

Git was built to make working with code feel safe. Once you understand it — really understand it, not just the commands but the model — that's exactly what it feels like.

The Complete Recovery Toolkit

# See every position HEAD has been at
git reflog

# Recover from a bad reset
git reset --hard HEAD@{N}

# Recover a deleted branch
git switch -c recovered-branch <hash-from-reflog>

# Undo a commit on shared branch (safe)
git revert HEAD

# Stash and restore work in progress
git stash push -m "description"
git stash pop

# Cherry-pick a specific commit
git cherry-pick <commit-hash>

# Binary search for a breaking commit
git bisect start
git bisect bad
git bisect good <known-good-hash>
git bisect run <test-command>
git bisect reset

# Run two branches simultaneously
git worktree add ../folder branch-name
git worktree remove ../folder

# Dry run before destructive operations
git clean -nd   # Preview what clean would delete
git reset --dry-run  # Not all Git versions support this; use status instead

← Part 4: Collaboration That Doesn't Create Chaos | Back to the Series Hub →

If this was useful, I turned the whole series into a 23-page PDF reference — checklists, hook templates, 80+ commands, reflog & bisect deep-dives, and a recovery playbook for 12 real emergencies.

Git Mastery Field Guide →

If this was useful, I turned the whole series into a 23-page PDF reference — checklists, hook templates, 80+ commands, reflog & bisect deep-dives, and a recovery playbook for 12 real emergencies.

Git Mastery Field Guide →

Collaboration That Doesn't Create Chaos

Shakil Alam — Sun, 15 Mar 2026 08:27:38 +0000

Part 4 of the Git Mastery Series
← Part 3: Branching Without Fear | Part 5: Git as Your Safety Net →

The first time you work on a shared repository with a team, Git feels entirely different. Suddenly the stakes are higher. You're not just managing your own work — you're touching code other people depend on, potentially rewriting history they've already pulled, or introducing changes that conflict with what someone else spent the day building.

Most Git problems on teams aren't technical. They're coordination problems that Git reflects back at you. The branch with 47 commits that's been open for three weeks. The merge that had 12 conflicts because two developers refactored the same file in parallel without knowing it. The force push that rewrote history on a shared branch and caused chaos for the rest of the team.

These situations all had a Git solution. But the solution was mostly about communication and process, not commands.

The Pull Request Isn't a Formality

A lot of teams treat pull requests as a checkbox — open it, someone clicks "approve," merge it. The code review is cursory. Feedback is minimal. "LGTM" appears within minutes on PRs that contain hundreds of lines of changes.

This is a missed opportunity. A pull request is the best point in the entire development process to catch problems — not just bugs, but design issues, architectural drift, security vulnerabilities, and code that technically works but will be unmaintainable in six months.

The problem is that most PRs aren't designed to be reviewed. They're designed to be merged.

What a reviewable PR looks like:

The title is specific: feat(checkout): add Razorpay payment gateway integration not payment stuff.

There's a description that answers: what does this PR do, why was it needed, how should the reviewer test it, and is there anything specific you want feedback on?

The commits tell the story of what was built — not just what you happened to type while building it. (This is why Part 2 matters.)

The PR is a size a human can actually review in 30–60 minutes. If it's 2,000 lines of diff, it's not a PR — it's a project. Break it up.

## What does this PR do?
Integrates Razorpay as a payment gateway option for checkout.
Previously we only supported Stripe.

## Why?
Multiple users in India reported Stripe charges in USD are
causing currency conversion frustration. Razorpay handles INR natively.

## How to test
1. Set RAZORPAY_KEY_ID and RAZORPAY_KEY_SECRET in .env (test keys in 1Password)
2. Add an item to cart and proceed to checkout
3. Select "Pay with Razorpay" 
4. Use test card: 4111 1111 1111 1111

## Notes for reviewer
The webhook handling in PaymentController is the most complex part.
I'd appreciate extra eyes on lines 87-134.

Closes #312

That takes five minutes to write and saves the reviewer twenty minutes of confusion. It also forces you to think about whether what you built is actually what was needed.

Keeping Your Branch Current Without Creating a Mess

The longer your feature branch lives, the further it drifts from main. Merge conflicts get worse the longer you wait. Changes other people made become harder to reconcile.

The habit: update your branch from main regularly. Every day, or whenever something relevant lands on main.

Two ways to do this:

Rebase onto main (preferred for feature branches):

git switch feature/my-feature
git fetch origin
git rebase origin/main

Your commits get replayed on top of the latest main. Your branch history stays clean. When you eventually merge, it's a fast-forward. No merge commit, no noise.

Merge main into your branch (simpler but messier):

git switch feature/my-feature
git merge main

This creates a merge commit on your feature branch every time you do it. If you update three times before merging, you have three merge commits on a feature branch. The history becomes confusing. Prefer rebase for this specific operation.

One important rule: if your branch is shared with other developers — if someone else has pulled it and is working from it — don't rebase. Rebasing rewrites commit hashes, which means anyone who has your old commits now has conflicts with the new ones. On shared branches, merge instead.

Protected Branches and Why "No Direct Push to Main" Is a Feature

Most teams eventually learn this lesson the hard way: a direct push to main that breaks the build on a Friday afternoon.

Branch protection rules exist to make mistakes hard by default:

Require pull requests before merging
Require at least one approval
Require CI to pass before merging
Prevent force pushes on main

Setting these up on GitHub or GitLab takes five minutes and prevents a category of incidents that are otherwise entirely predictable.

Settings → Branches → Branch protection rules

The mindset here: protection rules aren't about distrust. They're about creating a system where good practices are automatic and mistakes require deliberate effort to make. A team that needs protection rules isn't a bad team — it's a team that understands that humans make mistakes under pressure and has designed for that.

Force Push: When It's Right and When It's Wrong

git push --force has a reputation as a dangerous command, and it deserves it in the wrong context. But in the right context, it's completely normal.

When force push is right: after rebasing or amending commits on your own feature branch that nobody else has pulled. You've rewritten local history and need to update the remote to match:

git rebase -i HEAD~3  # Clean up commits
git push --force-with-lease origin feature/my-feature

Note --force-with-lease instead of --force. This is strictly safer — it refuses to force push if someone else has pushed to the branch since you last fetched. It protects against accidentally overwriting someone else's work on a shared branch.

When force push is wrong: on main, develop, or any branch other people are working from. Rewriting shared history is how you get frantic Slack messages and conflicts everyone has to manually resolve.

Simple rule: force push only on branches you own. Never on shared branches. If you've accidentally pushed something to a shared branch that needs to be removed — bad credentials, sensitive data, large binary files — have a team conversation before force pushing.

Git Hooks: Automation That Enforces Standards

Git hooks are scripts that run automatically at specific points in the Git workflow. They're one of the most powerful and underused features for teams.

Useful hooks for shared work:

pre-commit: runs before a commit is finalized. Use it to run linters, check for debug statements, validate commit message format:

#!/bin/sh
# .git/hooks/pre-commit
npm run lint
if [ $? -ne 0 ]; then
  echo "Linting failed. Fix errors before committing."
  exit 1
fi

commit-msg: validates the commit message format:

#!/bin/sh
# .git/hooks/commit-msg
commit_regex='^(feat|fix|refactor|docs|test|chore|perf)(\(.+\))?: .{1,72}'
if ! grep -qE "$commit_regex" "$1"; then
  echo "Commit message doesn't follow Conventional Commits format."
  echo "Example: feat(auth): add OTP login"
  exit 1
fi

pre-push: runs before pushing to remote. Good for running tests:

#!/bin/sh
# .git/hooks/pre-push
npm test
if [ $? -ne 0 ]; then
  echo "Tests failed. Fix them before pushing."
  exit 1
fi

The problem with .git/hooks is that it's not committed to the repository — every developer has to set it up manually. For shared hooks, use a tool like Husky (JavaScript projects) or Lefthook (language-agnostic) that stores hooks in the repo and installs them automatically.

The mindset: hooks remove the "I forgot" category of mistakes. Nobody remembers to run the linter before every commit. A hook that does it automatically means the standard is enforced without depending on anyone's memory.

When History Goes Wrong on a Shared Branch

Sometimes, despite good practices, something bad lands on a shared branch. A commit with credentials. A merge that introduced a regression. A massive binary file that shouldn't have been committed.

Reverting vs resetting:

git revert creates a new commit that undoes the changes of a previous commit. It doesn't rewrite history — it adds to it. This is the safe option for shared branches:

# Undo the last commit while preserving history
git revert HEAD
git push origin main

# Undo a specific commit further back
git revert a3f8c9d
git push origin main

git reset moves the branch pointer backward, effectively removing commits from the visible history. This is only safe on branches you haven't shared:

# Undo last commit (keep changes in working dir)
git reset HEAD~1

# Undo last commit completely
git reset --hard HEAD~1

The rule: on shared branches, revert. On private branches, reset.

Tagging: The Commit History Entry Nobody Writes

Tags are a lightweight way to mark important points in history — releases, milestones, deployment checkpoints. Most teams skip them. The teams that use them find them invaluable for production debugging.

# Create a release tag
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

# Push all tags
git push origin --tags

# See all tags
git tag

# See what changed between releases
git diff v1.1.0 v1.2.0
git log v1.1.0..v1.2.0 --oneline

When something breaks in production, git diff v1.1.0 v1.2.0 shows you exactly what changed between the version that worked and the version that didn't. Without tags, you're guessing which commits were in which release.

The Collaboration Mindset

Working on a shared repository is a form of communication. Every commit, PR, and branch name is a message to your team. Code that works but is unreadable is a burden. A PR that can't be reviewed is a bottleneck. A force push on main is an interruption to everyone.

The developers who collaborate well with Git aren't the ones with the most commands memorized. They're the ones who think about how their work will land for everyone else. Small PRs that are easy to review. Clear commit messages that explain decisions. Branches that are cleaned up after merging. History that tells the story of how the product was built.

That history outlasts everyone on the team. Write it accordingly.

Quick Reference

# Update feature branch from main (clean)
git fetch origin
git rebase origin/main

# Force push safely after rebase
git push --force-with-lease origin feature/branch

# Undo a commit on a shared branch (safe)
git revert HEAD
git push origin main

# Create and push a release tag
git tag -a v1.2.0 -m "Release 1.2.0"
git push origin v1.2.0

# See what changed between releases
git diff v1.1.0 v1.2.0

# See commits not yet in main
git log main..feature/branch --oneline

# Check what you're about to push
git diff origin/main..HEAD

← Part 3: Branching Without Fear | Next: Part 5 — Git as Your Safety Net →

If this was useful, I turned the whole series into a 23-page PDF reference — checklists, hook templates, 80+ commands, reflog & bisect deep-dives, and a recovery playbook for 12 real emergencies.

Git Mastery Field Guide →

Branching Without Fear

Shakil Alam — Sun, 15 Mar 2026 08:27:02 +0000

Part 3 of the Git Mastery Series
← Part 2: Committing with Intention | Part 4: Collaboration That Doesn't Create Chaos →

There's a type of developer who avoids branches. They work directly on main, commit everything there, and nervously push every fifteen minutes so their work is "safe." When asked why they don't branch, they say some version of: "It's just me" or "Branches feel like extra steps" or "I always mess up the merge."

The irony is that branching is exactly what makes Git safe. It's the thing that lets you try something risky without touching working code. It's what lets you switch contexts instantly without losing your place. The developers who are most afraid of Git are often the ones least using the feature that would remove that fear.

What a Branch Is Letting You Do

From Part 1, you know a branch is just a pointer. But let's talk about what that means practically.

When you create a branch and switch to it, you're working in complete isolation. Whatever you commit doesn't touch main. If you decide the whole experiment was wrong, you delete the branch and it's gone. main never knew it existed.

git switch -c experiment/try-new-payment-flow
# ... write code, commit, test, realize it's a bad idea ...
git switch main
git branch -D experiment/try-new-payment-flow
# Gone. main is unchanged.

This is the mental model: a branch is a sandbox. Create one freely for every non-trivial piece of work — a feature, a fix, a refactor, even a quick experiment you're not sure about. The cost is near zero. The safety is real.

A Branching Strategy That Actually Works

There are entire books about branching strategies. GitFlow with its develop, release, hotfix, and feature branches. Trunk-based development. GitHub Flow. They all have tradeoffs.

Here's the one that works for most teams most of the time:

main          → production-ready code, always deployable
feature/*     → new features, branched from main
bugfix/*      → bug fixes, branched from main  
hotfix/*      → urgent fixes, branched from main, merged back immediately

That's it. No develop branch creating a second place to merge things. No release branches unless you genuinely need staged releases. Keep it flat until you have a specific reason not to.

Naming matters more than developers think. feature/user-login tells you everything. feat-login-new tells you something. johns-branch-v2 tells you nothing and will confuse someone three months from now (including John).

# Names that communicate intent
git switch -c feature/razorpay-integration
git switch -c bugfix/cart-total-rounding-error
git switch -c hotfix/payment-crash-on-null-address
git switch -c refactor/extract-notification-service

Merge vs Rebase: Stop Treating This as a Religion

The merge-vs-rebase debate has taken on an almost theological quality in some developer communities. Strong opinions, passionate defense, occasional contempt for the other side.

Here's the practical truth: they're different tools for different situations, and understanding what each one actually does makes the choice obvious.

Merge preserves the full history of how things happened. When you merge feature/login into main, Git creates a merge commit that has two parents — the tip of main and the tip of the feature branch. The history shows exactly when the branch was created and when it was merged. It's honest.

git switch main
git merge feature/login
# Creates a merge commit with two parents

Rebase replays your commits on top of another branch, creating new commits with the same changes but different parent hashes. The result looks like you wrote your feature on top of the latest main, even if main moved forward while you were working. The history is linear and clean. It's legible but slightly fictional.

git switch feature/login
git rebase main
# Replays your commits on top of current main
git switch main
git merge feature/login  # Now a fast-forward, no merge commit needed

When to use each:

Use merge when you're bringing a finished feature into a shared branch. The merge commit is useful — it marks exactly when the feature landed.

Use rebase when you're updating a feature branch to include recent changes from main. This keeps your branch current without a messy "Merge branch 'main' into feature/login" commit polluting the feature's history.

Use merge for public branches. Use rebase for your private, unpushed work. That's the rule that resolves 90% of the confusion.

The Fast-Forward and Why It Matters

When a branch hasn't diverged from its target — meaning main hasn't had any new commits since you branched off — Git can "fast-forward" instead of creating a merge commit. It just moves the pointer forward:

# main: A → B → C
# feature: A → B → C → D → E

git switch main
git merge feature
# Result: main: A → B → C → D → E (no merge commit)

This is why rebasing before merging produces clean history — after a rebase, your branch is always ahead of main with no divergence, so the merge is always a fast-forward.

If you want to force a merge commit even when a fast-forward is possible (to preserve the record that a branch existed), use --no-ff:

git merge --no-ff feature/login

Some teams do this for feature branches so every feature has a visible merge commit in history. Others prefer the clean linear history of fast-forwards. Both are defensible. The important thing is having a consistent team decision rather than random behavior.

Resolving Conflicts Without Panic

Merge conflicts have a reputation they don't deserve. They're not dangerous. They're just Git telling you: "Two people edited the same area of the same file and I don't know which version to keep. You decide."

That's it. Git is asking a question.

When you hit a conflict:

git merge feature/update-user-model
# CONFLICT (content): Merge conflict in src/User.php

Open src/User.php and you'll see conflict markers:

<<<<<<< HEAD
protected $fillable = ['name', 'email', 'phone'];
=======
protected $fillable = ['name', 'email', 'role'];
>>>>>>> feature/update-user-model

The section between <<<<<<< HEAD and ======= is what your current branch has. The section between ======= and >>>>>>> is what you're merging in. You need to edit this into what it should actually be:

protected $fillable = ['name', 'email', 'phone', 'role'];

Then:

git add src/User.php
git commit  # Complete the merge

Three things that make conflicts less painful:

Merge small, merge often. A branch that diverges for two weeks will have far more conflicts than one that diverges for two days. The longer you wait, the more painful the merge.

Use a visual merge tool. git mergetool opens a three-pane editor showing the base, your changes, and theirs. It's significantly easier to understand than raw conflict markers.

Talk to the other person first. The best way to resolve a conflict is to understand why both changes were made before deciding which to keep. A conflict is a conversation waiting to happen.

Deleting Branches: Stop Hoarding

Merged branches should be deleted. Not archived. Deleted.

A repository with 200 stale branches is a repository nobody understands. You can't tell which branches are active, which are abandoned, which are merged. The signal is lost in noise.

# Delete local branch (after merging)
git branch -d feature/login

# Delete remote branch
git push origin --delete feature/login

# See remote branches that no longer exist locally
git remote prune origin --dry-run

Most Git hosts (GitHub, GitLab, Bitbucket) offer "auto-delete branch on merge" in repository settings. Turn it on. Branches should be cheap to create and quick to discard — not collections you maintain.

The One Branch Habit That Changes Everything

Here's the habit that separates developers who love Git from developers who tolerate it: create a branch before you start anything, every time, even for small things.

A "quick fix" that turns into a three-hour debugging session is exactly when you need a branch. A "tiny refactor" that somehow requires touching six files is exactly when you need a branch. An "experimental change" you might want to revert is exactly when you need a branch.

The ten seconds to run git switch -c fix/whatever is worth it every single time. It creates a clean separation between "finished, working code" and "work in progress." It means main is always in a deployable state. It means you can abandon your work cleanly if something higher priority comes up.

Once this habit becomes automatic, Git starts feeling like a safety net rather than a source of anxiety. Because that's what it is.

Quick Reference

# Create and switch to a new branch
git switch -c feature/branch-name

# Switch to existing branch
git switch branch-name

# List all branches (including remote)
git branch -a

# Merge a branch into current
git merge branch-name

# Rebase current branch onto another
git rebase main

# Delete merged local branch
git branch -d branch-name

# Force delete unmerged branch
git branch -D branch-name

# Delete remote branch
git push origin --delete branch-name

# See branches with last commit
git branch -v

# See which branches are merged into main
git branch --merged main

← Part 2: Committing with Intention | Next: Part 4 — Collaboration That Doesn't Create Chaos →

If this was useful, I turned the whole series into a 23-page PDF reference — checklists, hook templates, 80+ commands, reflog & bisect deep-dives, and a recovery playbook for 12 real emergencies.

Git Mastery Field Guide →

DEV Community: Shakil Alam

How We Implemented Content Security Policy (CSP) in Our Laravel App

What Content Security Policy Actually Does

What Is a Nonce?

The Naive Approach (and Why It Fails)

The Mindset Shift: Write CSP-Friendly Code

The Implementation

Step 1: Generate the Nonce and Share It

Step 2: Define the CSP Policy

Deep Dive: style-src, style-src-elem, and style-src-attr

Step 3: Use the Nonce in Blade

Step 4: Add the Rest of the Security Header Stack

Step 5: Register the Middleware

CSP Violation Reporting — Your Early Warning System 🚨

What a Violation Report Looks Like

The Route

The Controller

Log Channels

The Modern Report-To Header

Pre-Enforcement Checklist

Deploy Safely: Start in Report-Only Mode

What We'd Do Differently

The Result

Get the Quick Reference PDF

Frequently Asked Questions

Laravel External API Reliability: When Their System Goes Down

What you will build

The problem with try-catch at the call site

The sync trait: making resilience decisions visible

Why two timeout values?

Tracing failures across systems with a request ID

shouldContinueWithoutSync() — a business decision in code

What a complete model looks like

Handling updates across multiple endpoints

What happens to failed syncs

Approach 1: Queued delayed retry (start here)

Approach 2: Scheduled reconciliation (add after you've seen one outage)

The edge case: what if the local write fails?

What this does not solve

Where you end up

Before you ship — checklist

What this series built

Further reading

Secure File Uploads: Seven Checks and Why Each One Exists

What you will build

The validation pipeline

The middleware

Check 1 — Filename sanitization

Checks 2 and 3 — Extension and client MIME allowlisting

Check 4 — Server-side MIME detection

Check 5 — Cross-checking extension against detected MIME

Check 6 — Size limits

Check 7 — Magic bytes

SVG: the format that deserves extra attention

Always generate a unique name before saving

Where files live after validation

Registering the middleware

Before you ship — checklist

Laravel Queue Architecture: Designing Background Work That Holds Up

What you will learn

The mental model: a queue is not a to-do list

What to put in a job constructor — and what not to

The single responsibility principle, applied to jobs

Queue topology: the decision nobody makes until they have to

Retry strategy: not all failures are equal

Transient failures

Rate-limited or service-down failures

Permanent failures

Processing large backlogs: the Artisan command pattern

Atomic file operations: designing for crashes

The shape of a well-designed job

Before you ship — checklist

The Audit Trail: Building a System That Remembers

What you will build

What an audit trail actually needs to prove

The request ID: one thread through every log

Slow queries: while you are here, add this

The model change logger

File-based logs and the folder segmentation problem

Masking sensitive fields

Deep Dive: `style-src`, `style-src-elem`, and `style-src-attr`

`shouldContinueWithoutSync()` — a business decision in code