Laravel Image Sanitize Documentation

Introduction

Laravel Image Sanitize is a small Laravel middleware for image upload flows. It scans uploaded image files for suspicious payload markers such as PHP code or PHAR references, and when detected, re-encodes the image through Intervention Image to strip embedded payload content.

The package is intentionally narrow: detect suspicious image uploads, rewrite unsafe image contents, and keep the surrounding Laravel validation and storage decisions in your application.

Installation

Install the package with Composer:

bash

composer require laravel-at/laravel-image-sanitize

Basic Usage

Attach the middleware directly to upload routes that accept image files.

php

use App\Http\Controllers\FileController;
use LaravelAt\ImageSanitize\ImageSanitizeMiddleware;

Route::post('/files', [FileController::class, 'upload'])
    ->name('file.upload')
    ->middleware(ImageSanitizeMiddleware::class);

Middleware Alias

In Laravel 12 and 13, you can register a readable middleware alias in bootstrap/app.php.

php

use Illuminate\Foundation\Configuration\Middleware;
use LaravelAt\ImageSanitize\ImageSanitizeMiddleware;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->alias([
        'image-sanitize' => ImageSanitizeMiddleware::class,
    ]);
})

Then use the alias on your route:

php

Route::post('/files', [FileController::class, 'upload'])
    ->name('file.upload')
    ->middleware('image-sanitize');

Configuration

Publish the configuration file when you need to adjust allowed MIME types, detection patterns, image driver, quality, orientation handling, animation decoding, or metadata stripping.

bash

php artisan vendor:publish --tag=image-sanitize-config

The default configuration is deliberately compact:

php

return [
    'allowed_mime_types' => [
        'image/jpeg',
        'image/png',
        'image/gif',
        'image/bmp',
        'image/webp',
    ],

    'patterns' => [
        '<?php',
        'phar',
    ],

    'driver' => \Intervention\Image\Drivers\Gd\Driver::class,
    'quality' => 100,
    'auto_orientation' => true,
    'decode_animation' => true,
    'strip_metadata' => true,
];

Direct Usage

You can call the sanitizer directly when you are handling image bytes outside the middleware flow.

php

if (ImageSanitize::detect($contents)) {
    $contents = (string) ImageSanitize::sanitize($contents);
}

How It Works

1 The middleware inspects uploaded image files that match the configured MIME type allow-list.
2 File contents are scanned for configured suspicious payload markers such as PHP open tags and PHAR references.
3 When a suspicious marker is detected, the image is decoded and re-encoded with Intervention Image.
4 The rewritten image content replaces the original upload content before your controller continues.

Security Notes

This package is defense-in-depth for image upload flows.
It should complement Laravel validation, MIME checks, storage outside public execution paths, and normal upload security practices.
SVG is intentionally not supported by default.
The package rewrites detected images by decoding and re-encoding them with Intervention Image.

Testing

Run the package test suite with Composer:

bash

composer test

Changelog

Release notes and version history live in the package repository. Check the GitHub releases for published changes.

Credits

Made by

Logo by

Caneco