phing

Using Phing on a Mac OS X console sometimes has a strange result: While the Phing script runs correctly, the console displays nothing. The reason for this is that the ANSI color codes used by some versions of Phing are not supported by OS X.

The solution is simple. Change the output logger.

$ phing -logger phing.listener.DefaultLogger ftest

This will use a non-colorized logger.

I'm upgrading to Snow Leopard, and I intend to switch from MAMP to the built-in PHP/Apache 2 configuration. As a PHP developer, there are several notable things that I wanted to track as I performed my upgrades. This article tracks those changes

PHP 5.3
My current OS 10.5 toolchain for PHP was this:

• PHP 5.2.6 (MAMP)
• Apache 2 (MAMP)
• MySQL 5 (MAMP)
• TextMate
• Git
• XDebug
• Several PEAR packages installed into MAMP's PHP 5, including PHPUnit, PhpDocumentor, Phing, and XDebug

One of the desired outcomes was to switch to the OS X version of PHP and Apache, which is tenable now that PHP is more robust (and now that I know how to use PEAR with the OS X version). It's also desirable because Snow Leopard is now running PHP 5.3. Here are my notes on the upgrade.

Update: Problems with PHPUnit and Phing.

Out of the box, Phing provides numerous features for creating high-powered source code management scripts. In an earlier post, I talked about metaprogramming in Phing, merely scratching the surface of what Phing can do. In this article, I want to illustrate how easy it is to extend Phing.

Phing can move, copy, package, unpackage, modify, touch, and delete files. But one thing it can't do out of the box is download files. In this short article, I will illustrate how easy it is to build a new Phing task to download a file from an arbitrary URL.

The desired goal it to make it possible to write a phing task that looks like this (in the build.xml):

  <download url="http://example.com/mypackage.tgz" tofile="SomeFile.tgz"/>

This task, when executed, should download the package from the target url and, if tofile is set, store the file with the name given there.

Doing this is going to involve two parts:

• Writing the task in PHP.
• Telling Phing, in the build.xml, where the new task is.

The first part is the harder of the two... it'll take a couple dozen lines of very basic code.

There are a handful of PHP development tools that I find myself using project after project. One of them is Phing, a PHP-centered build tool similar to Ant, rake, or GNU Make.

The primary purpose of Phing is to make it easy for PHP developers to write build scripts for our applications. If you are familiar with Ruby on Rails, you might compare this to rake's usage. rake makes it easy to manage your Rails application. You can rebuild the database, start and stop the webserver, and so on from within rake.

Phing uses a declarative XML language to create targets (commands you can run) that are composed of tasks (individual steps for each command). Phing is built entirely in PHP, and is easily extended. Even without writing a line of PHP, you can squeeze a seemingly endless number of tasks out of a Phing script.

Here are some common tasks I use Phing for in my PHP projects. The first four meet some common needs. The last one is by far the coolest, though.

1. Let Phing catch your typos.
2. Automate Your Automated Testing.
3. Let Phing Write Your Documentation
4. Package Your Applications
5. Build Your Own Toolchain

I have recently converted some of my PHP projects over to use the awesome Phing build tool. Phing is similar to Apache Ant, a tool I am familiar with from my Java development days. I have crafted Phing's build.xml for QueryPath to handle building packages, generating API docs, running coverage analyses, linting, and (of course) running QueryPath's ~250 tests.

Having left IDEs behind for the time being, I have been working hard to build an personalized toolchain for PHP development. I've settled on TextMate as my editor (though I still use vim quite often). One thing I wanted to be able to do is run unit tests from within TextMate.

Initially I built a shell script to run the unit tests. But after moving to Phing, it seemed like it should be possible to take advantage of Phing's unit test running abilities (and lovely HTML output) from within TextMate. Working this out took two major stages:

1. Writing a custom target in Phing's build.xml
2. Creating a simple TextMate bundle for running Phing tasks

This article shows how to accomplish each of these steps.

This short article explains how Phing and phpDocumentator can be used together to merge DocBook XML tutorials into generated API documentation.

The Phing build tool provides a suite of powerful utilities for managing your PHP projects. One of the things Phing can do is use phpDocumentor to generate documentation for source code.

A not-often-used feature of phpDocumentor is its built-in support for add-on tutorials. phpDocumentor can take tutorials stored in DocBook XML and merge them into the set of documentation that phpDocumentor builds from source code. DocBook XML for phpDocumentor typically looks something like this (a seriously trimmed example pulled from QueryPath):

tutorials/QueryPath/QueryPath.pkg

<?xml version="1.0"?>
<refentry id="{@id}">
 <refnamediv>
  <refname>Using QueryPath</refname>
  <refpurpose>How to make the most of the QueryPath library.</refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <author>
   Matt Butcher
   <authorblurb>
    {@link <a href="http://querypath.org" title="http://querypath.org">http://querypath.org</a> Project Founder}
    {@link http://queryPath.org}
   </authorblurb>
  </author>
 </refsynopsisdiv>
 {@toc}
 <refsect1 id="{@id intro}">
  <title>About QueryPath</title>
  <para>
    QueryPath is a library designed to help you quickly and efficiently search,
    modify, and traverse XML and HTML documents. It is built on an interface with
    functions similar to what is found in {@link <a href="http://jquery.com" title="http://jquery.com">http://jquery.com</a> jQuery}. However,
    it is optimized for server-side work.
  </para>
  <para>
   The user guide for QueryPath is located in the 
   {@link <a href="http://api.querypath.org/" title="http://api.querypath.org/">http://api.querypath.org/</a> official site}. 
  </para>
  <para>
    Ready to get going? Start with the <emphasis>{@link qp()}</emphasis> function. Along with the 
    basic documentation, there are several examples linked from that function.
  </para>
 </refsect1>
</refentry>

The file above provides a basic introduction to the QueryPath library. It is in DocBook XML as described in the phpDocumentor documentation. We want to take the XML document above and have it integrated automatically into our API documentation.

Phing, the build tool, provides a target for generating source code documentation using phpDocumentor. One thing that is not obvious, though, is how Phing can generate tutorials.

Here's an example target configuration (an excerpt from a larger build.xml) that shows how the tutorials directory can be included in the phpDocumentor call. Tutorials included this way will automatically be read, parsed, and included in the generated documentation:

<target name="doc">
    <phpdoc title="My API Docs"
      sourcecode="yes"
      destdir="docs"
      output="HTML:Smarty:QueryPath"
      >
      <fileset dir="./src">
        <include name="<strong>/*.php"/>
      </fileset>
      <fileset dir="./tutorials">
        <include name="</strong>/*"/>
      </fileset>
      <projdocfileset dir=".">
        <include name="README"/>
        <include name="INSTALL"/>
      </projdocfileset>
    </phpdoc>
  </target>

The above shows a complete documentation build of a project. In the example above, the main source code is stored in a src/ directory, and all of the tutorials are stored in a tutorials/ directory. Of particular interest is this little section:

      <fileset dir="./tutorials">
        <include name="**/*"/>
      </fileset

This section instructs phpDocumentor to add the tutorials/ directory to the list of directories and files that phpDocumentor will process. The additional include element instructs phpDocumentor to include all subdirectories (**, and all files in each subdirectory (/*).

Based on this Phing instruction, phpDocumentor will analyze the tutorial DocBook XML files and generate HTML files, which it will link into the generated documentation.

Examples, too, can be added in a way similar to the method employed for tutorials. phpDocumentor can parse example PHP files -- files that illustrate how the library is to be used -- and include those files in the generated documentation. Should you want to add those, here is how you can do so:

    <fileset dir="./examples">
      <include name="**/*.php"/>
    </fileset>

Since examples are typically PHP files, phpDocumentor will process them just as it does any other PHP files.

Phing and phpDocumentor together provide a powerful method of automatically generating API documentation for PHP projects. In this short article, we have seen how tutorial documentation can be included in generated documentation.