Home

PHP.GT Build provides a system to describe client-side build work in one place and run it from PHP projects without introducing another package manager or task runner of its own.

The library does two jobs:

• checks that the commands the project depends on are installed and meet the version constraints
• runs the relevant commands when matching source files exist, either once or continuously in watch mode

Build does not install or manage front-end tooling for us. We can keep using whatever tooling is preferred, whether that means node_modules/.bin, vendor/bin, or programs installed elsewhere on the system.

What the configuration looks like

The recommended format is build.ini. Each section name is a file pattern, and each section describes the command to run for that pattern.

build.ini:

[script/**/*.es6]
name=Bundle JavaScript
require=node_modules/.bin/esbuild >=0.17, node >=18
execute=./node_modules/.bin/esbuild ./script/app.es6 --bundle --sourcemap --outfile=./www/script.js

[style/**/*.scss]
name=Compile Sass
require=sass >=1.6
execute=sass ./style/style.scss ./www/style.css

[asset/**/*]
name=Publish static assets
require=vendor/bin/sync ^1.3
execute=vendor/bin/sync ./asset ./www/asset --symlink

When we run vendor/bin/build, Build checks the requirements first and then executes each task whose glob matches at least one file.

INI is now the default

Build still supports build.json, but build.ini is usually more compact for this kind of command-focused configuration.

JSON support remains available for projects that already use it, or for cases where a nested object structure is preferred. There's a separate JSON configuration example page showing the equivalent layout.

A few details worth knowing early

• If both build.ini and build.json exist in the same directory, Build uses build.ini.
• Mode files work with both formats: build.production.ini or build.production.json.
• The require line is optional, but it is worth using so problems are detected before a build starts.
• Task names are optional. If omitted, the command itself is used in log output.

---

Start with command line usage to see how Build finds configuration files and how the command-line options fit together.