README

Validation défensive de fichiers uploadés pour PHP 8.1+, sans déplacer ni stocker les fichiers. Le cœur ne dépend d’aucun framework et des intégrations optionnelles sont fournies pour Laravel et Symfony.

Ce package est développé et maintenu par IT EMPOWER SOLUTIONS, société spécialisée dans la conception, la sécurisation et l’accompagnement de solutions web.

Fonctionnalités

limite de taille vérifiée sur le fichier réel ;
liste blanche d’extensions ;
détection MIME réelle avec finfo ;
correspondance stricte extension/MIME ;
blocage d’extensions, types MIME et signatures exécutables ;
détection des doubles extensions dangereuses (facture.php.jpg) ;
génération de noms aléatoires sûrs avec random_bytes ;
contrôle des dimensions et du nombre de pixels des images ;
SVG désactivé par défaut et inspection de DOCTYPE, ENTITY, scripts, événements, URI JavaScript, data URI et ressources distantes lorsqu’il est activé ;
résultat typé avec codes d’erreur et API validate() / assert() ;
prise en charge directe du format $_FILES.

Le package ne déplace jamais un fichier uploadé. La décision de stockage, le chemin final, les permissions et la politique de conservation restent sous le contrôle de l’application.

Installation

composer require it-empower-solutions/secure-upload

Prérequis : PHP 8.1 ou supérieur et l’extension fileinfo. L’extension GD est recommandée pour garantir l’inspection des images matricielles dans tous les environnements.

Utilisation en PHP

use ItEmpower\SecureUpload\UploadValidator;

$validator = new UploadValidator([
    'max_size' => 5 * 1024 * 1024,
    'allowed_extensions' => ['jpg', 'jpeg', 'png', 'pdf'],
]);

$result = $validator->validateUploadedFile($_FILES['document'] ?? []);

if (!$result->isValid()) {
    foreach ($result->errors as $error) {
        echo "{$error->code}: {$error->message}\n";
    }
} else {
    echo $result->safeFilename;
    // Déplacez ou stockez vous-même le fichier après validation.
}

Pour un fichier temporaire déjà identifié :

$result = $validator->validate(
    path: '/tmp/php-upload',
    originalName: 'rapport.pdf',
    declaredSize: 123456,
);

declaredSize est optionnel. S’il est fourni, il est comparé à la taille réellement lue sur disque.

Validation avec exception

use ItEmpower\SecureUpload\Exception\UploadValidationException;

try {
    $result = $validator->assert('/tmp/php-upload', 'rapport.pdf');
} catch (UploadValidationException $exception) {
    foreach ($exception->result->errors as $error) {
        // Journaliser ou retourner une réponse adaptée.
    }
}

Générer uniquement un nom sûr

$filename = $validator->generateSafeFilename('pdf');
// Exemple : 19ee91477fbb6a8b385ce4e23b42f021.pdf

Le nom d’origine n’est jamais réutilisé. Conservez-le uniquement comme métadonnée après l’avoir échappé pour le contexte d’affichage.

Configuration

use ItEmpower\SecureUpload\UploadConfig;
use ItEmpower\SecureUpload\UploadValidator;

$validator = new UploadValidator(new UploadConfig(
    maxSize: 10 * 1024 * 1024,
    allowedExtensions: ['jpg', 'jpeg', 'png', 'pdf'],
    mimeTypes: UploadConfig::DEFAULT_MIME_TYPES,
    maxImageWidth: 10_000,
    maxImageHeight: 10_000,
    maxImagePixels: 40_000_000,
    randomNameBytes: 16,
    allowSvg: false,
));

Si vous ajoutez une extension, déclarez aussi ses types MIME acceptés dans mimeTypes. Une extension sans correspondance MIME est refusée.

SVG

Les SVG sont des documents actifs et restent interdits par défaut. Pour les accepter :

$validator = new UploadValidator([
    'allowed_extensions' => ['svg'],
    'allow_svg' => true,
]);

L’inspection intégrée rejette les principales constructions actives et les chargements externes. Elle constitue une barrière défensive, pas un moteur complet de nettoyage XML/CSS. Pour afficher des SVG fournis par des tiers, servez-les depuis un domaine isolé, avec Content-Disposition: attachment lorsque l’affichage n’est pas nécessaire, une CSP restrictive et X-Content-Type-Options: nosniff.

Laravel

L’auto-discovery enregistre le ServiceProvider et la façade SecureUpload. Publiez la configuration :

php artisan vendor:publish --tag=secure-upload-config

Puis utilisez l’injection :

use Illuminate\Http\Request;
use ItEmpower\SecureUpload\UploadValidator;

public function store(Request $request, UploadValidator $validator)
{
    $file = $request->file('document');

    $result = $validator->assert(
        $file->getPathname(),
        $file->getClientOriginalName(),
        $file->getSize(),
    );

    return ['safe_filename' => $result->safeFilename];
}

Ou la façade :

use ItEmpower\SecureUpload\Framework\Laravel\Facades\SecureUpload;

$result = SecureUpload::validate($path, $originalName, $size);

Symfony

Installez les composants nécessaires à l’intégration :

composer require symfony/http-kernel symfony/dependency-injection symfony/config

Enregistrez le bundle si Symfony Flex ne le fait pas :

// config/bundles.php
return [
    ItEmpower\SecureUpload\Framework\Symfony\ItEmpowerSecureUploadBundle::class => ['all' => true],
];

Configuration :

# config/packages/it_empower_secure_upload.yaml
it_empower_secure_upload:
    max_size: 10485760
    allowed_extensions: [jpg, jpeg, png, pdf]
    max_image_width: 10000
    max_image_height: 10000
    max_image_pixels: 40000000
    allow_svg: false

UploadValidator est autowirable. Le service public it_empower_secure_upload.validator est aussi disponible.

Codes d’erreur principaux

file_unreadable, size_unavailable, file_too_large, size_mismatch ;
extension_missing, extension_not_allowed, double_extension ;
executable_extension, executable_mime, executable_content ;
mime_unavailable, mime_mismatch ;
image_invalid, image_dimensions_exceeded ;
svg_not_allowed, svg_invalid, svg_doctype, svg_entity, svg_script, svg_event_handler, svg_javascript, svg_external_uri, svg_css_url ;
upload_error.

Recommandations de sécurité

La validation d’un upload doit être complétée par une défense en profondeur :

stocker hors de la racine web lorsque possible ;
ne jamais exécuter les fichiers déposés et désactiver les interpréteurs dans le répertoire de stockage ;
imposer un nom généré et une extension validée ;
servir un Content-Type contrôlé et X-Content-Type-Options: nosniff ;
appliquer authentification, autorisation, quotas, journalisation et analyse antivirus selon le risque ;
réencoder les images lorsque le contexte l’exige ;
protéger les formulaires contre les requêtes forgées et limiter les délais d’upload.

Pour un audit ou une intégration adaptée à votre contexte, contactez IT EMPOWER SOLUTIONS à contact@it-empower.com.

Exemples et tests

Le dossier examples contient des exemples PHP, Laravel et Symfony complets. Pour exécuter la suite :

composer install
vendor/bin/phpunit

Licence

MIT. Voir LICENSE.

it-empower-solutions / secure-upload

Maintainers

Package info

Statistics

Security