CollectionBuilder
class CollectionBuilder extends BaseTask implements NestedCollectionInterface, WrappedTaskInterface, CommandInterface, StateAwareInterface, InputAwareInterface (View source)
Creates a collection, and adds tasks to it. The collection builder offers a streamlined chained-initialization mechanism for easily creating task groups. Facilities for creating working and temporary directories are also provided.
<?php
$result = $this->collectionBuilder()
->taskFilesystemStack()
->mkdir('g')
->touch('g/g.txt')
->rollback(
$this->taskDeleteDir('g')
)
->taskFilesystemStack()
->mkdir('g/h')
->touch('g/h/h.txt')
->taskFilesystemStack()
->mkdir('g/h/i/c')
->touch('g/h/i/i.txt')
->run()
?>
In the example above, the `taskDeleteDir` will be called ifTraits
Task input/output methods. TaskIO is 'used' in BaseTask, so any task that extends this class has access to all of the methods here.
Task input/output methods. TaskIO is 'used' in BaseTask, so any task that extends this class has access to all of the methods here.
Properties
| protected ConfigInterface | $config | from ConfigAwareTrait | |
| protected OutputAdapterInterface | $outputAdapter | from VerbosityThresholdTrait | |
| protected int | $verbosityThreshold | from VerbosityThresholdTrait | |
| protected OutputInterface | $output | from OutputAwareTrait | |
| protected TimeKeeper|null | $timer | from Timer | |
| protected null|ProgressIndicator | $progressIndicator | from ProgressIndicatorAwareTrait | |
| protected Data | $state | from StateAwareTrait | |
| protected InputInterface | $input | from InputAwareTrait | |
| protected Tasks | $commandFile | ||
| protected CollectionInterface | $collection | ||
| protected TaskInterface | $currentTask | ||
| protected bool | $simulated |
Methods
Any class that uses ConfigAwareTrait SHOULD override this method , and define a prefix for its configuration items. This is usually done in a base class. When used, this method should return a string that ends with a "."; see BaseTask::configPrefix().
No description
No description
No description
Print a message if the selected verbosity level is over this task's verbosity threshold.
Print information about a task in progress.
Provide notification that some part of the task succeeded.
Provide notification that there is something wrong, but execution can continue.
Provide notification that some operation in the task failed, and the task cannot continue.
Provide debugging notification. These messages are only displayed if the log level is VERBOSITY_DEBUG.
Get the formatted task name for use in task output.
Ask the provided parent class to inject all of the dependencies that it has and we need.
Take all dependencies availble to this task and inject any that are needed into the provided task. The general pattern is that, for every FooAwareInterface that this class implements, it should test to see if the child also implements the same interface, and if so, should call $child->setFoo($this->foo).
No description
No description
Create a temporary directory to work in. When the collection completes or rolls back, the temporary directory will be deleted.
Create a working directory to hold results. A temporary directory is first created to hold the intermediate results. After the builder finishes, the work directory is moved into its final location; any results already in place will be moved out of the way and then deleted.
Add arbitrary code to execute as a task.
Add a list of tasks to our task collection.
No description
No description
No description
Called by the factory method of each task; adds the current task to the task builder.
No description
No description
No description
No description
Return the current task for this collection builder.
Create a new builder with its own task collection
Calling the task builder with methods of the current task calls through to that method of the task.
Construct the desired task and add it to this builder.
Check to see if there are any setter methods defined in configuration for this task.
If there is a single task, run it; if there is a collection, run all of its tasks.
Returns command that can be executed.
No description
Return the collection of tasks associated with this builder.
Details
$this
setConfig(ConfigInterface $config)
Set the config management object.
ConfigInterface
getConfig()
Get the config management object.
static protected string
configPrefix()
Any class that uses ConfigAwareTrait SHOULD override this method , and define a prefix for its configuration items. This is usually done in a base class. When used, this method should return a string that ends with a "."; see BaseTask::configPrefix().
static protected
configClassIdentifier($classname)
No description
static protected
configPostfix()
No description
static
configure(string $key, mixed $value, ConfigInterface|null $config = null)
No description
protected mixed|null
getConfigValue(string $key, mixed|null $default = null)
No description
$this
setVerbosityThreshold(int $verbosityThreshold)
No description
int
verbosityThreshold()
No description
setOutputAdapter(OutputAdapterInterface $outputAdapter)
No description
OutputAdapterInterface
outputAdapter()
No description
bool
hasOutputAdapter()
No description
bool
verbosityMeetsThreshold()
No description
writeMessage(string $message)
Print a message if the selected verbosity level is over this task's verbosity threshold.
$this
setOutput(OutputInterface $output)
No description
protected OutputInterface
output()
No description
protected OutputInterface
stderr()
No description
protected OutputInterface
getOutput()
deprecated
deprecated
Backwards compatibility
in
TaskIO at line 49
null|LoggerInterface
logger()
deprecated
deprecated
No description
in
TaskIO at line 85
protected
printTaskInfo(string $text, null|array $context = null)
Print information about a task in progress.
With the Symfony Console logger, NOTICE is displayed at VERBOSITY_VERBOSE and INFO is displayed at VERBOSITY_VERY_VERBOSE.
Robo overrides the default such that NOTICE is displayed at VERBOSITY_NORMAL and INFO is displayed at VERBOSITY_VERBOSE.
n.b. We should probably have printTaskNotice for our ordinary output, and use printTaskInfo for less interesting messages.
protected
printTaskSuccess(string $text, null|array $context = null)
Provide notification that some part of the task succeeded.
With the Symfony Console logger, success messages are remapped to NOTICE, and displayed in VERBOSITY_VERBOSE. When used with the Robo logger, success messages are displayed at VERBOSITY_NORMAL.
protected
printTaskWarning(string $text, null|array $context = null)
Provide notification that there is something wrong, but execution can continue.
Warning messages are displayed at VERBOSITY_NORMAL.
protected
printTaskError(string $text, null|array $context = null)
Provide notification that some operation in the task failed, and the task cannot continue.
Error messages are displayed at VERBOSITY_NORMAL.
protected
printTaskDebug($text, null|array $context = null)
Provide debugging notification. These messages are only displayed if the log level is VERBOSITY_DEBUG.
protected
printTaskOutput(string $level, string $text, null|array $context)
deprecated
deprecated
No description
protected bool
hideTaskProgress()
No description
protected
showTaskProgress(bool $inProgress)
No description
protected string
formatBytes(int $size, int $precision = 2)
Format a quantity of bytes.
protected string
getPrintedTaskName(null|object $task = null)
Get the formatted task name for use in task output.
This is placed in the task context under 'name', and used as the log label by Robo\Common\RoboLogStyle, which is inserted at the head of log messages by Robo\Common\CustomLogStyle::formatMessage().
protected array
getTaskContext(null|array $context = null)
No description
in
Timer at line 12
protected
startTimer()
No description
in
Timer at line 20
protected
stopTimer()
No description
in
Timer at line 28
protected
resetTimer()
No description
in
Timer at line 36
protected float|null
getExecutionTime()
No description
int
progressIndicatorSteps()
No description
$this
setProgressIndicator(null|ProgressIndicator $progressIndicator)
No description
protected null|bool
hideProgressIndicator()
No description
protected
showProgressIndicator()
No description
protected
restoreProgressIndicator(bool $visible)
No description
protected int
getTotalExecutionTime()
No description
protected
startProgressIndicator()
No description
protected bool
inProgress()
No description
protected
stopProgressIndicator()
No description
protected
disableProgressIndicator()
No description
protected
detatchProgressIndicator()
No description
protected
advanceProgressIndicator(int $steps = 1)
No description
$this
inflect(InflectionInterface|mixed $parent)
Ask the provided parent class to inject all of the dependencies that it has and we need.
injectDependencies(mixed $child)
Take all dependencies availble to this task and inject any that are needed into the provided task. The general pattern is that, for every FooAwareInterface that this class implements, it should test to see if the child also implements the same interface, and if so, should call $child->setFoo($this->foo).
The benefits of this are pretty large. Any time an object that implements
InflectionInterface is created, just call $child->inflect($this), and
any available optional dependencies will be hooked up via setter injection.
The required dependencies of an object should be provided via constructor injection, not inflection.
Data
getState()
No description
setState(Data $state)
No description
setStateValue(int|string $key, mixed $value)
No description
updateState(Data $update)
No description
resetState()
No description
$this
setInput(InputInterface $input)
No description
protected InputInterface
input()
No description
protected InputInterface
getInput()
deprecated
deprecated
Backwards compatibility.
__construct(Tasks $commandFile)
No description
static CollectionBuilder
create(ContainerInterface $container, Tasks $commandFile)
No description
$this
simulated(bool $simulated = true)
No description
bool
isSimulated()
No description
string
tmpDir(string $prefix = 'tmp', string $base = '', bool $includeRandomPart = true)
Create a temporary directory to work in. When the collection completes or rolls back, the temporary directory will be deleted.
Returns the path to the location where the directory will be created.
string
workDir(string $finalDestination)
Create a working directory to hold results. A temporary directory is first created to hold the intermediate results. After the builder finishes, the work directory is moved into its final location; any results already in place will be moved out of the way and then deleted.
$this
addTask(TaskInterface $task)
No description
$this
addCode(callable $code, int|string $name = \Robo\Collection\CollectionInterface::UNNAMEDTASK)
Add arbitrary code to execute as a task.
$this
addTaskList(array $tasks)
Add a list of tasks to our task collection.
$this
rollback(TaskInterface $task)
No description
$this
rollbackCode(callable $rollbackCode)
No description
$this
completion(TaskInterface $task)
No description
$this
completionCode(callable $completionCode)
No description
$this
progressMessage(string $text, array $context = [], string $level = LogLevel::NOTICE)
No description
$this
setParentCollection(NestedCollectionInterface $parentCollection)
No description
$this
addTaskToCollection(TaskInterface $task)
Called by the factory method of each task; adds the current task to the task builder.
TODO: protected
$this
storeState(int|string $key, mixed $source = '')
No description
$this
deferTaskConfiguration(string $functionName, int|string $stateKey)
No description
$this
defer($callback)
No description
protected $this
callCollectionStateFunction(string $functionName, array $args)
No description
protected $this
callCollectionStateFuntion(string $functionName, array $args)
deprecated
deprecated
No description
TaskInterface
getCollectionBuilderCurrentTask()
Return the current task for this collection builder.
TODO: Not needed?
CollectionBuilder
newBuilder()
Create a new builder with its own task collection
$this|mixed
__call(string $fn, array $args)
Calling the task builder with methods of the current task calls through to that method of the task.
There is extra complexity in this function that could be simplified if we attached the 'LoadAllTasks' and custom tasks to the collection builder instead of the RoboFile. While that change would be a better design overall, it would require that the user do a lot more work to set up and use custom tasks. We therefore take on some additional complexity here in order to allow users to maintain their tasks in their RoboFile, which is much more convenient.
Calls to $this->collectionBuilder()->taskFoo() cannot be made directly because all of the task methods are protected. These calls will therefore end up here. If the method name begins with 'task', then it is eligible to be used with the builder.
When we call getBuiltTask, below, it will use the builder attached to the commandfile to build the task. However, this is not what we want: the task needs to be built from THIS collection builder, so that it will be affected by whatever state is active in this builder. To do this, we have two choices: 1) save and restore the builder in the commandfile, or 2) clone the commandfile and set this builder on the copy. 1) is vulnerable to failure in multithreaded environments (currently not supported), while 2) might cause confusion if there is shared state maintained in the commandfile, which is in the domain of the user.
Note that even though we are setting up the commandFile to use this builder, getBuiltTask always creates a new builder (which is constructed using all of the settings from the commandFile's builder), and the new task is added to that. We therefore need to transfer the newly built task into this builder. The temporary builder is discarded.
$this
build(string|object $name, array $args)
Construct the desired task and add it to this builder.
protected CompletionWrapper|Simulator
fixTask(TaskInterface $task, array $args)
No description
protected
configureTask(string $taskClass, TaskInterface $task)
Check to see if there are any setter methods defined in configuration for this task.
Result
run()
When we run the collection builder, run everything in the collection.
protected Result
runTasks()
If there is a single task, run it; if there is a collection, run all of its tasks.
string
getCommand()
Returns command that can be executed.
This method is used to pass generated command from one task to another.
TaskInterface
original()
No description
CollectionInterface
getCollection()
Return the collection of tasks associated with this builder.