# tasks/system/ExecTask.php

$Id: ExecTask.php 1244 2011-07-29 21:38:51Z mrook $

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This software consists of voluntary contributions made by many individuals and is licensed under the LGPL. For more information please see http://phing.info.

## \ExecTask
jump to top

Package: phing\tasks\system

Executes a command on the shell.

Use {@link Project#createTask} to register a new Task.

Parent(s)
  \Task < \ProjectComponent
Author
  Andreas Aderhold
Author
  Hans Lellelid
Author
  Christian Weiske
Copyright
  2001,2002 THYRELL. All rights reserved
Version
  $Revision: 1244 $

### Properties

`boolean $checkreturn= 'false'`

Whether to check the return code.

Default value `false` Details

Type
  boolean

`string $command= ''`

Command to execute.

Details

Type
  string

`\Commandline $commandline= ''`

Commandline managing object

Details

Type
  \Commandline

`string $description= ''`
inherited

description of the taskInherited from: \Task::$description
Details

Type
  string
Inherited_from
  \Task::$description

`\PhingFile $dir= ''`

Working directory.

Details

Type
  \PhingFile

`\File $error= ''`

Where to direct error output.

Details

Type
  \File

`boolean $escape= 'false'`

Whether to escape shell command using escapeshellcmd().

Default value `false` Details

Type
  boolean

`\Location $location= ''`
inherited

stored buildfile locationInherited from: \Task::$location
Details

Type
  \Location
Inherited_from
  \Task::$location

`integer $logLevel= 'Project::MSG_VERBOSE'`

Logging level for status messages

Default value `Project::MSG_VERBOSE` Details

Type
  integer

`boolean $logOutput= 'false'`

Whether to log returned output as MSG_INFO instead of MSG_VERBOSE

Default value `false` Details

Type
  boolean

`string $os= ''`

Operating system.

Details

Type
  string

`\File $output= ''`

Where to direct output.

Details

Type
  \File

`string $outputProperty= ''`

Property name to set with output value from exec call.

Details

Type
  string

`boolean $passthru= 'false'`

Whether to use PHP's passthru() function instead of exec()

Default value `false` Details

Type
  boolean

`\Project $project= 'null'`
inherited

Holds a reference to the project that a project component (a task, a target, etc.) belongs to

A reference to the current project instanceInherited from: \ProjectComponent::$project
Default value `null` Details

Type
  \Project
Inherited_from
  \ProjectComponent::$project

`string $returnProperty= ''`

Property name to set with return value from exec call.

Details

Type
  string

`boolean $spawn= 'false'`

If spawn is set then [unix] programs will redirect stdout and add '&'.

Default value `false` Details

Type
  boolean

`\Target $target= ''`
inherited

owning Target objectInherited from: \Task::$target
Details

Type
  \Target
Inherited_from
  \Task::$target

`string $taskName= ''`
inherited

Taskname for loggerInherited from: \Task::$taskName
Details

Type
  string
Inherited_from
  \Task::$taskName

`string $taskType= ''`
inherited

internal taskname (req)Inherited from: \Task::$taskType
Details

Type
  string
Inherited_from
  \Task::$taskType

`\RuntimeConfigurable $wrapper= ''`
inherited

wrapper of the taskInherited from: \Task::$wrapper
Details

Type
  \RuntimeConfigurable
Inherited_from
  \Task::$wrapper

### Methods

`__construct( ) : void`

`buildCommand( ) : void`

Builds the full command to execute and stores it in $command.

Details

Uses
  \$command

`cleanup( integer $return, array $output ) : void`

Runs all tasks after command execution: - change working directory back - log output - verify return value

Parameters

Name | Type | Description
--- | --- | ---
$return | integer | Return code
$output | array | Array with command output

`createArg( ) : \CommandlineArgument`

Creates a nested tag.

Returns

Type | Description
--- | ---
\CommandlineArgument | Argument object

`executeCommand( ) : array`

Executes the command and returns return code and output.

Returns

Type | Description
--- | ---
array | array(return code, array with output)

`getDescription( ) : string`
inherited

Returns the textual description of the task

Inherited from: \Task::getDescription()
Returns

Type | Description
--- | ---
string | The text description of the task

`getLocation( ) : \Location`
inherited

Returns the location within the buildfile this task occurs. Used by {@link BuildException} to give detailed error messages.

Inherited from: \Task::getLocation()
Returns

Type | Description
--- | ---
\Location | The location object describing the position of this task within the buildfile.

`getOwningTarget( ) : \Target`
inherited

Returns the owning target of this task.

Inherited from: \Task::getOwningTarget()
Returns

Type | Description
--- | ---
\Target | The target object that owns this task

`getProject( ) : \Project`
inherited

Returns a reference to current project

Inherited from: \ProjectComponent::getProject()
Returns

Type | Description
--- | ---
\Project | Reference to current porject object

`getRegisterSlot( $slotName ) : void`
inherited

Returns a name

Inherited from: \Task::getRegisterSlot()
Parameters

Name | Type | Description
--- | --- | ---
$slotName |  |

`getRuntimeConfigurableWrapper( ) : \RuntimeConfigurable`
inherited

Returns the wrapper object for runtime configuration

Inherited from: \Task::getRuntimeConfigurableWrapper()
Returns

Type | Description
--- | ---
\RuntimeConfigurable | The wrapper object used by this task

`getTaskName( ) : string`
inherited

Returns the name of task, used only for log messages

Inherited from: \Task::getTaskName()
Returns

Type | Description
--- | ---
string | Name of this task

`getTaskType( ) : string`
inherited

Returns the name of the task under which it was invoked, usually the XML tagname

Inherited from: \Task::getTaskType()
Returns

Type | Description
--- | ---
string | The type of this task (XML Tag)

`init( ) : void`
inherited

Called by the parser to let the task initialize properly.

Inherited from: \Task::init()

Should throw a BuildException if something goes wrong with the build

This is abstract here, but may not be overloaded by subclasses.

Throws

Exception | Description
--- | ---
\BuildException |

`isApplicable( ) : boolean`

Checks whether the command shall be executed

Returns

Type | Description
--- | ---
boolean | False if the exec command shall not be run

`log( string $msg, integer $level = Project::MSG_INFO ) : void`
inherited

Provides a project level log event to the task.

Inherited from: \Task::log()

@param string $msg The message to be logged.

Parameters

Name | Type | Description
--- | --- | ---
$msg | string | The message to log
$level | integer | The priority of the message

Details

See
  \BuildEvent
See
  \BuildListener

`main( ) : void`

Main method: wraps execute() command.

Should throw a BuildException if someting goes wrong with the build

This is abstract here. Must be overloaded by real tasks.

`maybeConfigure( ) : void`
inherited

Configure this task if it hasn't been done already.

Inherited from: \Task::maybeConfigure()
`perform( ) : void`
inherited

Perfrom this task

Inherited from: \Task::perform()
`prepare( ) : void`

Prepares the command building and execution, i.e.

changes to the specified directory.

`setCheckreturn( boolean $checkreturn ) : void`

Whether to check the return code.

Parameters

Name | Type | Description
--- | --- | ---
$checkreturn | boolean | If the return code shall be checked

`setCommand( mixed $command ) : void`

The command to use.

Parameters

Name | Type | Description
--- | --- | ---
$command | mixed | String or string-compatible (e.g. w/ __toString()).

`setDescription( string $desc ) : void`
inherited

Sets a textual description of the task

Inherited from: \Task::setDescription()
Parameters

Name | Type | Description
--- | --- | ---
$desc | string | The text describing the task

`setDir( \PhingFile $dir ) : void`

Specify the working directory for executing this command.

Parameters

Name | Type | Description
--- | --- | ---
$dir | \PhingFile | Working directory

`setError( \PhingFile $f ) : void`

File to which error output should be written.

Parameters

Name | Type | Description
--- | --- | ---
$f | \PhingFile | Error log file

`setEscape( boolean $escape ) : void`

Whether to use escapeshellcmd() to escape command.

Parameters

Name | Type | Description
--- | --- | ---
$escape | boolean | If the command shall be escaped or not

`setExecutable( mixed $executable ) : void`

The executable to use.

Parameters

Name | Type | Description
--- | --- | ---
$executable | mixed | String or string-compatible (e.g. w/ __toString()).

`setLevel( string $level ) : void`

Set level of log messages generated (default = verbose)

Parameters

Name | Type | Description
--- | --- | ---
$level | string | Log level

`setLocation( \Location $location ) : void`
inherited

Sets the location within the buildfile this task occurs. Called by the parser to set location information.

Inherited from: \Task::setLocation()
Parameters

Name | Type | Description
--- | --- | ---
$location | \Location | The location object describing the position of this task within the buildfile.

`setLogoutput( boolean $logOutput ) : void`

Whether to log returned output as MSG_INFO instead of MSG_VERBOSE

Parameters

Name | Type | Description
--- | --- | ---
$logOutput | boolean | If output shall be logged visibly

`setOs( string $os ) : void`

Specify OS (or muliple OS) that must match in order to execute this command.

Parameters

Name | Type | Description
--- | --- | ---
$os | string | Operating system string (e.g. "Linux")

`setOutput( \PhingFile $f ) : void`

File to which output should be written.

Parameters

Name | Type | Description
--- | --- | ---
$f | \PhingFile | Output log file

`setOutputProperty( string $prop ) : void`

The name of property to set to output value from exec() call.

Parameters

Name | Type | Description
--- | --- | ---
$prop | string | Property name

`setOwningTarget( \Target $target ) : void`
inherited

Sets the owning target this task belongs to.

Inherited from: \Task::setOwningTarget()
Parameters

Name | Type | Description
--- | --- | ---
$target | \Target | Reference to owning target

`setPassthru( boolean $passthru ) : void`

Whether to use PHP's passthru() function instead of exec()

Parameters

Name | Type | Description
--- | --- | ---
$passthru | boolean | If passthru shall be used

`setProject( \Project $project ) : void`
inherited

References the project to the current component.

Inherited from: \ProjectComponent::setProject()
Parameters

Name | Type | Description
--- | --- | ---
$project | \Project | The reference to the current project

`setReturnProperty( string $prop ) : void`

The name of property to set to return value from exec() call.

Parameters

Name | Type | Description
--- | --- | ---
$prop | string | Property name

`setRuntimeConfigurableWrapper( \RuntimeConfigurable $wrapper ) : void`
inherited

Sets the wrapper object this task should use for runtime configurable elements.

Inherited from: \Task::setRuntimeConfigurableWrapper()
Parameters

Name | Type | Description
--- | --- | ---
$wrapper | \RuntimeConfigurable | The wrapper object this task should use

`setSpawn( boolean $spawn ) : void`

Whether to suppress all output and run in the background.

Parameters

Name | Type | Description
--- | --- | ---
$spawn | boolean | If the command is to be run in the background

`setTaskName( $name ) : string`
inherited

Sets the name of this task for log messages

Inherited from: \Task::setTaskName()
Parameters

Name | Type | Description
--- | --- | ---
$name |  |

Returns

Type | Description
--- | ---
string | A string representing the name of this task for log

`setTaskType( string $name ) : void`
inherited

Sets the type of the task. Usually this is the name of the XML tag

Inherited from: \Task::setTaskType()
Parameters

Name | Type | Description
--- | --- | ---
$name | string | The type of this task (XML Tag)

Documentation was generated by DocBlox 0.15.1.