Troubleshooting and warning in code related to issues with native ZipArchiver.

doc/articles/troubleshooting.md

@@ -345,3 +345,14 @@ composer update
 ```
 
 See also https://github.com/composer/composer/issues/4180 for more information.
+
+## Zip archives are being reported as corrupted or not unpacked correctly.
+
+Composer can unpack zipballs using either a system-provided `unzip` utility or PHP's
+native `ZipArchiver` class, preferring the first. The `ZipArchiver` class however is
+known to occassionally report valid zip files as corrupted, and does not support certain
+advanced features with permissions and symlinks.
+
+If you have issues with zip files you should install a native implementation of unzip
+and verify whether the problem persists. If so it is likely a real issue in the file
+itself and you should contact the provider.

src/Composer/Downloader/ZipDownloader.php

@@ -98,7 +98,10 @@ class ZipDownloader extends ArchiveDownloader
         }
 
         if (true !== $zipArchive->extractTo($path)) {
-            throw new \RuntimeException("There was an error extracting the ZIP file. Corrupt file?");
+            $this->io->writeError("<warn>As there is no 'unzip' command installed zip files are being unpacked using the PHP zip extension.</warn>");
+            $this->io->writeError("<warn> This may cause invalid reports of corrupted archives. Installing 'unzip' may remediate them.</warn>");
+
+            throw new \RuntimeException("There was an error extracting the ZIP file, it is either corrupted or using an invalid format");
         }
 
         $zipArchive->close();