Download the PHP package civicrm/composer-compile-lib without Composer

CiviCRM Composer Compilation Library

This package provides a handful of small tasks and helpers for use with composer-compile-plugin.

Design guidelines for this package:

• To ensure easy operation in a new/unbooted system:
  • Use basic functions and static methods
  • Use primitive data sources (such as static JSON files)
• To ensure that compilation steps report errors:
  • Every task/function must throw an exception if it doesn't work.
• To allow pithy tasks:
  • If a task is outputting to a folder, and if the folder doesn't exist, then it should auto-create the folder.

The primary purpose here is demonstrative - to provide examples. Consequently, it is fairly minimal / lightweight / loosely-coupled. There is no dependency on CiviCRM. Conversely, CiviCRM packages may define other tasks which are not in this library.

Require the library

All the examples below require the civicrm/composer-compile-lib package. Load via CLI:

Or via composer.json:

Task: SCSS

In this example, we generate a file dist/sandwich.css by reading scss/sandwich.scss. The file may @import mixins and variables from the ./scss/ folder.

Note that a "task" simply calls a static PHP method (@php-method \\CCL\\Tasks::scss) with the JSON data as input. You can also call the method in a PHP script. For example, we could define a task based on a script:

The following script generalizes the example from before -- it maps any SCSS files (scss/*.scss) to corresponding CSS files (dist/#1.css). This file-list is passed into \CCL\Tasks::scss for processing:

Note that this implementation of \CCL\Tasks::scss() is fairly opinionated - it combines scssphp with php-autoprefixer. The output is written as two files, a larger files (*.css) and a smaller file (*.min.css).

Task: PHP Template

In this example, we use a PHP template to generate another PHP file. Specifically, we create Sandwich.php using the specification from EntityTemplate.php:

As in the previous example, the task is simply a PHP method (@php-method \\CCL\\Tasks::template), so it can be used from a PHP script. The following script would extend the pattern, mapping any JSON files (src/Entity/*.json) to corresponding PHP files (src/Entity/#1.php):

Functions

PHP's standard library has a lot of functions that would work for basic file manipulation (copy(), rename(), chdir(), etc). The problem is error-signaling -- you have to explicitly check error-output, and this grows cumbersome for improvised glue code. It's more convenient to have a default stop-on-error behavior, e.g. throwing exceptions.

symfony/filesystem provides wrappers which throw exceptions. But it puts them into a class Filesystem which, which requires more boilerplate.

For the most part, CCL simply mirrors symfony/filesystem using static methods in the CCL class. Compare:

This is more convenient for scripting one-liners. For example, the following tasks do simple file operations. If anything goes wrong, they raise an exception and stop the compilation process.

The full function list:

For more details about each function, see CCL\Functions and symfony/filesystem.