/
[console] Make Phing (build tool) usage less painful [5.3.0-B1]

[console] Make Phing (build tool) usage less painful [5.3.0-B1]

Owned by Alex
Last updated: Oct 04, 2015

The Phing (see https://www.phing.info/) is one of many automation tools used by In-Portal. In particular Phing scripts are being used on http://ci.in-portal.org/ website (Front-End of Jenkins build server) to run these any many other tasks on code changed in every commit:

  • apply recent database schema/data changes to sample database used on build server
  • generate API documentation by scanning the code
  • run deployment scripts
  • confirm, that changed PHP doesn't contain any syntax errors
  • record statistics about code style violations (via PHP_CodeSniffer and PHP Mess Detector tools)
  • measure code size (via PhpLoc tool)
  • run unit tests (via PHPUnit)

It might seem at first, that described actions only makes sense in build server context, but some of them (e.g. unit test running and code checking) are also quite useful when executed on developer machine as well.

Each action, that can be invoked in Phing is called a target. Currently it's possible to execute any of Phing targets using following command:

phing -f tools/build/build_custom.xml target_name

The above command will execute "target_name" target using "tools/build/build_custom.xml" build file located in root of In-Portal installation. The problem with above command is not only its length, but also fact, that:

  • the build file needs to be specified each time
  • different build file (the "tools/build/build_all.xml") needs to be used by In-Portal developers in comparison to "Development Kit" module developers

The next pain point comes in, when some targets require path to be specified in order to work. For example the "phpcbf" target (that automatically fixes coding standards) requires path in order to fix only particular file. In that case command will look like this:

phing -f tools/build/build_custom.xml phpcbf -Dscan.dir=\${base.dir}/modules/custom/units/sections/orders/e_order_eh.php

That surely isn't an easy command to remember with all these $ escaping and "scan.dir" stuff.

Solution

Thanks to Symfony Console package usage we can add "phing:run <target_name> <path>" command, that will work like this:

  • when "target_name" argument is specified, then execute given target on default path (folder)
  • when both "target_name" and "path" arguments are specified, then execute given target on given path (file or folder)
  • when neither of above arguments are specified, then list possible targets with their descriptions (by scanning the Phing build file)

On first run the command will ask user to specify a build file location by listing available build files from "/tools/build/" folder. Of course full auto-complete support will be added to auto-complete each argument possible values.

Example output of "in-portal phing-run" command:

Example output of "in-portal phing-run lint" command:

Of course developers needs to learn how to interpret Phing build script output, but that not a big problem compared to the benefits, which introduced "phing:run" command will bring to them.

Related Tasks

INP-1494 - Getting issue details... STATUS