Extension WordPress : corriger un ZIP invalide ou sans extension reconnue

Lire le détail de l’erreur avant de remplacer des fichiers

Vous téléversez une extension et WordPress refuse le paquet : « Archive incompatible », « Aucune extension valide trouvée » ou un message mentionnant PclZip. Ces formulations n’indiquent pas toutes la même étape. Le résultat recherché est un paquet installable reconnu, puis une installation contrôlée ; il ne suffit pas de faire disparaître un avertissement.

Une archive illisible échoue pendant la décompression. Une archive qui s’ouvre peut contenir un thème, une documentation ou un dossier de développement au lieu d’une extension installable. Un message demandant une version différente de PHP ou de WordPress désigne encore une autre vérification. Copiez le texte complet, pas seulement le titre « échec de l’installation ».

Ce guide vise une extension WordPress classique autohébergée. Utilisez Extensions, et non l’écran des thèmes. Dans un réseau multisite, l’installation demande les droits adaptés au réseau. Si le menu n’est pas disponible sur votre hébergement géré, clarifiez d’abord le droit d’installation. Un compte sans ce droit ne sera pas débloqué en changeant le nom du ZIP.

Préserver le paquet reçu et l’état du site

Conservez le fichier d’origine dans votre espace local avec son nom, sa taille et sa provenance. Faites les observations sur une copie lorsque vous extrayez son contenu. Si vous demandez ensuite une correction à l’éditeur, il pourra distinguer son paquet de celui que vous auriez recompressé. Ne publiez pas un lien privé de téléchargement ou de licence dans un forum.

Avant un remplacement ou une activation, préparez une sauvegarde restaurable des fichiers et de la base. Pour une extension déjà utilisée, notez sa version, son état actif ou inactif et son rôle. Une suppression préalable peut déclencher une désinstallation et retirer des données : elle n’est pas une étape normale du diagnostic d’un ZIP invalide.

Commencez par le paquet local : source, téléchargement et structure. Si un paquet officiel intact et correctement organisé échoue encore, examinez le dépôt et la décompression côté serveur. Une copie de test permet de limiter les changements, à condition d’y neutraliser les paiements, envois et autres effets externes avant toute activation.

Approche 1 : récupérer une nouvelle copie officielle

Cette méthode convient si le téléchargement s’est interrompu, si le fichier provient d’un ancien échange ou si sa nature reste incertaine. Elle demande votre accès au répertoire officiel ou à l’espace de téléchargement de l’éditeur. Le but est de repartir d’un paquet prévu pour WordPress, sans réparer manuellement des fichiers manquants.

Pour une extension du répertoire WordPress.org, ouvrez sa fiche officielle et utilisez son téléchargement. Pour un produit commercial, ouvrez votre espace client autorisé et lisez la procédure propre à la version. Un produit portant un nom voisin, une archive de thème ou une bibliothèque PHP autonome ne deviennent pas une extension en renommant leur fichier.

1. Téléchargez le paquet installable correspondant au produit et à la version voulus, dans un nouveau dossier local.
2. Attendez la fin du téléchargement et vérifiez le nom complet ainsi que la taille. Un fichier encore temporaire ou vide ne convient pas.
3. Gardez l’ancienne copie séparée pour comparer. Si l’éditeur fournit une empreinte de contrôle, comparez-la avec l’outil prévu par sa documentation.
4. Reprenez le dépôt avec la nouvelle copie après les vérifications suivantes. Aucun fichier du site n’a besoin d’être modifié pour cette première étape.

Distinguer l’archive complète du ZIP installable

Un téléchargement commercial peut réunir documentation, exemples, licence et un ou plusieurs paquets. Sur Envato Market, le choix All files and Documentation sert notamment à obtenir la documentation incluse. Ce conteneur complet n’est pas nécessairement celui que l’écran Extensions attend. La documentation de l’auteur doit désigner le fichier à installer.

Ouvrez l’archive localement sans exécuter les fichiers qu’elle contient. Si vous y trouvez un ZIP explicitement désigné comme extension installable, utilisez ce ZIP intérieur. Ne lui ajoutez pas les PDF, exemples et autres dossiers du paquet complet. Si plusieurs ZIP sont présents, identifiez leur rôle : composant principal, module complémentaire ou version différente. Leur présence n’autorise pas à tout installer.

Un dépôt de code source peut également demander une préparation par son éditeur. Des dossiers src, tests ou des fichiers de dépendances ne prouvent pas qu’il est prêt à l’emploi. Cherchez la version distribuée pour WordPress ou demandez le paquet construit à l’auteur. N’inventez pas une procédure de compilation pour contourner le message d’installation.

Reconnaître la structure d’une extension sans modifier son code

Une extension classique distribuée en dossier possède un fichier PHP principal avec un en-tête reconnu par WordPress. Le champ Plugin Name identifie l’extension ; d’autres champs décrivent sa version et ses prérequis. Vous pouvez examiner ce fichier dans un éditeur de texte local sans le lancer. Son seul nom ne suffit pas à établir la validité du produit.

L’exemple ci-dessous est fictif et schématique : le dossier mon-extension contient son fichier principal et ses éventuels sous-dossiers. Il sert à repérer un emballage supplémentaire, pas à imposer ces noms à toutes les extensions. Une structure dossier-livraison/documentation/mon-extension.zip demande de choisir le paquet intérieur prévu, non de renommer dossier-livraison.

Si aucun fichier principal d’extension n’est présent à l’endroit attendu, revenez à la distribution officielle. N’ajoutez pas vous-même un en-tête Plugin Name pour forcer sa reconnaissance : vous pourriez déguiser un thème ou un paquet incomplet en extension. Si WordPress cite une version PHP ou WordPress minimale, conservez ce détail et traitez la compatibilité séparément.

mon-extension/
  mon-extension.php
  includes/
  assets/

Extraire une copie localement pour repérer un fichier endommagé

Cette vérification convient à une archive provenant d’une source identifiée. Elle sert à observer le contenu et les erreurs de lecture, sans encore installer de code sur le serveur. Choisissez un dossier local vide réservé à cette copie ; ne mélangez pas les fichiers avec une ancienne version.

Sous Windows, dans l’Explorateur de fichiers, faites un clic droit sur la copie du ZIP, puis Extraire tout et choisissez la destination. Les libellés peuvent varier légèrement selon la version. Attendez la fin et relevez tout message d’erreur. N’ouvrez pas un exécutable ou un script inclus pour tenter de réparer l’archive.

Une extraction réussie prouve seulement que cet outil a pu lire les éléments qu’il a extraits. Elle ne certifie ni l’innocuité du code ni sa compatibilité avec la méthode du serveur. Si l’outil réclame un mot de passe ou des volumes supplémentaires, obtenez le paquet installable adapté auprès de l’éditeur. Renommer RAR ou 7z en ZIP ne convertit pas leur format.

En cas d’échec local sur la nouvelle copie officielle, fournissez ce constat à l’auteur. Conservez l’original ; il n’y a encore aucun changement du site à annuler.

Contrôle facultatif avec Python déjà disponible

Si Python est déjà installé sur votre ordinateur, son module zipfile fournit un contrôle supplémentaire du ZIP. Cette variante n’est pas nécessaire au parcours dans l’Explorateur. Elle teste l’archive ; elle n’exécute pas le code PHP qu’elle contient et ne la téléverse pas vers votre site.

L’exemple utilise un chemin Windows fictif. Remplacez-le par celui de la copie à vérifier et gardez les guillemets si le chemin contient des espaces. Sur un autre système, utilisez son chemin local avec la même option -t. Travaillez uniquement sur le paquet identifié, sans extraction ni test automatique de toutes vos archives.

1. Ouvrez votre terminal local et exécutez la commande adaptée à ce fichier.
2. Lisez le résultat complet, y compris une exception ou une erreur de décompression. Une méthode de compression non prise en charge par cet outil ne prouve pas à elle seule un fichier tronqué.
3. Si le contrôle réussit, conservez ce résultat comme contrôle de lecture, pas comme certificat de sécurité ou validation WordPress.
4. Si le contrôle échoue sur un paquet officiel récemment téléchargé, demandez à l’auteur une distribution compatible. Aucune donnée du site n’a été changée.

python -m zipfile -t "C:\CHEMIN\extension.zip"

Téléverser le bon paquet depuis l’administration

Une fois le paquet identifié et les prérequis examinés, revenez dans WordPress avec le compte autorisé. Utilisez le ZIP installable lui-même, pas le dossier extrait ni un ZIP qui englobe tout votre dossier de travail. Ne recomprimez pas une distribution valide simplement parce que son nom contient un numéro de version.

Un nouvel échec identique malgré un paquet localement lisible justifie les contrôles serveur suivants. Un message de version minimale, de dépendance ou d’activation ne se résout plus en retéléchargeant le même ZIP. Gardez cette différence pour éviter une succession d’essais qui modifient plusieurs choses sans apporter de preuve.

1. Ouvrez Extensions, Ajouter une extension, puis Téléverser une extension.
2. Sélectionnez la nouvelle copie du ZIP officiel prévu et vérifiez son nom avant de cliquer sur Installer maintenant.
3. Attendez le résultat et relevez le message précis. Si l’installation réussit, contrôlez le nom et la version dans Extensions installées avant l’activation préparée.
4. Si WordPress reconnaît une extension déjà installée, passez au contrôle de remplacement décrit plus loin ; ne validez pas sans comparaison.

Approche 2 : vérifier si le fichier est reçu en entier

Cette approche convient après vérification de la provenance et du paquet. Relevez sa taille, la limite de dépôt affichée par WordPress et le moment où l’erreur apparaît. Dans Outils, Santé du site, Informations, examinez les réglages serveur disponibles. Le terminal de votre ordinateur ou une autre version de PHP ne représente pas nécessairement celle qui reçoit l’administration.

PHP distingue notamment la limite d’un fichier, upload_max_filesize, et celle de la requête complète, post_max_size. Cette dernière doit permettre le fichier et les autres données du formulaire. Un plafond plus bas dans un proxy ou le serveur Web peut encore arrêter la requête avant PHP. Ne choisissez pas une valeur au hasard pour toutes ces couches.

Si la taille du paquet reste sous les plafonds effectifs et que le serveur confirme sa réception complète, n’augmentez pas ces limites pour traiter un ZIP sans extension reconnue. En revanche, un dépassement confirmé peut se corriger dans le panneau prévu pour le domaine, avec une valeur autorisée et proportionnée. Ce contrôle distingue le transport du fichier de sa structure interne.

Ajuster une limite confirmée pour le seul domaine dans cPanel

Ce parcours demande un accès cPanel et l’accord du responsable sur les valeurs autorisées. Il ne s’applique que si la taille du dépôt a réellement été identifiée comme le blocage. Conservez les valeurs initiales et la configuration concernée ; ne choisissez pas une taille très élevée pour éviter de mesurer le fichier.

Ne supprimez pas tout php.ini pour annuler deux champs : vous pourriez perdre d’autres réglages utiles.

1. Ouvrez Software, puis MultiPHP INI Editor, et choisissez Basic Mode.
2. Dans le sélecteur, choisissez le domaine exact. Home Directory applique un périmètre plus large au compte et ne convient pas à cette correction ciblée.
3. Relevez upload_max_filesize et post_max_size lorsqu’ils sont proposés. Modifiez seulement les valeurs confirmées nécessaires au paquet, en prévoyant une marge pour la requête complète.
4. Cliquez sur Apply, revenez dans les informations du site et vérifiez la prise en compte. Refaites ensuite un seul dépôt préparé.
5. Rétablissez les valeurs initiales si la modification était injustifiée. Si le panneau limite la valeur ou si une couche amont refuse encore la requête, faites examiner cette seule couche par le prestataire.

Distinguer l’ouverture du ZIP de l’écriture des fichiers

WordPress peut utiliser ZipArchive et, dans certains cas, sa bibliothèque PclZip pour décompresser un paquet. Voir le nom PclZip dans l’erreur ne prouve pas que cette bibliothèque manque : cela peut être elle qui explique pourquoi elle n’a pas pu lire l’archive. Le code exact et la suite du message restent nécessaires.

Une erreur d’ouverture du ZIP, une archive vide et l’impossibilité de copier un fichier ne décrivent pas le même problème. Si l’outil local lit la distribution mais que WordPress ne peut pas l’ouvrir, fournissez au prestataire le paquet exact ou sa référence officielle, les versions du site et le message intégral. Il pourra comparer le fichier reçu et la méthode de décompression réellement utilisée dans PHP.

Ne désactivez pas globalement les contrôles d’archives et n’ajoutez pas un filtre trouvé ailleurs pour imposer une autre bibliothèque sans avoir identifié la cause. Si l’éditeur confirme un format de distribution incompatible, demandez un ZIP installable adapté. Une nouvelle archive fournie par l’auteur vaut mieux qu’une reconstruction improvisée qui retirerait des fichiers nécessaires.

Contrôler l’espace disponible et le répertoire de travail

Un paquet compressé a besoin de place après extraction et pendant la copie. WordPress utilise un répertoire de travail, habituellement sous wp-content/upgrade, pour préparer le paquet. La taille du ZIP ne représente donc pas à elle seule l’espace nécessaire à l’opération. Conservez le chemin exact affiché dans une erreur d’écriture.

Dans cPanel, Files puis Disk Usage aide à examiner l’usage du stockage du compte. Vérifiez les plafonds effectifs avec le prestataire si le quota ou le nombre de fichiers pose problème. Libérez seulement des éléments identifiés, après préservation des sauvegardes nécessaires hors du serveur. Ne supprimez pas les dossiers inconnus pour récupérer rapidement de la place.

Un refus d’écriture demande de vérifier propriétaire, permissions et emplacement temporaire utilisés par PHP. Il ne se corrige pas en rendant toute l’installation accessible à tous. Demandez une correction limitée au chemin et à l’identité confirmés. Ne videz pas wp-content/upgrade pendant une opération concurrente et ne supposez pas que tout ce qui s’y trouve appartient au seul essai que vous venez de lancer.

Si l’extension est déjà installée, comparer avant de remplacer

Un paquet reconnu peut conduire WordPress à présenter une comparaison entre l’extension actuelle et celle téléversée. Ce n’est plus l’erreur initiale d’archive illisible : le système a identifié un produit. Comparez son nom, son auteur, sa version et les prérequis affichés. Une différence inattendue demande d’annuler et de vérifier le téléchargement.

Le remplacement doit viser le même produit dans l’édition prévue. Une version gratuite et sa version commerciale ne suivent pas nécessairement la même procédure. Si l’éditeur demande de conserver deux composants ou de migrer certains réglages, sa documentation spécifique prime sur une assimilation fondée sur leurs noms proches.

Après sauvegarde et validation de ces points, utilisez la confirmation de remplacement proposée par WordPress, puis contrôlez la version installée. Ne cliquez pas sur Supprimer pour contourner une comparaison ou un dossier existant. Une rétrogradation n’est pas une simple réparation de ZIP et peut être incompatible avec les données déjà transformées. Si vous renoncez avant confirmation, retournez à la liste des extensions et vérifiez que l’ancienne version demeure celle attendue.

Vérifier l’activation et conserver les éléments du diagnostic

Une installation réussie rend l’extension disponible ; son activation reste une autre action. Avant de l’activer, confirmez les prérequis et les dépendances utiles au projet. Sur une copie, préparez les paramètres nécessaires sans envoyer de messages ou de transactions réels. Contrôlez ensuite une fonction représentative, l’administration et une page publique.

Si l’activation échoue avec une erreur PHP ou un message de version, gardez la trace et utilisez le dépannage correspondant. Ne modifiez pas l’en-tête du fichier pour masquer une exigence de compatibilité. Si une mise à jour déjà effectuée doit être annulée, faites coordonner fichiers et données selon la sauvegarde ; réinstaller seulement un ancien ZIP ne garantit pas un retour complet.

Pour l’aide, fournissez la provenance officielle du paquet, son nom, sa version, sa taille, le message intégral et les résultats locaux puis serveur, avec leurs heures. Transmettez les archives commerciales uniquement par le canal privé autorisé de l’éditeur. Aucune extension de réparation n’est nécessaire à ces vérifications : les outils natifs permettent de séparer la mauvaise distribution, le fichier illisible et la réception ou l’écriture refusée.

Identifiez l’étape à laquelle WordPress refuse le paquet

Sur une copie locale de WordPress 7.1.4, le même installateur a traité quatre paquets d’essai. Une copie dont une partie des octets avait été retirée a échoué à l’ouverture de l’archive. Un ZIP complet contenant une notice et un autre ZIP s’est ouvert, puis WordPress a signalé qu’il ne trouvait aucune extension valide. Le ZIP intérieur, présenté seul, a installé les fichiers et l’extension est apparue dans la liste des extensions installées, à l’état inactif. Dans le quatrième cas, WordPress a reconnu l’en-tête du fichier principal et refusé la version de PHP minimale déclarée par le paquet de test.

Sur votre copie, lisez le détail qui suit le message général d’échec et relevez le dernier état affiché. Si le fichier ne s’ouvre pas localement, reprenez le téléchargement auprès de l’éditeur et contrôlez de nouveau cette copie. Si le fichier s’ouvre et contient le ZIP installable indiqué par la notice, sélectionnez ce fichier intérieur dans l’écran de téléversement. Si WordPress affiche une version minimale de PHP, relevez la version du site dans Outils, Santé du site, puis Informations, rubrique Serveur. Transmettez ces deux versions à la personne qui gère le site ou vérifiez auprès de l’éditeur quelle version du produit est prise en charge.

Dans le banc local, les trois refus ont laissé le dossier des extensions vide. Sur votre copie, vérifiez l’état de la liste avant de relancer un essai. Si une version est déjà présente, comparez la version et le nom affichés avec les valeurs relevées au départ. Laissez l’extension inactive pendant la comparaison si elle vient d’être installée pour le test.

Vérifiez que vous comparez le même fichier

Cette vérification convient quand vous avez deux copies censées correspondre à la même distribution. Par exemple, vous disposez du téléchargement d’origine et d’une copie transférée dans un espace privé par votre équipe. Avec Windows et PowerShell, exécutez la commande ci-dessous sur chaque fichier, en remplaçant les chemins. Comparez toute la colonne Hash, qui contient une empreinte SHA-256. Si l’éditeur publie une empreinte pour cette version précise, comparez aussi votre résultat à cette valeur.

Deux empreintes identiques confirment que le contrôle porte sur le même contenu. Si elles diffèrent, vérifiez d’abord le nom de la version et la provenance de chaque fichier. Un fichier peut changer lors d’un transfert incomplet, et un éditeur peut distribuer plusieurs paquets légitimes pour un même produit. Reprenez le fichier désigné par sa notice avant un nouvel essai. L’empreinte permet de comparer des fichiers. La provenance se vérifie à partir de la distribution officielle.

Get-FileHash -LiteralPath 'C:\Recette\extension-originale.zip' -Algorithm SHA256
Get-FileHash -LiteralPath 'C:\Recette\extension-copie.zip' -Algorithm SHA256

Testez une seule correction à la fois sur la copie

Pour un conteneur de distribution, ouvrez le ZIP d’origine dans un dossier de travail local. Identifiez le paquet intérieur d’après la notice, extrayez ce seul fichier et reprenez l’installation depuis Extensions, Ajouter une extension. Le contrôle attendu est l’apparition de la bonne version dans Extensions installées. Pour annuler cet essai sur une copie dédiée, supprimez les fichiers de l’extension d’essai encore inactive depuis l’administration si elle le permet, ou revenez à l’instantané de la copie.

Pour un fichier officiel lisible qui échoue dès l’envoi, relevez la taille du fichier, la limite affichée et l’heure de l’essai. Demandez au responsable du serveur de confirmer quelle couche refuse la requête avant de toucher à un réglage. Rejouez ensuite avec le même fichier après la seule correction autorisée. Si le refus intervient toujours au même stade, remettez la valeur du réglage relevée avant l’essai et poursuivez le diagnostic avec le message exact. La recette du banc transmet un fichier local à l’installateur WordPress. Sur votre site, la réception HTTP, les quotas et les permissions du serveur se contrôlent séparément.