README

This plugin allows you to download extra files and extract them within your package.

This is an updated version of civicrm/composer-downloads-plugin. It adds support for more archive files and allow custom variables.

Example

Suppose your PHP package foo/bar relies on an external archive file (examplelib-1.1.0-windows-amd64.zip on Windows, or examplelib-1.1.0-linux-x86_64.tar.gz on Linux, or examplelib-1.1.0-darwin-x86_64.tar.gz on MacOS):

{
  "name": "foo/bar",
  "require": {
    "pact-foundation/composer-downloads-plugin": "^1.0"
  },
  "extra": {
    "downloads": {
      "examplelib": {
        "url": "https://example.com/examplelib-{$version}-{$os}-{$architecture}${$musl}.{$extension}",
        "path": "extern/{$id}",
        "version": "1.1.0",
        "variables": {
            "{$musl}": "PHP_OS === 'Linux' && musl() === true ? '-musl' : ''",
            "{$os}": "strtolower(PHP_OS_FAMILY)",
            "{$architecture}": "strtolower(php_uname('m'))",
            "{$extension}": "PHP_OS_FAMILY === 'Windows' ? 'zip' : 'tar.gz'",
        },
        "ignore": ["tests", "doc", "*.md"],
        "hash": {
          "algo": "sha256",
          "value": "08fbce50f84d89fdf1fdef425c7dd1a13c5c023fa87f453ba77db4df27d273c0"
        }
      }
    }
  }
}

When a downstream user of foo/bar runs composer require foo/bar, it will download and extract the archive file to vendor/foo/bar/extern/examplelib.

Attribute:

• url: The URL to the extra file.

• path: The releative path where content will be extracted.

• type: (Optional) Determines how the download is handled. If omit, the extension in url will be used to detect.

  • Archive types (The archive file url will be downloaded and extracted to path):
    • zip: . Support extension *.zip
    • rar: Support extension *.rar
    • xz: Support extension *.tar.xz
    • tar: Support extensions *.tar.gz, *.tar.bz2, *.tar, *.tgz
  • File types (The file url will be downloaded and placed at path):
    • file
    • phar: The file will be mark as executable.
    • gzip: The *.gz file will be extracted to a file that will be placed at path.

• ignore: (Optional) A list of a files that should be omited from the extracted folder.

  • This supports a subset of .gitignore notation.
  • Only useful with archive types.

• executable: (Optional) Indicate list of files should be mark as executable.

  • For archive types: the value should be a list of extracted files
  • For file types: the value should be boolean (true/false)

• version: (Optional) A version number for the downloaded artifact.

  • This has no functional impact on the lifecycle of the artifact.
  • It can affect the console output.
  • It can be used as a variable.

• variables: (Optional) List of custom variables.

• hash: (Optional) Verify contents of the file downloaded from url. If hash values are not the same: file will be deleted & composer will throw exception.

  • algo: Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..). For a list of supported algorithms see hash_algos()
  • value: Expected value of hash function

Variables

Supported Attribute

Only following attribute support variables:

• url
• path
• ignore

Default Variables

• {$id}: The identifier of the download. (In the example, it would be examplelib.)
• {$version}: Just a text defined in the version attribute, if not defined, the value will be empty string ("").

Custom Variables

• The format will be "{$variable-name}": "EXPRESSION-SYNTAX-EVALUATED-TO-STRING"
• More about the syntax at Expression Syntax.
• The syntax must be evaluated into a string.

Methods

Custom variable support these methods:

• range
• strtolower
• php_uname
• in_array
• str_contains
• str_starts_with
• str_ends_with
• matches
• musl

Constants

Custom variable support these constants:

• PHP_OS
• PHP_OS_FAMILY
• PHP_SHLIB_SUFFIX
• DIRECTORY_SEPARATOR

Default Attributes

You may set default attributes for all downloads. Place them under *, as in:

{
  "extra": {
    "downloads": {
      "*": {
        "path": "bower_components/{$id}",
        "ignore": ["test", "tests", "doc", "docs"],
        "variables": {
          "{$extension}": "zip"
        }
      },
      "jquery": {
        "url": "https://github.com/jquery/jquery-dist/archive/1.12.4.{$extension}"
      },
      "jquery-ui": {
        "url": "https://github.com/components/jqueryui/archive/1.12.1.{$extension}"
      }
    }
  }
}

Document

See more at Doc

Contributing

Pull requests are welcome, please send pull requests.

If you found any bug, please report issues.

Authors

• Rob Bayliss - Composer Extra Files
• Tim Otten and contributors - Composer Download Plugin
• Tien Vo and contributors - this project

License

This package is available under the MIT license.