phing: A PHP Build System in the Ant Mould

An Ant for PHP, Not Another Make

Phing expands its own name: PHing Is Not GNU make, and the README says plainly that it is a PHP project build system or build tool based on Apache Ant.

The borrowing is structural rather than cosmetic. Ant's model is that a build file is declarative XML, and the work is done by task classes that the file invokes. Phing keeps both halves of that: simple XML build files and extensible PHP task classes, and the README describes the combination as an easy-to-use and highly flexible build framework.

The pitch to a PHP developer is that the build system speaks the same language as the application. A task is a PHP class, so a task you need for your own project is a class you write, and the object model is there to extend or add custom tasks to.

The target audience is stated in the README as people who find themselves writing custom scripts to handle the packaging, deploying or testing of their applications. The argument is that the pre-packaged operation modules, the tasks, remove the need for those scripts, and that a build file is something a colleague can read six months later.

What the Task Library Already Covers

The feature list is where the value of an existing library shows, because the tasks are the library.

Running PHPUnit unit tests is there, including test result and coverage reports, which is the one most teams adopt first. File transformations cover token replacement, XSLT transformation and template transformations, which is the other common category, since a PHP project usually has templates and generated assets. There are file system operations, interactive build support, and SQL execution, so a build can prepare a database as part of its steps.

Source control operations cover Git, Subversion and Mercurial, which is a deliberate breadth choice, since the tool is not tied to one of the three. Documentation generation is covered by PhpDocumentor and ApiGen.

The three source control systems together are a good example of the task model paying off. Each is a class, so supporting all three costs three classes rather than three code paths through the build engine, and the same is true for the two documentation tools and the several transformation types.

Four Ways to Install, Including a GitHub Action

The install section gives four routes, and the first is the preferred one.

Composer is the preferred method. You add phing/phing to the require-dev or the require section of your project's composer.json and run composer install:

{
    "require-dev": {
        "phing/phing": "3.1.x-dev"
    }
}

The Phar route is the zero-install option, downloading the archive from the project site and running it with php phing-latest.phar.

The Docker route is marked experimental, with the official image on Docker Hub. To execute Phing inside a container and run a build.xml located in /home/user:

docker run --rm -v /home/user:/opt phing/phing:3.0 -f /opt/build.xml

The fourth is a GitHub Action, phingofficial/phing-github-action, published on the GitHub Marketplace. The workflow snippet in the README shows the shape:

name: CI
on: [ push ]
jobs:
  build-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Phing Build
        uses: phingofficial/[email protected]
        with:
          version: 3.0.0-alpha4
          user-properties: prop=FooBar
          targets: foo
          verbose: true

The user-properties, targets and verbose options in that snippet are the interesting part, because they are the parameters you would otherwise pass on the command line, and the action is a wrapper that makes the same build file runnable from a workflow.

Phing 3 Changed the Ground Rules

There is a short section on Phing 3 that anyone evaluating the tool should read first, and it is two sentences.

Phing 3 is a significant update with some breaking changes compared to Phing 2, and the details are in the UPGRADING.md file in the repository. The supported PHP versions are given as well: Phing 3.x is compatible with PHP 8.1 or later.

Both points matter in practice. A build tool that changes its API between major lines means a team with an existing Phing 2 setup has a migration to plan, and a project that has to support PHP 8.0 or older cannot use the 3.x line at all. The version numbers in the release history show the pace, with 3.1.2 from 2026-02-06, 3.1.1 from 2025-12-21 and 3.1.0 from 2025-07-25, so the 3.1 line is where most of the recent work has landed.

The documentation is split in two, which is worth knowing before you search. The rendered documentation is at phing.info, and the source of the documentation lives in a separate repository, phingofficial/guide.

Running the Tests Locally Needs Three Extra Pieces

The section on running the unit tests lists the conditions that have to be met before the suite will pass, and two of them are unusual.

You need PEAR installed with the pear.phing.info channel discovered. You need the packages python-docutils and subversion installed. And you need the php.ini setting phar.readonly set to Off.

That list tells you something about the project. The PEAR channel requirement is a legacy of the Ant lineage, and the subversion package is needed because some of the tasks under test talk to Subversion, and the Python docutils package is there for the documentation generation tasks.

Once the environment is ready, the sequence is short:

composer install
cd tests
../bin/phing

The tests are themselves run by Phing, from the tests directory, using the bin/phing entry point rather than the installed Phar or the Composer binary. That is a nice touch for a project like this one, since the test suite is also a working example of a build file.

The rest of the contribution guidance is conventional and worth skimming. Issues should be searched before filing, support and installation questions belong on Twitter, Slack or IRC rather than in the tracker, and a good description including the steps to reproduce the problem is expected. Pull requests should squash commits and avoid unnecessary whitespace changes, and the source is formatted to the PSR-2 standard.

The Container Image and the Monorepo Build

The Dockerfile shows how the project builds itself, and it is a two stage build with a separate dependency stage.

The first stage is based on composer:2 and installs the dependencies with the optimised autoloader and the prefer-dist flag, and with the platform requirements ignored, which is what lets a single vendor directory serve the image regardless of the PHP version in the final stage.

The second stage is php:8.5-cli-alpine, and it installs the PHP extensions the tasks need: gettext, intl, sockets, tidy, xsl and zip. The extension list maps directly onto the task library, which is a tidy confirmation that the features in the README have real dependencies behind them.

Only the pieces the running tool needs are copied into the final image: the bin/phing entry point, the src/ and etc/ directories, and the vendor directory from the Composer stage. The entry point is bin/phing, so the image runs as a build tool rather than as a shell.

The repository is arranged for a monorepo build, with a monorepo-builder.php script at the root, a build/ directory, a src/ directory for the library, an etc/ directory for the shipped configuration, and the property files that let you register custom task and type classes, custom.task.properties and custom.type.properties. The static analysis and style tooling is configured too, with phpstan.neon for the analyser and .php-cs-fixer.dist.php for the formatter, plus a CHANGELOG.md, a CREDITS.md, a SECURITY.md and an UPGRADING.md.

The project is licensed under LGPL-3.0, the licence file is in the repository, and the maintainer is Michiel Rook, who takes donations through Patreon, Flattr, PayPal and an Amazon wishlist.

Editorial conclusion

phing fits a PHP team that wants one declarative build file for tests, asset transformation, database steps and deployment, and that prefers XML over a shell script or a PHP script with side effects. It is a poor fit if you are moving to a modern PHP toolchain, since Phing 3 is a significant update with breaking changes against Phing 2 and the maintenance of the project is the responsibility of a single maintainer. Before adopting it, read UPGRADING.md, check that your PHP version is 8.1 or newer, and note that running the test suite locally needs PEAR with the pear.phing.info channel, the python-docutils and subversion packages, and phar.readonly turned off in php.ini. The project is licensed LGPL-3.0, the newest release is 3.1.2 from 2026-02-06, and the last push was on 2026-10-15.

Frequently asked questions

Official sources

1. License: LGPL-3.0
2. phingofficial/phing on GitHub
3. Project website
4. README
5. Releases