B.23 ExecTask

Executes a shell command. You can use this to quickly add a new command to Phing. However, if you want to use this regularly, you should think about writing a Task for it.

The command attribute is no longer supported. You should now use a combination of the executable attribute and arg nested elements:

<exec command="echo foo"/>
<!-- should become -->
<exec executable="/bin/echo">
    <arg value="foo"/>
</exec>

Where it was once possible to pipe the output of one program to be the input of another using the command attribute: <exec command="echo FLUSHALL | redis-cli"> This must now be done using a combination of the executable and line attributes, thus: <exec executable="bash" line="echo FLUSHALL | redis-cli">

Table B.23: Attributes

NameTypeDescriptionDefaultRequired
executable String The command to execute without any command line arguments.n/a 
dir String The directory the command is to be executed in.n/aNo
output String Where to direct stdout.n/aNo
error String Where to direct stderr.Redirected to stdout, unless passthru is set to true. No
os String Only execute if the Appendix A, Fact Sheet property contains specified text. n/aNo
osfamily String OS family as used in the <os> condition.n/aNo
escape Boolean By default, we escape shell metacharacters before executing. Setting this to false will disable this precaution. false No
passthru Boolean Whether to use PHP's passthru() function instead of exec(). false No
logoutput Boolean Whether to log returned output as MSG_INFO instead of MSG_VERBOSE. false No
spawn Boolean Whether to spawn unix programs to the background, redirecting stdout. false No
returnProperty String Property name to set return value to from exec() call.n/aNo
outputProperty String Property name to set output value to from exec() call.n/aNo
checkreturn Boolean Whether to check the return code of the program, throws a BuildException when returncode != 0. false No
level String Control the level at which status messages are reported. One of error, warning, info, verbose, debug. verbose No
resolveexecutable Boolean When this attribute is true, the name of the executable is resolved firstly against the project basedir and if that does not exist, against the execution directory if specified. On Unix systems, if you only want to allow execution of commands in the user's path, set this to false. false No
searchpath Boolean When this attribute is true, then system path environment variables will be searched when resolving the location of the executable. false No

B.23.1 Examples

<!-- List the contents of "/home" using the executable attribute -->
<exec executable="ls" passthru="yes">
  <arg value="-l"/>
  <arg path="/home"/>
</>

<!-- List the contents of "/home", but only if on Linux -->
<exec executable="ls" passthru="yes" os="Linux">
  <arg value="-l"/>
  <arg path="/home"/>
</>

<!-- Demonstrate executable attribute and environment variables. -->
<exec executable="php" outputProperty="outputProperty">
    <env key="HELLO" value="hello"/>
    <env key="WORLD" value="world"/>
      <arg value="-r"/>
    <arg value="print getEnv('HELLO') . ' ' . getEnv('WORLD');"/>
</exec>

<!-- Demonstrate piping outputs from one command to another using the executable attribute. -->
<exec executable="bash">
    <arg value="-c"/>
    <arg line='"java -jar test.jar page.xml | mysql -u user -p base"'/>
</exec>

<!-- Restart some docker service -->
<exec executable="docker">
    <arg line="--debug restart ${service.name}"/>
</exec>

<!-- List the contents of "/tmp" out to a file. -->
<exec executable="ls" escape="false">
    <arg line="-l /tmp > foo.out"/>
</exec>

B.23.2 Supported Nested Tags

  • arg

    Table B.24: Attributes

    NameTypeDescriptionDefaultRequired
    value String A single command-line argument; can contain space characters. To pass an empty argument, enclose two double quotes in single quotes ('""'). n/aOne of these
    file String The name of a file as a single command-line argument; will be replaced with the absolute filename of the file. n/a
    path String A string that will be treated as a path-like string as a single command-line argument; you can use ; or : as path separators and Phing will convert it to the platform's local conventions. n/a
    line String A space-delimited list of command-line arguments. n/a
    escape Boolean Force escape for this attribute. false  


    env

    It is possible to specify environment variables to pass to the system command via nested <env> elements.

    Table B.25: Attributes

    NameTypeDescriptionDefaultRequired
    key String The name of the environment variable.n/aYes
    value String The literal value for the environment variable.n/aOne of these
    file String The value for the environment variable. Will be replaced by the absolute filename of the file by Phing. n/a
    path String The value for a PATH like environment variable. You can use ; or : as path separators and Phing will convert it to the platform's local conventions. n/a