Produits dématérialisés PrestaShop : corriger les erreurs de téléchargement

Produits dématérialisés PrestaShop : diagnostiquer et corriger les erreurs après téléchargement

La vente de produits dématérialisés (ebooks, templates, fichiers ZIP, licences logicielles) est un levier de marge important pour les e-commerçants PrestaShop. Mais quand un client télécharge son fichier et obtient une erreur à l'ouverture, c'est la crédibilité de la boutique qui en prend un coup.

Ce problème revient régulièrement, et les causes sont multiples. Voici une méthodologie complète pour identifier et corriger l'origine du problème.

Comprendre le circuit de téléchargement dans PrestaShop

Avant de debugger, il faut comprendre comment PrestaShop gère les produits virtuels :

1. **Upload** : le fichier est stocké dans le dossier `/download/` à la racine de PrestaShop
2. **Association** : le fichier est lié au produit via la table `ps_product_download`
3. **Achat** : à la validation de commande, PrestaShop génère un hash unique de téléchargement
4. **Livraison** : le client reçoit un lien avec ce hash, qui pointe vers `index.php?controller=get-file&key=HASH`
5. **Streaming** : le contrôleur `GetFileController` lit le fichier et l'envoie au navigateur via `readfile()`

Chacune de ces étapes peut être la source du problème.

Étape 1 : activer le mode debug

Premier réflexe indispensable — activer le mode debug pour voir si PrestaShop remonte des erreurs PHP silencieuses :

PrestaShop 1.7

Éditez le fichier config/defines.inc.php :

define('_PS_MODE_DEV_', true);

PrestaShop 8.x

Modifiez le fichier .env à la racine du projet :

APP_DEBUG=1
APP_ENV=dev

Une fois le debug activé, tentez à nouveau le téléchargement. Si une erreur PHP apparaît (memory limit, permission denied, file not found), vous avez votre piste.

Étape 2 : vérifier l'intégrité du fichier sur le serveur

Un fichier ZIP peut être corrompu à plusieurs moments : pendant l'upload, lors du transfert FTP, ou à cause d'un disque défectueux.

Vérifier que le fichier existe

ls -la /var/www/prestashop/download/

Repérez votre fichier. Son nom dans le dossier /download/ est hashé par PrestaShop. Pour retrouver la correspondance :

SELECT id_product, display_filename, filename, nb_downloadable, date_add
FROM ps_product_download
WHERE active = 1
ORDER BY date_add DESC;

La colonne filename correspond au nom hashé dans /download/, tandis que display_filename est le nom original affiché au client.

Tester l'intégrité du ZIP côté serveur

# Tester l'intégrité de l'archive
unzip -t /var/www/prestashop/download/HASH_DU_FICHIER

# Vérifier la taille (comparer avec l'original)
ls -lh /var/www/prestashop/download/HASH_DU_FICHIER
md5sum /var/www/prestashop/download/HASH_DU_FICHIER

Si unzip -t remonte des erreurs, le fichier est corrompu sur le serveur. Il faut le réuploader.

Point important : testez toujours l'intégrité côté serveur avant de conclure. Si le fichier s'ouvre correctement sur le serveur mais pas après téléchargement, le problème vient du processus de streaming.

Étape 3 : le piège du output buffering

C'est la cause la plus fréquente et la plus sournoise. Si du contenu (même un espace ou un BOM UTF-8) est envoyé avant le fichier, il sera concaténé au début du flux binaire et corrompra le fichier.

Diagnostiquer

Téléchargez le fichier problématique et ouvrez-le dans un éditeur hexadécimal. Un fichier ZIP valide commence toujours par les octets 50 4B 03 04 (la signature "PK"). Si vous voyez des caractères avant cette signature, du contenu parasite est injecté.

Corriger

Dans le contrôleur de téléchargement, ou dans un override, assurez-vous de nettoyer le buffer avant l'envoi :

// Nettoyer tout output buffer existant
while (ob_get_level()) {
    ob_end_clean();
}

// Headers corrects pour un téléchargement binaire
header('Content-Type: application/octet-stream');
header('Content-Disposition: attachment; filename="' . $display_filename . '"');
header('Content-Length: ' . filesize($file_path));
header('Content-Transfer-Encoding: binary');
header('Cache-Control: must-revalidate');
header('Pragma: public');

// Envoi du fichier
readfile($file_path);
exit;

PrestaShop 8.x : la méthode Symfony

Sur PrestaShop 8.x, privilégiez la réponse Symfony qui gère proprement le streaming :

use Symfony\Component\HttpFoundation\BinaryFileResponse;
use Symfony\Component\HttpFoundation\ResponseHeaderBag;

$response = new BinaryFileResponse($filePath);
$response->setContentDisposition(
    ResponseHeaderBag::DISPOSITION_ATTACHMENT,
    $displayFilename
);

return $response;

Étape 4 : les limites serveur

Pour les fichiers volumineux, plusieurs paramètres PHP et serveur peuvent tronquer le téléchargement :

; php.ini — valeurs recommandées pour des fichiers jusqu'à 256 Mo
upload_max_filesize = 256M
post_max_size = 256M
memory_limit = 512M
max_execution_time = 300
max_input_time = 300

Pour Nginx, ajoutez dans votre bloc server :

client_max_body_size 256M;
proxy_read_timeout 300;
send_timeout 300;

Pour Apache, dans votre .htaccess ou VirtualHost :

LimitRequestBody 268435456
TimeOut 300

Attention : si vous utilisez un CDN (Cloudflare, etc.), vérifiez aussi les limites de taille de réponse côté CDN. Cloudflare Free limite les réponses à 100 Mo par défaut.

Étape 5 : le problème côté client

Avant de tout remettre en question côté serveur, il est pertinent de vérifier si le problème est côté client :

• **Tester sur un autre navigateur** : certains navigateurs peuvent interférer avec le téléchargement (extensions de sécurité, antivirus intégré)
• **Tester sur une autre machine** : un utilitaire de décompression défaillant ou obsolète peut être en cause
• **Vérifier la taille du fichier téléchargé** : comparez-la avec la taille attendue. Si elle diffère, le téléchargement a été tronqué
• **Logiciel de décompression** : l'utilitaire Windows natif est limité. Recommandez 7-Zip ou WinRAR à vos clients

Étape 6 : sécuriser la configuration des produits virtuels

Dans le back-office, vérifiez ces paramètres essentiels :

Préférences > Produits > Produits dématérialisés (PS 1.7) ou Paramètres de la boutique > Produits (PS 8.x) :

• **Nombre de téléchargements autorisés** : ne mettez pas 0 (illimité) en production, limitez à 3-5 pour éviter les abus
• **Nombre de jours** : délai d'expiration du lien (30 jours recommandé)
• **Envoyer un e-mail avec le lien** : activez cette option pour que le client ait toujours accès au lien même s'il ferme son navigateur

Checklist de diagnostic rapide

Voici l'ordre de vérification recommandé quand un client signale un fichier corrompu :

1. **Mode debug activé** → erreur PHP visible ?
2. **Fichier présent dans `/download/`** → taille cohérente ?
3. **`unzip -t` sur le serveur** → fichier intègre ?
4. **Éditeur hexadécimal sur le fichier téléchargé** → octets parasites avant `PK` ?
5. **Taille fichier serveur vs fichier téléchargé** → identique ?
6. **Test sur autre navigateur/machine** → reproductible ?
7. **Logs serveur** (`error.log`) → timeout ou erreur ?

Si le fichier est intact sur le serveur mais corrompu après téléchargement, le problème est presque toujours lié à l'output buffering ou aux headers HTTP.