Collection
class Collection extends BaseTask implements CollectionInterface, CommandInterface, StateAwareInterface (View source)
Group tasks into a collection that run together. Supports rollback operations for handling error conditions.
This is an internal class. Clients should use a CollectionBuilder rather than direct use of the Collection class. CollectionBuilder.
Below, the example FilesystemStack task is added to a collection, and associated with a rollback task. If any of the operations in the FilesystemStack, or if any of the other tasks also added to the task collection should fail, then the rollback function is called. Here, taskDeleteDir is used to remove partial results of an unfinished task.
Traits
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 Element[] | $taskList | ||
| protected TaskInterface[] | $rollbackStack | ||
| protected TaskInterface[] | $completionStack | ||
| protected CollectionInterface | $parentCollection | ||
| protected callable[] | $deferredCallbacks | ||
| protected string[] | $messageStoreKeys |
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
Required verbosity level before any TaskIO output will be produced.
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.
Return the count of steps in this collection
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).
Constructor.
No description
Add a task or a list of tasks to our task collection. Each task will run via its 'run()' method once (and if) all of the tasks added before it complete successfully. If the task also implements RollbackInterface, then it will be rolled back via its 'rollback()' method ONLY if its 'run()' method completes successfully, and some task added after it fails.
Add arbitrary code to execute as a task.
Add arbitrary code that will be called once for every item in the provided array or iterable object. If the function result of the provided callback is a TaskInterface or Collection, then it will be executed.
Add a rollback task to our task collection. A rollback task will execute ONLY if all of the tasks added before it complete successfully, AND some task added after it fails.
Add arbitrary code to execute as a rollback.
Add a completion task to our task collection. A completion task will execute EITHER after all tasks succeed, OR immediatley after any task fails. Completion tasks never cause errors to be returned from Collection::run(), even if they fail.
Add arbitrary code to execute as a completion.
Add a task before an existing named task.
Add a task after an existing named task.
Print a progress message after Collection::run() has executed all of the tasks that were added prior to the point when this method was called. If one of the previous tasks fail, then this message will not be printed.
Add either a 'before' or 'after' function or task.
Wrap the provided task in a wrapper that will ignore any errors or exceptions that may be produced. This is useful, for example, in adding optional cleanup tasks at the beginning of a task collection, to remove previous results which may or may not exist.
No description
Return the list of task names added to this collection.
Test to see if a specified task name exists.
Add a list of tasks to our task collection.
Set the parent collection. This is necessary so that nested collections' rollback and completion tasks can be added to the top-level collection, ensuring that the rollbacks for a collection will run if any later task fails.
Get the appropriate parent collection to use
Register a rollback task to run if there is any failure.
Register a completion task to run once all other tasks finish.
A Collection of tasks can provide a command via getCommand()
if it contains a single task, and that task implements CommandInterface.
Force the rollback functions to run
Force the completion functions to run
Reset this collection, removing all tasks.
Run all of our rollback tasks.
Defer execution of a callback function until just before a task runs. Use this time to provide more settings for the task, e.g. from the collection's shared state, which is populated with the results of previous test runs.
No description
Run all of the tasks in a provided list, ignoring failures.
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)
Required verbosity level before any TaskIO output will be produced.
e.g. OutputInterface::VERBOSITY_VERBOSE
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()
Return the count of steps in this collection
$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
__construct()
Constructor.
setProgressBarAutoDisplayInterval(int $interval)
No description
$this
add(TaskInterface $task, int|string $name = self::UNNAMEDTASK)
Add a task or a list of tasks to our task collection. Each task will run via its 'run()' method once (and if) all of the tasks added before it complete successfully. If the task also implements RollbackInterface, then it will be rolled back via its 'rollback()' method ONLY if its 'run()' method completes successfully, and some task added after it fails.
$this
addCode(callable $code, int|string $name = self::UNNAMEDTASK)
Add arbitrary code to execute as a task.
$this
addIterable(CollectionInterface|array $iterable, callable $code)
Add arbitrary code that will be called once for every item in the provided array or iterable object. If the function result of the provided callback is a TaskInterface or Collection, then it will be executed.
$this
rollback(TaskInterface $rollbackTask)
Add a rollback task to our task collection. A rollback task will execute ONLY if all of the tasks added before it complete successfully, AND some task added after it fails.
$this
rollbackCode(callable $rollbackCode)
Add arbitrary code to execute as a rollback.
$this
completion(TaskInterface $completionTask)
Add a completion task to our task collection. A completion task will execute EITHER after all tasks succeed, OR immediatley after any task fails. Completion tasks never cause errors to be returned from Collection::run(), even if they fail.
$this
completionCode(callable $completionTask)
Add arbitrary code to execute as a completion.
$this
before(string $name, callable|TaskInterface $task, int|string $nameOfTaskToAdd = self::UNNAMEDTASK)
Add a task before an existing named task.
$this
after(string $name, callable|TaskInterface $task, int|string $nameOfTaskToAdd = self::UNNAMEDTASK)
Add a task after an existing named task.
$this
progressMessage(string $text, array $context = [], LogLevel|string $level = LogLevel::NOTICE)
Print a progress message after Collection::run() has executed all of the tasks that were added prior to the point when this method was called. If one of the previous tasks fail, then this message will not be printed.
protected $this
wrapAndRegisterRollback(TaskInterface $rollbackTask)
No description
protected $this
addBeforeOrAfter(string $method, string $name, callable|TaskInterface $task, string $nameOfTaskToAdd)
Add either a 'before' or 'after' function or task.
CallableTask
ignoreErrorsTaskWrapper(TaskInterface $task)
Wrap the provided task in a wrapper that will ignore any errors or exceptions that may be produced. This is useful, for example, in adding optional cleanup tasks at the beginning of a task collection, to remove previous results which may or may not exist.
TODO: Provide some way to specify which sort of errors are ignored, so that 'file not found' may be ignored, but 'permission denied' reported?
CallableTask
ignoreErrorsCodeWrapper(callable $task)
No description
string[]
taskNames()
Return the list of task names added to this collection.
bool
hasTask(string $name)
Test to see if a specified task name exists.
n.b. before() and after() require that the named task exist; use this function to test first, if unsure.
protected Element
namedTask(string $name)
Find an existing named task.
$this
addTaskList(array $tasks)
Add a list of tasks to our task collection.
protected $this
addToTaskList(string $name, TaskInterface $task)
Add the provided task to our task list.
protected $this
addCollectionElementToTaskList(int|string $name, Element $taskGroup)
No description
$this
setParentCollection(NestedCollectionInterface $parentCollection)
Set the parent collection. This is necessary so that nested collections' rollback and completion tasks can be added to the top-level collection, ensuring that the rollbacks for a collection will run if any later task fails.
CollectionInterface|$this
getParentCollection()
Get the appropriate parent collection to use
null
registerRollback(TaskInterface $rollbackTask)
Register a rollback task to run if there is any failure.
Clients are free to add tasks to the rollback stack as desired; however, usually it is preferable to call Collection::rollback() instead. With that function, the rollback function will only be called if all of the tasks added before it complete successfully, AND some later task fails.
One example of a good use-case for registering a callback function directly is to add a task that sends notification when a task fails.
null
registerCompletion(TaskInterface $completionTask)
Register a completion task to run once all other tasks finish.
Completion tasks run whether or not a rollback operation was triggered. They do not trigger rollbacks if they fail.
The typical use-case for a completion function is to clean up temporary objects (e.g. temporary folders). The preferred way to do that, though, is to use Temporary::wrap().
On failures, completion tasks will run after all rollback tasks. If one task collection is nested inside another task collection, then the nested collection's completion tasks will run as soon as the nested task completes; they are not deferred to the end of the containing collection's execution.
string
getCommand()
A Collection of tasks can provide a command via getCommand()
if it contains a single task, and that task implements CommandInterface.
Result
run()
Run our tasks, and roll back if necessary.
$this
fail()
Force the rollback functions to run
$this
complete()
Force the completion functions to run
$this
reset()
Reset this collection, removing all tasks.
protected
runRollbackTasks()
Run all of our rollback tasks.
Note that Collection does not implement RollbackInterface, but it may still be used as a task inside another task collection (i.e. you can nest task collections, if desired).
protected Result
runSubtask(TaskInterface|NestedCollectionInterface|WrappedTaskInterface $task)
No description
protected
doStateUpdates(TaskInterface $task, Data $taskResult)
No description
$this
storeState(TaskInterface $task, string $key, string $source = '')
No description
$this
deferTaskConfiguration(TaskInterface $task, string $functionName, string $stateKey)
No description
$this
defer(TaskInterface $task, callable $callback)
Defer execution of a callback function until just before a task runs. Use this time to provide more settings for the task, e.g. from the collection's shared state, which is populated with the results of previous test runs.
protected
doDeferredInitialization(TaskInterface $task)
No description
protected
setParentCollectionForTask(TaskInterface|NestedCollectionInterface|WrappedTaskInterface $task, CollectionInterface $parentCollection)
No description
protected
runTaskListIgnoringFailures(array $taskList)
Run all of the tasks in a provided list, ignoring failures.
You may force a failure by throwing a ForcedException in your rollback or completion task or callback.
This is used to roll back or complete.
transferTasks(CollectionBuilder $builder)
Give all of our tasks to the provided collection builder.