Getting Time And Date Values In Phing

The tstamp task in Phing can be used to generate a timestamp that can be used anywhere within the current project. The default behaviour of tstamp is to create the properties DSTAMP, TSTAMP and TODAY, which contain time and date values. All you need to do is include the tstamp XML tag in your project somewhere.

<tstamp>
</tstamp>

The properties DSTAMP, TSTAMP and TODAY use the PHP strftime() function as a basis for formatting the time. The following table shows the value of each property.

Once you have added the tstamp XML tag you can then access these properties in any way you want. The following target defines the tstamp tag and then prints out the values of the three properties.

<target name="tstamp">

    <tstamp>

    <echo>DSTAMP = ${DSTAMP}</echo>
    <echo>TSTAMP = ${TSTAMP}</echo>
    <echo>TODAY = ${TODAY}</echo>  
</tstamp></target>

When run this prints out the following:

build > printtime:

     [echo] DSTAMP = 20110610
     [echo] TSTAMP = 1125
     [echo] TODAY = June 10 2011

I you wanted to add a prefix to these properties then you can do by using the prefix attribute of the tstamp property. Any value you add here will be required to access any of the tstamp properties. For example, if the prefix is set to "mytime" then the DSTAMP property needs to be accessed via "mytime.DSTAMP". The following is an example of all three parameters being accessed in this manner.

<target name="prefixtstamp">
    <tstamp prefix="mytime"> 

    <echo>DSTAMP = ${mytime.DSTAMP}</echo>
    <echo>TSTAMP = ${mytime.TSTAMP}</echo>
    <echo>TODAY = ${mytime.TODAY}</echo>
</tstamp></target>

When creating a tstamp element it is also possible to create a custom tstamp property with a custom format. To do this you create a tstamp element with a child format element. The property attribute defines the name of the property to set and the pattern property sets the pattern of the time stamp. This pattern of this format is the same as detailed on the strftime() manual page. The following sets the DATE parameter to be %c, which is the preferred date and time stamp based on local.

<target name="format">
    <tstamp>
        <format pattern="%c" property="DATE">
    </format></tstamp>

    <echo>DATE = ${DATE}</echo>
</target>

This produces the following output.

build > format:

     [echo] DATE = Fri Jun 10 21:53:06 2011

The property name of the format element can also be changed via the use of the prefix attribute on the tstamp element.

It is also possible to override one of the default tstamp property names using the format element. It is important to note here that overriding will only work if the tstamp element hasn't already been used. The following example shows a failiure of overriding the tstamp property TSTAMP as the tstamp element has already been used. This example would produce the correct output if the first tstamp element was removed.

<target name="overridefail">
    <tstamp>

    <tstamp>
        <format pattern="%c" property="TSTAMP">
    </format></tstamp>

    <echo>TSTAMP = ${TSTAMP}</echo>    
</tstamp></target>

You can also set the locale of the formatted time so that it is translated into region specific formats. The locale strings are the same as can be passed to the PHP setlocale() function. This function depends heavily on the server and platform configuration, but it will always default back to the system language if the locale string isn't recognised. The following example sets the locale to the Spainish language (within Spain) and formats the date to include some day and month names to fully display the different language.

<target name="formatspanish">
    <tstamp>
        <format locale="Spanish_Spain" pattern="%A %d %B (%c)" property="SpanishDate">
    </format></tstamp>

    <echo>SpanishDate = ${SpanishDate}</echo>
</target>

The output of this function is as follows:

build > formatspanish:

     [echo] SpanishDate = viernes 10 junio (vie 10 jun 2011 20:27:23 BST)

I should note that the above settings "spanish_Spain" is from a Windows environment. For an Ubuntu linux environment I had to install the appropriate language pack and then change the above locale string to the following: