fuzip/README.md

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

git clone https://github.com/votre-username/fuzip.git
cd fuzip

2. Configuration du serveur web

Apache

Créer un VirtualHost :

<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 :

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 :

upload_max_filesize = 512M
post_max_size = 512M
max_execution_time = 300
memory_limit = 512M
max_input_time = 300

4. Permissions des dossiers

# 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 :

// 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

'.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
• Consulter la documentation

---

⭐ Si ce projet vous a été utile, n'hésitez pas à lui donner une étoile sur GitHub !