.build.php Files

Custom .build.php files can be added to any directory in a project. Files by that name are executed automatically by the Phing build system. These allow you to run additional custom build routines via PHP scripts of your own.

Special File Name

Name your custom script: .build.php

Files by that name can be dropped into any directory, in as many places as you need them. For example, if a specific directory contains files that need an additional custom build process (i.e., you need to do something special with those files), you can simply add a .build.php file to that directory and build whatever automation is needed using a PHP script that you write yourself.

Controlling Build Execution Phase

Understanding Build Phases

There are basically two build phases handled by our Phing build system:

1. There are builds that occur in the base project directory; i.e., in the Git repo directory itself. For example, whenever you do an official release, version numbers get bumped. Those versions are bumped in the project's base directory so that changes in the version number will get pushed back to the remote GitHub repo.

Note: File system changes that occur in this build phase also affect the second build phase, because changes in the base directory are always propagated a split second later, to the second build phase, as described below.

2. In the second build phase, there are routines that run only in the .~build directory; i.e., a temporary directory that is manipulated just prior to packaging a distributable .zip, .tar.gz, or .phar file. For example, there are build routines that run in this phase which strip away files that are not needed in an official distro.

Execution Phase in .build.php Files

So there are two build phases. One in the base directory. Another in the build directory. By default, .build.php files run in both phases, which is usually NOT desirable, or necessary. So you'll want to control which phase your custom .build.php files run in.

File Names that Control Execution Phase

• .build.in-base-dir.php will run only in the base directory build phase.
• .build.in-build-dir.php runs only in the .~build directory phase.

In short, name your file in a way that dictates which phase it should run in.

Prioritizing Build Files

Sometimes you'll write multiple .build.php files. Perhaps you'd like to execute those files in a specific order. For example, maybe you have one .build.php file that does something to the file system, and the next .build.php file does something else. The second one depends on the first one being completed already.

Prioritized .build.php files are accomplished using a numbered format. Instead of .build.in-base-dir.php, you can use .build.in-base-dir.1.php, .build.in-base-dir.2.php, .build.in-base-dir.3.php, etc.

Prioritized build files must use a .[number] notation; i.e., a dash (-[number]) will not work. Use the .[number] notation so that your numbered build files are also excluded properly from any final distro that is generated by the Phing build system.

Note: A numbered sequence currently requires that you also add the phase. i.e., .build.1.php does not work. But .build.in-base-dir.1.php does work, as does .build.in-build-dir.1.php, .build.in-build-dir.2.php, .build.in-build-dir.3.php, etc.

Tip: The numbered format is ordered automatically by an underlying directory scan. If you have more than nine, be sure to pad them with a zero so that a natural sort order comes out like you'd expect it to.

• .build.in-base-dir.01.php
• .build.in-base-dir.02.php
• .build.in-base-dir.03.php
• .build.in-base-dir.04.php
• .build.in-base-dir.05.php
• .build.in-base-dir.06.php
• .build.in-base-dir.07.php
• .build.in-base-dir.08.php
• .build.in-base-dir.09.php
• .build.in-base-dir.10.php
• .build.in-base-dir.11.php
• etc, etc. Up to 99 build files.