README

The "Compile" plugin enables developers of PHP libraries to define free-form "compilation" tasks, such as:

• Converting SCSS to CSS
• Generating PHP wrappers based on an XML schema

For site-builders who use these PHP libraries, compilation tasks run seamlessly during the regular download (composer install, etc).

For developers who publish PHP libraries, a task can be as simple as:

{
  "require": {"civicrm/composer-compile-plugin": "~0.14"},
  "extra": {
    "compile": [
      {"run": "@sh cd css; cat one.css two.css three.css > all.css"}
    ]
  }
}

Tasks may be defined in several ways, including:

• Shell command (@sh cat file-{1,2,3} > big-file)
• PHP method (@php-method MyBuilder::build)
• PHP eval (@php-eval file_put_contents('big-file', make_big_file());)
• PHP script file (@php-script my-script.php)
• Composer subcommand (@composer dump-autoload)

Features:

• Easy to enable. No manual configuration for downstream site-builders. Framework agnostic.
• Plays well with other composer tooling, like forked repositories, composer-patches, composer-locator, composer-downloads, and the autoloader.
• Allows library repos to remain "clean" without committing build artifacts.
• Runs locally in PHP. Does not require external/hosted services or additional interpreters.
• Supports file monitoring for automatic rebuilds (composer compile:watch)
• Enforces permission model to address historical concerns about composer hooks and untrusted libraries.
• Integration-tests pass on both composer v1.10 and v2.0.

Documentation

• site-build.md: Managing the root package (for site-builders)
• tasks.md: Working with tasks (for library developers)
• evaluation.md: Evaluate and compare against similar options
• develop.md: How to work with composer-compile-plugin.git (for plugin-development)

See also

• composer-compile-lib: Small library of opinionated helpers/examples for specific compilation tasks -- meta-PHP, SCSS, etc
• composer#1193: Old discussion thread about post-install hooks for dependencies