Chris@17
|
1 <?php
|
Chris@17
|
2
|
Chris@17
|
3 namespace Drupal\Core\Batch;
|
Chris@17
|
4
|
Chris@17
|
5 use Drupal\Core\Queue\QueueInterface;
|
Chris@17
|
6 use Drupal\Core\StringTranslation\TranslatableMarkup;
|
Chris@17
|
7
|
Chris@17
|
8 /**
|
Chris@17
|
9 * Builds an array for a batch process.
|
Chris@17
|
10 *
|
Chris@17
|
11 * Example code to create a batch:
|
Chris@17
|
12 * @code
|
Chris@17
|
13 * $batch_builder = (new BatchBuilder())
|
Chris@17
|
14 * ->setTitle(t('Batch Title'))
|
Chris@17
|
15 * ->setFinishCallback('batch_example_finished_callback')
|
Chris@17
|
16 * ->setInitMessage(t('The initialization message (optional)'));
|
Chris@17
|
17 * foreach ($ids as $id) {
|
Chris@17
|
18 * $batch_builder->addOperation('batch_example_callback', [$id]);
|
Chris@17
|
19 * }
|
Chris@17
|
20 * batch_set($batch_builder->toArray());
|
Chris@17
|
21 * @endcode
|
Chris@17
|
22 */
|
Chris@17
|
23 class BatchBuilder {
|
Chris@17
|
24
|
Chris@17
|
25 /**
|
Chris@17
|
26 * The set of operations to be processed.
|
Chris@17
|
27 *
|
Chris@17
|
28 * Each operation is a tuple of the function / method to use and an array
|
Chris@17
|
29 * containing any parameters to be passed.
|
Chris@17
|
30 *
|
Chris@17
|
31 * @var array
|
Chris@17
|
32 */
|
Chris@17
|
33 protected $operations = [];
|
Chris@17
|
34
|
Chris@17
|
35 /**
|
Chris@17
|
36 * The title for the batch.
|
Chris@17
|
37 *
|
Chris@17
|
38 * @var string|\Drupal\Core\StringTranslation\TranslatableMarkup
|
Chris@17
|
39 */
|
Chris@17
|
40 protected $title;
|
Chris@17
|
41
|
Chris@17
|
42 /**
|
Chris@17
|
43 * The initializing message for the batch.
|
Chris@17
|
44 *
|
Chris@17
|
45 * @var string|\Drupal\Core\StringTranslation\TranslatableMarkup
|
Chris@17
|
46 */
|
Chris@17
|
47 protected $initMessage;
|
Chris@17
|
48
|
Chris@17
|
49 /**
|
Chris@17
|
50 * The message to be shown while the batch is in progress.
|
Chris@17
|
51 *
|
Chris@17
|
52 * @var string|\Drupal\Core\StringTranslation\TranslatableMarkup
|
Chris@17
|
53 */
|
Chris@17
|
54 protected $progressMessage;
|
Chris@17
|
55
|
Chris@17
|
56 /**
|
Chris@17
|
57 * The message to be shown if a problem occurs.
|
Chris@17
|
58 *
|
Chris@17
|
59 * @var string|\Drupal\Core\StringTranslation\TranslatableMarkup
|
Chris@17
|
60 */
|
Chris@17
|
61 protected $errorMessage;
|
Chris@17
|
62
|
Chris@17
|
63 /**
|
Chris@17
|
64 * The name of a function / method to be called when the batch finishes.
|
Chris@17
|
65 *
|
Chris@17
|
66 * @var string
|
Chris@17
|
67 */
|
Chris@17
|
68 protected $finished;
|
Chris@17
|
69
|
Chris@17
|
70 /**
|
Chris@17
|
71 * The file containing the operation and finished callbacks.
|
Chris@17
|
72 *
|
Chris@17
|
73 * If the callbacks are in the .module file or can be autoloaded, for example,
|
Chris@17
|
74 * static methods on a class, then this does not need to be set.
|
Chris@17
|
75 *
|
Chris@17
|
76 * @var string
|
Chris@17
|
77 */
|
Chris@17
|
78 protected $file;
|
Chris@17
|
79
|
Chris@17
|
80 /**
|
Chris@17
|
81 * An array of libraries to be included when processing the batch.
|
Chris@17
|
82 *
|
Chris@17
|
83 * @var string[]
|
Chris@17
|
84 */
|
Chris@17
|
85 protected $libraries = [];
|
Chris@17
|
86
|
Chris@17
|
87 /**
|
Chris@17
|
88 * An array of options to be used with the redirect URL.
|
Chris@17
|
89 *
|
Chris@17
|
90 * @var array
|
Chris@17
|
91 */
|
Chris@17
|
92 protected $urlOptions = [];
|
Chris@17
|
93
|
Chris@17
|
94 /**
|
Chris@17
|
95 * Specifies if the batch is progressive.
|
Chris@17
|
96 *
|
Chris@17
|
97 * If true, multiple calls are used. Otherwise an attempt is made to process
|
Chris@17
|
98 * the batch in a single run.
|
Chris@17
|
99 *
|
Chris@17
|
100 * @var bool
|
Chris@17
|
101 */
|
Chris@17
|
102 protected $progressive = TRUE;
|
Chris@17
|
103
|
Chris@17
|
104 /**
|
Chris@17
|
105 * The details of the queue to use.
|
Chris@17
|
106 *
|
Chris@17
|
107 * A tuple containing the name of the queue and the class of the queue to use.
|
Chris@17
|
108 *
|
Chris@17
|
109 * @var array
|
Chris@17
|
110 */
|
Chris@17
|
111 protected $queue;
|
Chris@17
|
112
|
Chris@17
|
113 /**
|
Chris@17
|
114 * Sets the default values for the batch builder.
|
Chris@17
|
115 */
|
Chris@17
|
116 public function __construct() {
|
Chris@17
|
117 $this->title = new TranslatableMarkup('Processing');
|
Chris@17
|
118 $this->initMessage = new TranslatableMarkup('Initializing.');
|
Chris@17
|
119 $this->progressMessage = new TranslatableMarkup('Completed @current of @total.');
|
Chris@17
|
120 $this->errorMessage = new TranslatableMarkup('An error has occurred.');
|
Chris@17
|
121 }
|
Chris@17
|
122
|
Chris@17
|
123 /**
|
Chris@17
|
124 * Sets the title.
|
Chris@17
|
125 *
|
Chris@17
|
126 * @param string|\Drupal\Core\StringTranslation\TranslatableMarkup $title
|
Chris@17
|
127 * The title.
|
Chris@17
|
128 *
|
Chris@17
|
129 * @return $this
|
Chris@17
|
130 */
|
Chris@17
|
131 public function setTitle($title) {
|
Chris@17
|
132 $this->title = $title;
|
Chris@17
|
133 return $this;
|
Chris@17
|
134 }
|
Chris@17
|
135
|
Chris@17
|
136 /**
|
Chris@17
|
137 * Sets the finished callback.
|
Chris@17
|
138 *
|
Chris@17
|
139 * This callback will be executed if the batch process is done.
|
Chris@17
|
140 *
|
Chris@17
|
141 * @param callable $callback
|
Chris@17
|
142 * The callback.
|
Chris@17
|
143 *
|
Chris@17
|
144 * @return $this
|
Chris@17
|
145 */
|
Chris@17
|
146 public function setFinishCallback(callable $callback) {
|
Chris@17
|
147 $this->finished = $callback;
|
Chris@17
|
148 return $this;
|
Chris@17
|
149 }
|
Chris@17
|
150
|
Chris@17
|
151 /**
|
Chris@17
|
152 * Sets the displayed message while processing is initialized.
|
Chris@17
|
153 *
|
Chris@17
|
154 * Defaults to 'Initializing.'.
|
Chris@17
|
155 *
|
Chris@17
|
156 * @param string|\Drupal\Core\StringTranslation\TranslatableMarkup $message
|
Chris@17
|
157 * The text to display.
|
Chris@17
|
158 *
|
Chris@17
|
159 * @return $this
|
Chris@17
|
160 */
|
Chris@17
|
161 public function setInitMessage($message) {
|
Chris@17
|
162 $this->initMessage = $message;
|
Chris@17
|
163 return $this;
|
Chris@17
|
164 }
|
Chris@17
|
165
|
Chris@17
|
166 /**
|
Chris@17
|
167 * Sets the message to display when the batch is being processed.
|
Chris@17
|
168 *
|
Chris@17
|
169 * Defaults to 'Completed @current of @total.'.
|
Chris@17
|
170 *
|
Chris@17
|
171 * @param string|\Drupal\Core\StringTranslation\TranslatableMarkup $message
|
Chris@17
|
172 * The text to display. Available placeholders are:
|
Chris@17
|
173 * - '@current'
|
Chris@17
|
174 * - '@remaining'
|
Chris@17
|
175 * - '@total'
|
Chris@17
|
176 * - '@percentage'
|
Chris@17
|
177 * - '@estimate'
|
Chris@17
|
178 * - '@elapsed'.
|
Chris@17
|
179 *
|
Chris@17
|
180 * @return $this
|
Chris@17
|
181 */
|
Chris@17
|
182 public function setProgressMessage($message) {
|
Chris@17
|
183 $this->progressMessage = $message;
|
Chris@17
|
184 return $this;
|
Chris@17
|
185 }
|
Chris@17
|
186
|
Chris@17
|
187 /**
|
Chris@17
|
188 * Sets the message to display if an error occurs while processing.
|
Chris@17
|
189 *
|
Chris@17
|
190 * Defaults to 'An error has occurred.'.
|
Chris@17
|
191 *
|
Chris@17
|
192 * @param string|\Drupal\Core\StringTranslation\TranslatableMarkup $message
|
Chris@17
|
193 * The text to display.
|
Chris@17
|
194 *
|
Chris@17
|
195 * @return $this
|
Chris@17
|
196 */
|
Chris@17
|
197 public function setErrorMessage($message) {
|
Chris@17
|
198 $this->errorMessage = $message;
|
Chris@17
|
199 return $this;
|
Chris@17
|
200 }
|
Chris@17
|
201
|
Chris@17
|
202 /**
|
Chris@17
|
203 * Sets the file that contains the callback functions.
|
Chris@17
|
204 *
|
Chris@17
|
205 * The path should be relative to base_path(), and thus should be built using
|
Chris@17
|
206 * drupal_get_path(). Defaults to {module_name}.module.
|
Chris@17
|
207 *
|
Chris@17
|
208 * @param string $filename
|
Chris@17
|
209 * The path to the file.
|
Chris@17
|
210 *
|
Chris@17
|
211 * @return $this
|
Chris@17
|
212 */
|
Chris@17
|
213 public function setFile($filename) {
|
Chris@17
|
214 $this->file = $filename;
|
Chris@17
|
215 return $this;
|
Chris@17
|
216 }
|
Chris@17
|
217
|
Chris@17
|
218 /**
|
Chris@17
|
219 * Sets the libraries to use when processing the batch.
|
Chris@17
|
220 *
|
Chris@17
|
221 * Adds the libraries for use on the progress page. Any previously added
|
Chris@17
|
222 * libraries are removed.
|
Chris@17
|
223 *
|
Chris@17
|
224 * @param string[] $libraries
|
Chris@17
|
225 * The libraries to be used.
|
Chris@17
|
226 *
|
Chris@17
|
227 * @return $this
|
Chris@17
|
228 */
|
Chris@17
|
229 public function setLibraries(array $libraries) {
|
Chris@17
|
230 $this->libraries = $libraries;
|
Chris@17
|
231 return $this;
|
Chris@17
|
232 }
|
Chris@17
|
233
|
Chris@17
|
234 /**
|
Chris@17
|
235 * Sets the options for redirect URLs.
|
Chris@17
|
236 *
|
Chris@17
|
237 * @param array $options
|
Chris@17
|
238 * The options to use.
|
Chris@17
|
239 *
|
Chris@17
|
240 * @return $this
|
Chris@17
|
241 *
|
Chris@17
|
242 * @see \Drupal\Core\Url
|
Chris@17
|
243 */
|
Chris@17
|
244 public function setUrlOptions(array $options) {
|
Chris@17
|
245 $this->urlOptions = $options;
|
Chris@17
|
246 return $this;
|
Chris@17
|
247 }
|
Chris@17
|
248
|
Chris@17
|
249 /**
|
Chris@17
|
250 * Sets the batch to run progressively.
|
Chris@17
|
251 *
|
Chris@17
|
252 * @param bool $is_progressive
|
Chris@17
|
253 * (optional) A Boolean that indicates whether or not the batch needs to run
|
Chris@17
|
254 * progressively. TRUE indicates that the batch will run in more than one
|
Chris@17
|
255 * run. FALSE indicates that the batch will finish in a single run. Defaults
|
Chris@17
|
256 * to TRUE.
|
Chris@17
|
257 *
|
Chris@17
|
258 * @return $this
|
Chris@17
|
259 */
|
Chris@17
|
260 public function setProgressive($is_progressive = TRUE) {
|
Chris@17
|
261 $this->progressive = $is_progressive;
|
Chris@17
|
262 return $this;
|
Chris@17
|
263 }
|
Chris@17
|
264
|
Chris@17
|
265 /**
|
Chris@17
|
266 * Sets an override for the default queue.
|
Chris@17
|
267 *
|
Chris@17
|
268 * The class will typically either be \Drupal\Core\Queue\Batch or
|
Chris@17
|
269 * \Drupal\Core\Queue\BatchMemory. The class defaults to Batch if progressive
|
Chris@17
|
270 * is TRUE, or to BatchMemory if progressive is FALSE.
|
Chris@17
|
271 *
|
Chris@17
|
272 * @param string $name
|
Chris@17
|
273 * The unique identifier for the queue.
|
Chris@17
|
274 * @param string $class
|
Chris@17
|
275 * The fully qualified name of a class that implements
|
Chris@17
|
276 * \Drupal\Core\Queue\QueueInterface.
|
Chris@17
|
277 *
|
Chris@17
|
278 * @return $this
|
Chris@17
|
279 */
|
Chris@17
|
280 public function setQueue($name, $class) {
|
Chris@17
|
281 if (!class_exists($class)) {
|
Chris@17
|
282 throw new \InvalidArgumentException('Class ' . $class . ' does not exist.');
|
Chris@17
|
283 }
|
Chris@17
|
284
|
Chris@17
|
285 if (!in_array(QueueInterface::class, class_implements($class))) {
|
Chris@17
|
286 throw new \InvalidArgumentException(
|
Chris@17
|
287 'Class ' . $class . ' does not implement \Drupal\Core\Queue\QueueInterface.'
|
Chris@17
|
288 );
|
Chris@17
|
289 }
|
Chris@17
|
290
|
Chris@17
|
291 $this->queue = [
|
Chris@17
|
292 'name' => $name,
|
Chris@17
|
293 'class' => $class,
|
Chris@17
|
294 ];
|
Chris@17
|
295 return $this;
|
Chris@17
|
296 }
|
Chris@17
|
297
|
Chris@17
|
298 /**
|
Chris@17
|
299 * Adds a batch operation.
|
Chris@17
|
300 *
|
Chris@17
|
301 * @param callable $callback
|
Chris@17
|
302 * The name of the callback function.
|
Chris@17
|
303 * @param array $arguments
|
Chris@17
|
304 * An array of arguments to pass to the callback function.
|
Chris@17
|
305 *
|
Chris@17
|
306 * @return $this
|
Chris@17
|
307 */
|
Chris@17
|
308 public function addOperation(callable $callback, array $arguments = []) {
|
Chris@17
|
309 $this->operations[] = [$callback, $arguments];
|
Chris@17
|
310 return $this;
|
Chris@17
|
311 }
|
Chris@17
|
312
|
Chris@17
|
313 /**
|
Chris@17
|
314 * Converts a \Drupal\Core\Batch\Batch object into an array.
|
Chris@17
|
315 *
|
Chris@17
|
316 * @return array
|
Chris@17
|
317 * The array representation of the object.
|
Chris@17
|
318 */
|
Chris@17
|
319 public function toArray() {
|
Chris@17
|
320 $array = [
|
Chris@17
|
321 'operations' => $this->operations ?: [],
|
Chris@17
|
322 'title' => $this->title ?: '',
|
Chris@17
|
323 'init_message' => $this->initMessage ?: '',
|
Chris@17
|
324 'progress_message' => $this->progressMessage ?: '',
|
Chris@17
|
325 'error_message' => $this->errorMessage ?: '',
|
Chris@17
|
326 'finished' => $this->finished,
|
Chris@17
|
327 'file' => $this->file,
|
Chris@17
|
328 'library' => $this->libraries ?: [],
|
Chris@17
|
329 'url_options' => $this->urlOptions ?: [],
|
Chris@17
|
330 'progressive' => $this->progressive,
|
Chris@17
|
331 ];
|
Chris@17
|
332
|
Chris@17
|
333 if ($this->queue) {
|
Chris@17
|
334 $array['queue'] = $this->queue;
|
Chris@17
|
335 }
|
Chris@17
|
336
|
Chris@17
|
337 return $array;
|
Chris@17
|
338 }
|
Chris@17
|
339
|
Chris@17
|
340 }
|