Completed
Push — master ( 8b8afe...5f2bbe )
by Greg
02:21
created

src/Collection/CollectionInterface.php (1 issue)

Check for PhpDoc comments which do parse

Documentation Minor

Upgrade to new PHP Analysis Engine

These results are based on our legacy PHP analysis, consider migrating to our new PHP analysis engine instead. Learn more

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.
0 ignored issues
show
The doc-type $code could not be parsed: Unknown type name "$code" at position 0. (view supported doc-types)

This check marks PHPDoc comments that could not be parsed by our parser. To see which comment annotations we can parse, please refer to our documentation on supported doc-types.

Loading history...
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
}
152