Improve error handling and abstract download classes

[mcaskill]

Checklist

• I've read the Contributing page.
• Issues: * is not a zip archive. #1, BUG: Zips are coming back empty. I think! #14, Error while extracting content  #18, Failed to execute (9) unzip -qq -o 'web/app/plugins/wp-all-import-pro// ... #27, WP All Import and WP All Export Addons not working #33, The "https://www.wpallimport.com/" file could not be downloaded (HTTP/2 503 ) #41
• My code is tested.
• My code follows the WordPress code style.
• My code has proper inline documentation.

Issue

When an add-on is unsupported or if a download URL can not be retrieved or resolved, an empty string is returned.

This has the unintended consequence of causing Composer to fail much later during the package installation routine resulting in the following error:

Example of the error "Failed to extract junaidbhura/ninja-forms-foobar"

$ composer require junaidbhura/ninja-forms-foobar
./composer.json has been updated
Running composer update junaidbhura/ninja-forms-foobar
Gathering patches from patch file.
Loading composer repositories with package information
Updating dependencies
Nothing to modify in lock file
Installing dependencies from lock file (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
  - Downloading junaidbhura/ninja-forms-foobar (1.0.0)
Gathering patches from patch file.
Gathering patches for dependencies. This might take a minute.
  - Installing junaidbhura/ninja-forms-foobar (1.0.0): Extracting archive
    Failed to extract junaidbhura/ninja-forms-foobar: (9) '/usr/bin/unzip' -qq '…/vendor/composer/tmp-3e5657bb7bb690e28af71c04f2d6fece' -d '…/vendor/composer/a78af123'

[…/vendor/composer/tmp-3e5657bb7bb690e28af71c04f2d6fece]
  End-of-central-directory signature not found.  Either this file is not
  a zipfile, or it constitutes one disk of a multi-part archive.  In the
  latter case the central directory and zipfile comment will be found on
  the last disk(s) of this archive.
unzip:  cannot find zipfile directory in one of …/vendor/composer/tmp-3e5657bb7bb690e28af71c04f2d6fece or
        …/vendor/composer/tmp-3e5657bb7bb690e28af71c04f2d6fece.zip, and cannot find …/vendor/composer/tmp-3e5657bb7bb690e28af71c04f2d6fece.ZIP, period.

    The archive may contain identical file names with different capitalization (which fails on case insensitive filesystems)
    Unzip with unzip command failed, falling back to ZipArchive class
    Install of junaidbhura/ninja-forms-foobar failed

In ZipDownloader.php line 220:

  '…/vendor/composer/tmp-3e5657bb7bb690e28af71c04f2d6fece' is not a zip archive.

To summarize this lengthy error: Composer is attempting to unzip a blank file downloaded from the empty string.

This error has confused many, including myself, as to the real cause. There are numerous issues about it.

Solution

The solution to this is to explicitly throw an exception during the processing of an add-on and the processing of the download URL to abort the package installation process sooner and provide a clear reason for what went wrong.

To simplify the addition of these error messages, I've abstracted common properties and methods into two base classes for greater consistency between plugin downloaders, especially EDD-distributed plugins.

I've chosen UnexpectedValueException since it seems like a good fit for most scenarios based on similar usage in Composer.

There are currently four kinds of error messages thrown:

1. Package is not supported (Ninja Forms and PublishPress Pro)
2. Download URL is invalid/missing (EDD and Gravity Forms)
3. Download version is invalid/missing (EDD only)
4. Download version and installed version do not match (EDD only)

Example of the error "Could not find a matching package" (1)

$ composer require junaidbhura/ninja-forms-foobar
Info from https://repo.packagist.org: #StandWithUkraine
./composer.json has been updated
Running composer update junaidbhura/ninja-forms-foobar
Gathering patches from patch file.
Loading composer repositories with package information
Updating dependencies
Lock file operations: 1 install, 0 updates, 0 removals
  - Locking junaidbhura/ninja-forms-foobar (1.0.0)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 1 install, 0 updates, 0 removals

In NinjaForms.php line 299:

  Could not find a matching package for junaidbhura/ninja-forms-foobar. Check the package spelling and that the package is supported

Example of the error "Expected a valid download URL" (2)

$ composer require junaidbhura/ninja-forms-foobar
./composer.json has been updated
Running composer update junaidbhura/ninja-forms-foobar
Gathering patches from patch file.
Loading composer repositories with package information
Updating dependencies
Nothing to modify in lock file
Installing dependencies from lock file (including require-dev)
Package operations: 1 install, 0 updates, 0 removals

In AbstractEddPlugin.php line 26:

  Expected a valid download URL for package junaidbhura/ninja-forms-foobar

Example of the error "Expected a valid download version number" (3)

$ composer require junaidbhura/ninja-forms-foobar
./composer.json has been updated
Running composer update junaidbhura/ninja-forms-foobar
Gathering patches from patch file.
Loading composer repositories with package information
Updating dependencies
Nothing to modify in lock file
Installing dependencies from lock file (including require-dev)
Package operations: 1 install, 0 updates, 0 removals

In AbstractEddPlugin.php line 33:

  Expected a valid download version number for package junaidbhura/ninja-forms-foobar

Example of the error "Expected download version to match installed version" (4)

$ composer require junaidbhura/ninja-forms-foobar
./composer.json has been updated
Running composer update junaidbhura/ninja-forms-foobar
Gathering patches from patch file.
Loading composer repositories with package information
Updating dependencies
Nothing to modify in lock file
Installing dependencies from lock file (including require-dev)
Package operations: 1 install, 0 updates, 0 removals

In AbstractEddPlugin.php line 40:

  Expected download version (3.0.0) to match installed version (2.0.0) of package junaidbhura/ninja-forms-foobar

How has this been tested?

I'm testing this on a client project that uses Advanced Custom Fields Pro, ACF Extended Pro, and WPML.

Screenshots

[mcaskill]

If you prefer, the AbstractEddPlugin could be a trait instead, the concept of the abstract classes could be different if you had something in mind, or each exception could be added to each downloader class.

[junaidbhura]

@mcaskill Abstract classes may be easier for potential contributors. Lets merge this! 🚀