PHPackages                             fomadev/sfupload - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. fomadev/sfupload

ActiveLibrary[HTTP & Networking](/categories/http)

fomadev/sfupload
================

Bibliothèque PHP 8.1+ sécurisée et légère pour l'upload de fichiers via PSR-7. Validation stricte, configuration flexible, zéro dépendance externe.

1.2.0(4mo ago)00MITPHPPHP >=8.1

Since Jan 1Pushed 4mo agoCompare

[ Source](https://github.com/fomadev/sfupload)[ Packagist](https://packagist.org/packages/fomadev/sfupload)[ RSS](/packages/fomadev-sfupload/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (2)Versions (3)Used By (0)

sfupload 🛡️
===========

[](#sfupload-️)

[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![PHP Version](https://camo.githubusercontent.com/3a551e6c37f4d5451a70062155ccea8dec2f6eb8a55eb1a1410a5166fce4b020/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344253230382e312d626c75652e737667)](https://php.net)[![Version](https://camo.githubusercontent.com/1dd20ab7897e2afa95b7178fe0467c6d03503bfdea3890055c130775e1e12275/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e322e302d677265656e2e737667)](https://camo.githubusercontent.com/1dd20ab7897e2afa95b7178fe0467c6d03503bfdea3890055c130775e1e12275/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e322e302d677265656e2e737667)

**sfupload** est une bibliothèque PHP 8.1+ légère, modulaire et ultra-sécurisée pour gérer les téléchargements de fichiers. Elle repose sur l'interface standard **PSR-7** pour garantir une compatibilité maximale avec tous les frameworks modernes (Symfony, Laravel, Slim, etc.).

🌟 Pourquoi choisir sfupload ?
-----------------------------

[](#-pourquoi-choisir-sfupload-)

L'upload de fichiers est l'une des plus grandes failles de sécurité en développement web. **sfupload** applique les meilleures pratiques par défaut :

✅ **Vérification MIME stricte** : Détecte le vrai type de fichier via Magic Bytes (`finfo`), pas l'extension
✅ **Renommage cryptographique** : Génère des noms imprévisibles avec `random_bytes()`
✅ **Architecture modulaire** : Séparez validation, stockage et logique métier
✅ **Configuration flexible** : Configurations prédéfinies (images, documents) ou personnalisées
✅ **Zéro dépendance externe** : Utilise uniquement PSR-7 et le cœur PHP
✅ **API simple** : 5 lignes pour un upload sécurisé

🚀 Installation
--------------

[](#-installation)

```
composer require fomadev/sfupload
```

📖 Usage rapide
--------------

[](#-usage-rapide)

### Exemple basique (5 lignes)

[](#exemple-basique-5-lignes)

```
use SfUpload\Uploader;
use SfUpload\Storage\LocalStorage;
use SfUpload\Validation\Validator;
use SfUpload\Validation\MimeTypeConstraint;
use SfUpload\Bridge\UploadedFileAdapter;

// Configuration simple
$storage = new LocalStorage(__DIR__ . '/uploads', true);
$mimeConstraint = new MimeTypeConstraint(['image/jpeg', 'image/png']);
$validator = new Validator(5 * 1024 * 1024, $mimeConstraint); // 5 Mo max
$uploader = new Uploader($storage, $validator);

// Upload sécurisé
try {
    $fileInfo = $uploader->upload(UploadedFileAdapter::fromGlobal($_FILES['file']));
    echo "Succès ! Fichier: " . $fileInfo->savedName;
    echo "Taille: " . $fileInfo->getFormattedSize(); // Utilise FileHelper
} catch (\SfUpload\Exception\UploadException $e) {
    echo "Erreur: " . $e->getMessage();
}
```

### Avec configuration prédéfinie

[](#avec-configuration-prédéfinie)

```
use SfUpload\Configuration\UploadConfig;

// Configuration prédéfinie pour images uniquement
$config = UploadConfig::imageOnly(10 * 1024 * 1024); // 10 Mo

$storage = new LocalStorage($uploadDir, true);
$mimeConstraint = new MimeTypeConstraint($config->getAllowedMimes());
$validator = new Validator($config->getMaxSize(), $mimeConstraint);
$uploader = new Uploader($storage, $validator);
```

### Configuration personnalisée

[](#configuration-personnalisée)

```
$config = new UploadConfig(
    maxSize: 20 * 1024 * 1024, // 20 Mo
    allowedMimes: ['application/pdf', 'application/msword'],
    createMissingDir: true
);
```

🎯 Configurations prédéfinies
----------------------------

[](#-configurations-prédéfinies)

PresetTypesTaille max`UploadConfig::imageOnly()`JPEG, PNG, WebP, GIF10 Mo`UploadConfig::documentOnly()`PDF, Word, Excel20 Mo`UploadConfig::any()`Tous50 Mo📚 API Complète
--------------

[](#-api-complète)

### Classe `Uploader`

[](#classe-uploader)

```
$uploader->upload(UploadedFileInterface $file): FileInfo
```

### Objet `FileInfo` retourné

[](#objet-fileinfo-retourné)

```
$fileInfo->originalName;        // Nom original du fichier
$fileInfo->savedName;           // Nom sécurisé généré
$fileInfo->fullPath;            // Chemin complet du fichier
$fileInfo->mimeType;            // Type MIME détecté
$fileInfo->size;                // Taille en bytes

// Méthodes utiles
$fileInfo->getExtension();      // Extension du fichier
$fileInfo->getFileType();       // Type: image, document, etc.
$fileInfo->getFormattedSize();  // Taille lisible: "5.2 MB"
$fileInfo->exists();            // Vérifie l'existence du fichier
$fileInfo->getStats();          // Retourne les stats du fichier
```

### Classe `UploadConfig`

[](#classe-uploadconfig)

```
$config = new UploadConfig($maxSize, $mimes, $createDir);

$config->getMaxSize();
$config->getAllowedMimes();
$config->shouldCreateMissingDir();

// Fluent interface
$config->setMaxSize(10 * 1024 * 1024)->setAllowedMimes([...]);
```

### Classe `FileHelper`

[](#classe-filehelper)

```
FileHelper::formatFileSize(5242880);              // "5 MB"
FileHelper::getFileType('image.jpg');             // "image"
FileHelper::sanitizePath($userPath);              // Sécurise le chemin
FileHelper::fileExists($filePath);                // Vérifie l'existence
FileHelper::getFileStats($filePath);              // Retourne les stats
```

📂 Structure du projet
---------------------

[](#-structure-du-projet)

```
src/
├── Bridge/                      # Adaptateurs PSR-7
│   └── UploadedFileAdapter.php  # Convertisseur $_FILES → PSR-7
├── Configuration/               # Gestion de la configuration
│   └── UploadConfig.php         # Configuration centralisée
├── Exception/                   # Exceptions personnalisées
│   └── UploadException.php
├── Storage/                     # Moteur de stockage
│   └── LocalStorage.php
├── Utility/                     # Utilitaires
│   └── FileHelper.php           # Helpers pour les fichiers
├── Validation/                  # Moteur de validation
│   ├── Validator.php
│   └── MimeTypeConstraint.php
├── FileInfo.php                 # DTO pour les infos du fichier
└── Uploader.php                 # Façade principale

```

🔐 Sécurité
----------

[](#-sécurité)

### Recommandations

[](#recommandations)

1. **Placez le dossier d'upload en dehors du public**

    ```
    // ❌ Mauvais
    $storage = new LocalStorage(__DIR__ . '/public/uploads');

    // ✅ Bon
    $storage = new LocalStorage(__DIR__ . '/../private/uploads', true);
    ```
2. **Configurez votre serveur pour interdire l'exécution de scripts**

    ```
    # .htaccess

        Deny from all

    ```
3. **Validez strictement les types MIME**

    ```
    $mimeConstraint = new MimeTypeConstraint(['image/jpeg']);
    // Détecte les vrais types, pas les extensions trompeuses
    ```

📋 Exemples inclus
-----------------

[](#-exemples-inclus)

### 1. Simple (`examples/simple.php`)

[](#1-simple-examplessimplephp)

Exemple basique avec galerie des fichiers récents

### 2. Images avancées (`examples/images-advanced.php`)

[](#2-images-avancées-examplesimages-advancedphp)

Upload d'images avec configuration prédéfinie

### 3. API Endpoint (`examples/api-endpoint.php`)

[](#3-api-endpoint-examplesapi-endpointphp)

Endpoint AJAX qui retourne JSON

### 4. Multi-type (`examples/multi-type.php`)

[](#4-multi-type-examplesmulti-typephp)

Gestion de plusieurs types de fichiers avec onglets

🔄 Changelog
-----------

[](#-changelog)

### 1.2.0 (Janvier 2026) ✨ Nouvelle version

[](#120-janvier-2026--nouvelle-version)

- ✨ Nouvelle classe `UploadConfig` pour configurations prédéfinies
- ✨ Nouvelle classe `FileHelper` avec utilitaires
- ✨ Nouvelle classe `UploadedFileAdapter` pour PSR-7
- 🎨 Méthodes utiles dans `FileInfo` (getFormattedSize, getFileType, etc.)
- 📚 4 exemples complets et documentés
- 🔧 Support de création automatique des dossiers

### 1.0.0

[](#100)

- Version initiale de la bibliothèque

🧪 Tests
-------

[](#-tests)

```
composer test
```

📄 Licence
---------

[](#-licence)

Ce projet est sous licence **MIT**. Voir le fichier [LICENSE](LICENSE) pour plus de détails.

🤝 Contribution
--------------

[](#-contribution)

Les contributions sont bienvenues ! N'hésitez pas à :

- Signaler des bugs
- Proposer des améliorations
- Soumettre des pull requests

📞 Support
---------

[](#-support)

Pour toute question, créez une [GitHub issue](https://github.com/fomadev/sfupload/issues).

---

Développé avec ❤️ par **fomadev**

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance76

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~8 days

Total

2

Last Release

128d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/57036d2d8261dc55c6e40f9170ed44d854d65a6795d792124936a5d39a1ba656?d=identicon)[fomadev](/maintainers/fomadev)

---

Top Contributors

[![fordimalanda](https://avatars.githubusercontent.com/u/131183274?v=4)](https://github.com/fordimalanda "fordimalanda (24 commits)")

---

Tags

backenddrag-and-dropfile-uploadhacktoberfestmedia-manageropen-sourcephpstorageuploaderpsr-7validationsecurityfileuploadphp8

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/fomadev-sfupload/health.svg)

```
[![Health](https://phpackages.com/badges/fomadev-sfupload/health.svg)](https://phpackages.com/packages/fomadev-sfupload)
```

###  Alternatives

[siriusphp/upload

Framework agnostic upload library

228570.4k7](/packages/siriusphp-upload)[league/uri-interfaces

Common tools for parsing and resolving RFC3987/RFC3986 URI

536204.9M23](/packages/league-uri-interfaces)[hkarlstrom/openapi-validation-middleware

PSR-7 and PSR-15 OpenAPI Validation Middleware

95198.8k1](/packages/hkarlstrom-openapi-validation-middleware)[phpro/http-tools

HTTP tools for developing more consistent HTTP implementations.

28137.8k](/packages/phpro-http-tools)[mezzio/mezzio-authentication-oauth2

OAuth2 (server) authentication middleware for Mezzio and PSR-7 applications.

28483.0k2](/packages/mezzio-mezzio-authentication-oauth2)[mezzio/mezzio-authentication

Authentication middleware for Mezzio and PSR-7 applications

121.6M26](/packages/mezzio-mezzio-authentication)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)