aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Batch/BatchBuilder.php

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