README

Secure file upload validation for Laravel — Protects your application from malicious file uploads using magic bytes detection, PHP code scanning, and comprehensive security checks.

📖 Full Documentation | 🚀 Quick Start | 🔒 Security

Features

• 🛡️ All-in-One Security — Single validation rule runs all checks
• 🔍 Magic Bytes Detection — Real MIME type validation (70+ formats)
• ⚠️ Malware Scanning — Detects PHP code, XSS, JavaScript in PDFs
• 🖼️ Image Security — EXIF metadata scanning, GPS detection
• 📄 PDF Protection — JavaScript and dangerous actions detection
• 📏 Size Validation — Image dimensions and PDF page limits
• 🚫 Auto-Blocking — Executables and scripts blocked by default
• 📊 Security Logging — Comprehensive threat monitoring
• ⚙️ Fully Customizable — Fluent API and config-based control

Installation

Install via Composer:

composer require abdian/laravel-safeguard

The package will auto-register via Laravel's package discovery.

Quick Start

Basic Usage (Recommended)

Use the safeguard rule for comprehensive security:

use Illuminate\Http\Request;

public function upload(Request $request)
{
    $request->validate([
        'file' => 'required|safeguard',
    ]);

    // File is safe to process
}

This single rule performs:

• ✅ Real MIME type detection
• ✅ PHP code scanning
• ✅ XSS vulnerability detection
• ✅ Image metadata analysis
• ✅ PDF security scanning

Advanced Configuration

use Abdian\LaravelSafeguard\Rules\Safeguard;

$request->validate([
    // Images only with security
    'avatar' => ['required', (new Safeguard())
        ->imagesOnly()
        ->maxDimensions(1920, 1080)
        ->blockGps()
        ->stripMetadata()
    ],

    // PDFs with restrictions
    'document' => ['required', (new Safeguard())
        ->pdfsOnly()
        ->maxPages(50)
        ->blockJavaScript()
    ],
]);

Individual Security Rules

For granular control, use specific validation rules:

$request->validate([
    'avatar' => 'required|safeguard_mime:image/jpeg,image/png|safeguard_image',
    'icon' => 'required|safeguard_svg',
    'document' => 'required|safeguard_pdf|safeguard_pages:1,10',
]);

Documentation

• Installation Guide — Complete installation instructions
• Quick Start Guide — Get started in 5 minutes
• Validation Rules — All available rules and options
• Configuration — Customize behavior and settings
• Customization — Add file types and patterns
• Logging & Monitoring — Security event logging
• Examples — Real-world usage examples
• Advanced Usage — Complex scenarios and tips

Requirements

• PHP 8.1 or higher
• Laravel 10.x, 11.x, or 12.x
• fileinfo PHP extension (enabled by default)

Security

Laravel Safeguard helps protect against:

• File Type Spoofing — Detects real file type via magic bytes
• PHP Code Injection — Scans for malicious PHP code in uploads
• XSS Attacks — Detects script tags and event handlers in SVG
• Metadata Exploits — Scans image EXIF for hidden code
• PDF Malware — Detects JavaScript and dangerous actions
• Executable Files — Auto-blocks .exe, scripts, and binaries

For security vulnerabilities, please email security@example.com instead of using the issue tracker.

License

Laravel Safeguard is open-sourced software licensed under the MIT license.

Links

• Documentation
• GitHub Repository
• Issue Tracker
• Changelog
• Contributing Guide

Made with ❤️ for the Laravel community