Composer Archive Project

Pondermatic is proud to announce the public release of our new Composer plugin called “Composer Archive Project“. It makes it easy to create an archive file as part of your development project’s release process.

What problem does this solve?

The Composer archive command creates an archive file of your package with the following hierarchy:

.
|-- src/
|   |-- main.php
|-- composer.json
|-- readme.md

However, archives for WordPress plugins and themes require a directory in the archive root with the name of the plugin or theme’s slug, e.g. pondermatic/xapi.

.
|-- xapi/
|   |-- src/
|   |   |-- main.php
|   |-- composer.json
|   |-- readme.md

Installation

To install this Composer plugin in your project:

composer require --dev pondermatic/composer-archive-project

If you’re using Composer version 2.2 or above, you will be asked to give permission to allow this plugin to execute, which will add the following to your composer.json file.

{
    "config": {
        "allow-plugins": {
            "pondermatic/composer-archive-project": true
        }
    }
}

How to use

Now Composer has a new archive-project command.

$ composer help archive-project
Description:
  Creates an archive of this composer package with a root project directory

Usage:
  archive-project [options] [--] [<package> [<version>]]

Arguments:
  package                        The package to archive instead of the current project
  version                        A version constraint to find the package to archive

Options:
  -f, --format=FORMAT            Format of the resulting archive: tar, tar.gz, tar.bz2 or zip (default tar)
      --dir=DIR                  Write the archive to this directory
      --file=FILE                Write the archive with the given file name. Note that the format will be appended.
      --ignore-filters           Ignore filters when saving package
  -h, --help                     Display help for the given command. When no command is given display help for the list command
  -q, --quiet                    Do not output any message
  -V, --version                  Display this application version
      --ansi|--no-ansi           Force (or disable --no-ansi) ANSI output
  -n, --no-interaction           Do not ask any interactive question
      --profile                  Display timing and memory usage information
      --no-plugins               Whether to disable plugins.
      --no-scripts               Skips the execution of all scripts defined in composer.json file.
  -d, --working-dir=WORKING-DIR  If specified, use the given directory as working directory.
      --no-cache                 Prevent use of the cache
  -v|vv|vvv, --verbose           Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  The archive-project command creates an archive of the specified format
  containing the files and directories of the Composer project or the specified
  package in the specified version and writes it to the specified directory.

  php composer.phar archive-project [--format=zip] [--dir=/foo] [--file=filename] [package [version]]

  Read more at https://getcomposer.org/doc/03-cli.md#archive

How it works

The name of the project is taken from the name property in your package’s composer.json file. For example, if your package name is pondermatic/xapi, then the project name is xapi.

Excluding paths

To prevent the archive from containing unwanted files, set the exclude option in the archive property of composer.json. This can be used to exclude IDE settings, the archive directory, unit tests, and development dependencies.

In this example, all development dependencies are excluded with "/vendor/” and then the files required by the distribution package are specified with the "!" prefix. Another way to do this would be to exclude specific directories|files.

"archive": {
        "exclude": [
            "/.idea/",
            "/archive/",
            "/tests/",
            "/vendor/",
            "!/vendor/autoload.php",
            "!/vendor/composer/",
            "/vendor/composer/installed.*",
            "/vendor/composer/LICENSE",
            "/.gitignore",
            "/composer.*",
            "/phpunit.xml*"
        ]
    },

These two script events can be used to automatically prevent development dependencies from the autoload.php file.

"scripts": {
        "pre-archive-cmd": "@composer dump-autoload --no-dev",
        "post-archive-cmd": "@composer dump-autoload"
    },