www.aleph1.co.uk Git - yaffs-website/blob - vendor/consolidation/robo/src/Collection/CollectionInterface.php

   1 <?php
   2 namespace Robo\Collection;
   3
   4 use Psr\Log\LogLevel;
   5 use Robo\Contract\TaskInterface;
   6
   7 interface CollectionInterface extends NestedCollectionInterface
   8 {
   9     /**
  10      * Unnamed tasks are assigned an arbitrary numeric index
  11      * in the task list. Any numeric value may be used, but the
  12      * UNNAMEDTASK constant is recommended for clarity.
  13      *
  14      * @var int
  15      */
  16     const UNNAMEDTASK = 0;
  17
  18     /**
  19      * Add a task or a list of tasks to our task collection.  Each task
  20      * will run via its 'run()' method once (and if) all of the tasks
  21      * added before it complete successfully.  If the task also implements
  22      * RollbackInterface, then it will be rolled back via its 'rollback()'
  23      * method ONLY if its 'run()' method completes successfully, and some
  24      * task added after it fails.
  25      *
  26      * @param TaskInterface $task
  27      *   The task to add to our collection.
  28      * @param int|string $name
  29      *   An optional name for the task -- missing or UNNAMEDTASK for unnamed tasks.
  30      *   Names are used for positioning before and after tasks.
  31      *
  32      * @return CollectionInterface
  33      */
  34     public function add(TaskInterface $task, $name = self::UNNAMEDTASK);
  35
  36     /**
  37      * Add arbitrary code to execute as a task.
  38      *
  39      * @param callable $code Code to execute as a task
  40      * @param int|string $name
  41      *   An optional name for the task -- missing or UNNAMEDTASK for unnamed tasks.
  42      *   Names are used for positioning before and after tasks.
  43      *
  44      * @return $this
  45      */
  46     public function addCode(callable $code, $name = self::UNNAMEDTASK);
  47
  48     /**
  49      * Add arbitrary code that will be called once for every item in the
  50      * provided array or iterable object.  If the function result of the
  51      * provided callback is a TaskInterface or Collection, then it will be
  52      * executed.
  53      *
  54      * @param CollectionInterface|array $iterable A collection of things to iterate
  55      * @param $code $code A callback function to call for each item in the collection.
  56      *
  57      * @return $this
  58      */
  59     public function addIterable($iterable, callable $code);
  60
  61     /**
  62      * Add a rollback task to our task collection.  A rollback task
  63      * will execute ONLY if all of the tasks added before it complete
  64      * successfully, AND some task added after it fails.
  65      *
  66      * @param TaskInterface $rollbackTask
  67      *   The rollback task to add.  Note that the 'run()' method of the
  68      *   task executes, not its 'rollback()' method.  To use the 'rollback()'
  69      *   method, add the task via 'Collection::add()' instead.
  70      *
  71      * @return $this
  72      */
  73     public function rollback(TaskInterface $rollbackTask);
  74
  75     /**
  76      * Add arbitrary code to execute as a rollback.
  77      *
  78      * @param callable $rollbackTask Code to execute during rollback processing
  79      *
  80      * @return $this
  81      */
  82     public function rollbackCode(callable $rollbackTask);
  83
  84     /**
  85      * Add a completion task to our task collection.  A completion task
  86      * will execute EITHER after all tasks succeed, OR immediatley after
  87      * any task fails.  Completion tasks never cause errors to be returned
  88      * from Collection::run(), even if they fail.
  89      *
  90      * @param TaskInterface $completionTask
  91      *   The completion task to add.  Note that the 'run()' method of the
  92      *   task executes, just as if the task was added normally.
  93      *
  94      * @return $this
  95      */
  96     public function completion(TaskInterface $completionTask);
  97
  98     /**
  99      * Add arbitrary code to execute as a completion.
 100      *
 101      * @param callable $completionTask Code to execute after collection completes
 102      *
 103      * @return $this
 104      */
 105     public function completionCode(callable $completionTask);
 106
 107     /**
 108      * Add a task before an existing named task.
 109      *
 110      * @param string $name
 111      *   The name of the task to insert before.  The named task MUST exist.
 112      * @param callable|TaskInterface $task
 113      *   The task to add.
 114      * @param int|string $nameOfTaskToAdd
 115      *   The name of the task to add. If not provided, will be associated
 116      *   with the named task it was added before.
 117      *
 118      * @return $this
 119      */
 120     public function before($name, $task, $nameOfTaskToAdd = self::UNNAMEDTASK);
 121
 122     /**
 123      * Add a task after an existing named task.
 124      *
 125      * @param string $name
 126      *   The name of the task to insert before.  The named task MUST exist.
 127      * @param callable|TaskInterface $task
 128      *   The task to add.
 129      * @param int|string $nameOfTaskToAdd
 130      *   The name of the task to add. If not provided, will be associated
 131      *   with the named task it was added after.
 132      *
 133      * @return $this
 134      */
 135     public function after($name, $task, $nameOfTaskToAdd = self::UNNAMEDTASK);
 136
 137     /**
 138      * Print a progress message after Collection::run() has executed
 139      * all of the tasks that were added prior to the point when this
 140      * method was called. If one of the previous tasks fail, then this
 141      * message will not be printed.
 142      *
 143      * @param string $text Message to print.
 144      * @param array $context Extra context data for use by the logger. Note
 145      *   that the data from the collection state is merged with the provided context.
 146      * @param \Psr\Log\LogLevel|string $level The log level to print the information at. Default is NOTICE.
 147      *
 148      * @return $this
 149      */
 150     public function progressMessage($text, $context = [], $level = LogLevel::NOTICE);
 151 }