Charles
bd6d321ed7
- Backend PHP: architecture MVC avec API REST (upload, merge, preview, extract) - Frontend JavaScript: composants modulaires (arborescence, upload, themes, i18n) - Fonctionnalités: drag&drop, sélection exclusive, détection conflits, persistance état - Sécurité: validation stricte, isolation sessions, sanitization chemins - UI/UX: responsive, thèmes clair/sombre, multi-langue (FR/EN) - Documentation: README complet avec installation et utilisation
348 lines
11 KiB
Markdown
348 lines
11 KiB
Markdown
# FuZip
|
|
|
|
Application web interactive pour fusionner deux fichiers ZIP en choisissant précisément les fichiers à conserver de chaque côté.
|
|
|
|
|
|
|
|
|
|
|
|
## 🎯 Fonctionnalités
|
|
|
|
### Gestion des fichiers
|
|
- **Upload de ZIP** jusqu'à 500 MB par glisser-déposer ou sélection
|
|
- **Arborescence interactive** avec navigation hiérarchique
|
|
- **Détection automatique des conflits** entre les deux ZIP
|
|
- **Sélection exclusive** : un fichier en conflit ne peut être choisi que d'un seul côté
|
|
- **Recherche en temps réel** avec expansion automatique des dossiers
|
|
- **Prévisualisation** des fichiers texte directement dans l'interface
|
|
- **Téléchargement individuel** de fichiers depuis les ZIP
|
|
|
|
### Interface utilisateur
|
|
- **Interface responsive** adaptée mobile et desktop
|
|
- **Thèmes clair/sombre** avec sauvegarde de préférence
|
|
- **Multi-langue** (Français/Anglais)
|
|
- **Persistance d'état** : l'interface reste identique après fermeture/réouverture de l'onglet
|
|
- **Animations fluides** et retours visuels
|
|
|
|
### Sécurité
|
|
- **Validation stricte** des fichiers uploadés (magic bytes, MIME type)
|
|
- **Isolation par session** : chaque utilisateur a son propre espace
|
|
- **Sanitization** des noms de fichiers et chemins
|
|
- **Protection contre les extensions dangereuses**
|
|
- **Nettoyage automatique** des anciennes sessions (>24h)
|
|
- **Limites configurable** : taille de fichier, nombre de fichiers, profondeur d'arborescence
|
|
|
|
## 🛠️ Technologies utilisées
|
|
|
|
### Backend
|
|
- **PHP 7.4+** avec extensions :
|
|
- `ZipArchive` - Manipulation des fichiers ZIP
|
|
- `fileinfo` - Détection MIME type
|
|
- `session` - Gestion des sessions utilisateur
|
|
- `json` - Sérialisation des données
|
|
|
|
### Frontend
|
|
- **JavaScript ES6+** vanilla (aucun framework)
|
|
- **CSS3** avec variables CSS pour theming
|
|
- **SVG** pour les icônes
|
|
- **localStorage** pour persistance d'état
|
|
|
|
### Architecture
|
|
- **Pattern MVC** côté backend
|
|
- **Composants modulaires** côté frontend
|
|
- **API REST** pour communication client-serveur
|
|
- **Streaming** pour téléchargement des ZIP fusionnés
|
|
|
|
## 📋 Prérequis
|
|
|
|
- **Serveur web** : Apache 2.4+ ou Nginx 1.18+
|
|
- **PHP** : 7.4 ou supérieur
|
|
- **Extensions PHP requises** :
|
|
- `zip`
|
|
- `fileinfo`
|
|
- `session`
|
|
- `json`
|
|
- **Espace disque** : Au moins 2 GB pour les fichiers temporaires
|
|
- **Navigateur moderne** : Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
|
|
|
|
## 🚀 Installation
|
|
|
|
### 1. Cloner le dépôt
|
|
|
|
```bash
|
|
git clone https://github.com/votre-username/fuzip.git
|
|
cd fuzip
|
|
```
|
|
|
|
### 2. Configuration du serveur web
|
|
|
|
#### Apache
|
|
|
|
Créer un VirtualHost :
|
|
|
|
```apache
|
|
<VirtualHost *:80>
|
|
ServerName fuzip.local
|
|
DocumentRoot /path/to/fuzip
|
|
|
|
<Directory /path/to/fuzip>
|
|
Options -Indexes +FollowSymLinks
|
|
AllowOverride All
|
|
Require all granted
|
|
</Directory>
|
|
|
|
# Augmenter les limites pour gros fichiers
|
|
php_value upload_max_filesize 512M
|
|
php_value post_max_size 512M
|
|
php_value max_execution_time 300
|
|
php_value memory_limit 512M
|
|
</VirtualHost>
|
|
```
|
|
|
|
#### Nginx
|
|
|
|
Configuration pour Nginx :
|
|
|
|
```nginx
|
|
server {
|
|
listen 80;
|
|
server_name fuzip.local;
|
|
root /path/to/fuzip;
|
|
index index.php;
|
|
|
|
client_max_body_size 512M;
|
|
|
|
location / {
|
|
try_files $uri $uri/ /index.php?$query_string;
|
|
}
|
|
|
|
location ~ \.php$ {
|
|
fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
|
|
fastcgi_index index.php;
|
|
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
|
|
include fastcgi_params;
|
|
|
|
fastcgi_read_timeout 300;
|
|
fastcgi_buffer_size 128k;
|
|
fastcgi_buffers 4 256k;
|
|
}
|
|
|
|
location ~ /\. {
|
|
deny all;
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. Configuration PHP
|
|
|
|
Modifier `php.ini` pour autoriser les gros fichiers :
|
|
|
|
```ini
|
|
upload_max_filesize = 512M
|
|
post_max_size = 512M
|
|
max_execution_time = 300
|
|
memory_limit = 512M
|
|
max_input_time = 300
|
|
```
|
|
|
|
### 4. Permissions des dossiers
|
|
|
|
```bash
|
|
# Créer le dossier temporaire
|
|
mkdir -p temp/uploads
|
|
|
|
# Définir les permissions (Linux/Mac)
|
|
chmod 755 temp
|
|
chmod 755 temp/uploads
|
|
|
|
# Propriétaire www-data (Apache/Nginx)
|
|
chown -R www-data:www-data temp
|
|
|
|
# Ou utilisateur spécifique selon votre config
|
|
# chown -R nginx:nginx temp
|
|
```
|
|
|
|
Sur Windows avec WAMP/XAMPP, vérifier que l'utilisateur du serveur a les droits d'écriture sur `temp/`.
|
|
|
|
### 5. Configuration de l'application
|
|
|
|
Ouvrir `core/Config.php` et ajuster les paramètres si nécessaire :
|
|
|
|
```php
|
|
// Taille maximale des fichiers (en octets)
|
|
const MAX_FILE_SIZE = 500 * 1024 * 1024; // 500 MB
|
|
|
|
// Nombre maximum de fichiers par ZIP
|
|
const MAX_FILES_PER_ZIP = 10000;
|
|
|
|
// Profondeur maximale de l'arborescence
|
|
const MAX_TREE_DEPTH = 20;
|
|
|
|
// Durée de vie des sessions (en secondes)
|
|
const SESSION_LIFETIME = 86400; // 24 heures
|
|
```
|
|
|
|
### 6. Tester l'installation
|
|
|
|
1. Accéder à `http://fuzip.local` (ou votre URL configurée)
|
|
2. Uploader deux fichiers ZIP de test
|
|
3. Vérifier que l'arborescence s'affiche correctement
|
|
4. Tester la fusion et le téléchargement
|
|
|
|
## 📁 Structure du projet
|
|
|
|
```
|
|
fuzip/
|
|
├── api/ # Endpoints API REST
|
|
│ ├── cleanup.php # Nettoyage des anciennes sessions
|
|
│ ├── merge.php # Fusion et téléchargement du ZIP
|
|
│ ├── preview.php # Prévisualisation de fichiers
|
|
│ ├── structure.php # Extraction structure + conflits
|
|
│ └── upload.php # Upload et validation des ZIP
|
|
│
|
|
├── assets/ # Ressources frontend
|
|
│ ├── css/
|
|
│ │ ├── file-tree.css # Styles arborescence
|
|
│ │ ├── main.css # Styles globaux
|
|
│ │ ├── themes.css # Thèmes clair/sombre
|
|
│ │ └── upload-panel.css # Styles zones d'upload
|
|
│ └── js/
|
|
│ ├── app.js # Application principale
|
|
│ ├── FileTreeRenderer.js # Rendu arborescence
|
|
│ ├── LanguageManager.js # Gestion i18n
|
|
│ ├── PreviewManager.js # Prévisualisation fichiers
|
|
│ ├── ThemeManager.js # Gestion thèmes
|
|
│ └── UploadManager.js # Gestion uploads
|
|
│
|
|
├── core/ # Logique métier backend
|
|
│ ├── Config.php # Configuration globale
|
|
│ ├── FileTree.php # Construction arborescence
|
|
│ ├── SessionManager.php # Gestion sessions utilisateur
|
|
│ └── ZipHandler.php # Manipulation des ZIP
|
|
│
|
|
├── temp/ # Fichiers temporaires (gitignored)
|
|
│ └── uploads/ # ZIP uploadés par session
|
|
│
|
|
├── .gitignore # Fichiers exclus de Git
|
|
├── index.php # Point d'entrée
|
|
└── README.md # Documentation
|
|
```
|
|
|
|
## 🎮 Utilisation
|
|
|
|
### 1. Upload des ZIP
|
|
|
|
- Glisser-déposer deux fichiers ZIP dans les zones gauche et droite
|
|
- Ou cliquer sur "Parcourir" pour sélectionner les fichiers
|
|
- L'arborescence s'affiche automatiquement après l'upload
|
|
|
|
### 2. Navigation dans l'arborescence
|
|
|
|
- **Cliquer sur un dossier** pour l'expandre/réduire
|
|
- **Utiliser la recherche** pour filtrer les fichiers (expansion automatique)
|
|
- **Bouton "Tout déplier"** pour expandre toute l'arborescence
|
|
|
|
### 3. Sélection des fichiers
|
|
|
|
- **Cocher une checkbox** pour sélectionner un fichier ou dossier
|
|
- **Sélection exclusive** : pour les fichiers en conflit (⚠), cocher d'un côté désélectionne automatiquement l'autre
|
|
- **Sélection de dossier** : sélectionne automatiquement tous les fichiers contenus
|
|
- Le compteur en bas affiche le nombre de fichiers sélectionnés
|
|
|
|
### 4. Prévisualisation et téléchargement
|
|
|
|
- **Icône œil** : prévisualiser un fichier texte
|
|
- **Icône téléchargement** : télécharger un fichier individuellement
|
|
|
|
### 5. Fusion
|
|
|
|
- Cliquer sur **"Fusionner et Télécharger"** pour créer le ZIP final
|
|
- Le fichier `fuzip_merged_YYYY-MM-DD_HHmmss.zip` est téléchargé automatiquement
|
|
|
|
### 6. Réinitialisation
|
|
|
|
- Cliquer sur **"Réinitialiser"** pour tout effacer et recommencer
|
|
|
|
## 🔒 Sécurité
|
|
|
|
### Validations implémentées
|
|
|
|
- ✅ Vérification des **magic bytes** (signatures ZIP)
|
|
- ✅ Validation du **type MIME**
|
|
- ✅ Limitation de la **taille des fichiers** (configurable)
|
|
- ✅ Limitation du **nombre de fichiers** par ZIP
|
|
- ✅ Limitation de la **profondeur d'arborescence**
|
|
- ✅ **Sanitization** des noms de fichiers (../traversal, caractères spéciaux)
|
|
- ✅ Blocage des **extensions dangereuses** (.exe, .bat, .sh, etc.)
|
|
- ✅ **Isolation par session** : chaque utilisateur a son propre espace
|
|
- ✅ **Nettoyage automatique** des fichiers temporaires
|
|
|
|
### Extensions bloquées
|
|
|
|
```php
|
|
'.exe', '.bat', '.cmd', '.sh', '.com', '.pif', '.scr',
|
|
'.vbs', '.js', '.jar', '.app', '.deb', '.rpm'
|
|
```
|
|
|
|
### Recommandations
|
|
|
|
- Déployer derrière un **reverse proxy** (Nginx) pour la production
|
|
- Activer **HTTPS** avec certificat SSL/TLS
|
|
- Configurer un **firewall** (fail2ban, CSF)
|
|
- Limiter l'accès avec **authentification** si nécessaire
|
|
- Monitorer les **logs** (`temp/fuzip.log`)
|
|
|
|
## 🐛 Dépannage
|
|
|
|
### Les fichiers ne s'uploadent pas
|
|
|
|
- Vérifier les permissions du dossier `temp/uploads/`
|
|
- Vérifier les limites PHP (`upload_max_filesize`, `post_max_size`)
|
|
- Vérifier les logs : `temp/fuzip.log` et logs Apache/Nginx
|
|
|
|
### Erreur 500 lors de la fusion
|
|
|
|
- Augmenter `memory_limit` et `max_execution_time` dans `php.ini`
|
|
- Vérifier l'espace disque disponible
|
|
- Consulter les logs pour identifier l'erreur exacte
|
|
|
|
### L'état ne persiste pas
|
|
|
|
- Vérifier que localStorage est activé dans le navigateur
|
|
- Vérifier que les cookies de session PHP fonctionnent
|
|
- Nettoyer le cache du navigateur
|
|
|
|
### Conflit de session après fermeture
|
|
|
|
- Ceci est normal : si la session PHP expire, l'état est automatiquement nettoyé
|
|
- Augmenter `SESSION_LIFETIME` dans `Config.php` si nécessaire
|
|
|
|
## 📝 Licence
|
|
|
|
Ce projet est sous licence MIT. Voir le fichier `LICENSE` pour plus de détails.
|
|
|
|
## 👨💻 Auteur
|
|
|
|
Développé avec ❤️ pour faciliter la fusion de fichiers ZIP.
|
|
|
|
## 🤝 Contribution
|
|
|
|
Les contributions sont les bienvenues ! N'hésitez pas à :
|
|
|
|
1. **Fork** le projet
|
|
2. Créer une **branche** pour votre fonctionnalité (`git checkout -b feature/amazing-feature`)
|
|
3. **Commit** vos changements (`git commit -m 'Add amazing feature'`)
|
|
4. **Push** vers la branche (`git push origin feature/amazing-feature`)
|
|
5. Ouvrir une **Pull Request**
|
|
|
|
## 📮 Support
|
|
|
|
Pour toute question ou problème :
|
|
|
|
- Ouvrir une [issue](https://github.com/votre-username/fuzip/issues)
|
|
- Consulter la [documentation](https://github.com/votre-username/fuzip/wiki)
|
|
|
|
---
|
|
|
|
⭐ Si ce projet vous a été utile, n'hésitez pas à lui donner une étoile sur GitHub !
|