annotate core/lib/Drupal/Core/Batch/BatchBuilder.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 129ea1e6d783
children
rev   line source
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 }