Chris@17: <?php
Chris@17: 
Chris@17: namespace Drupal\Core\Batch;
Chris@17: 
Chris@17: use Drupal\Core\Queue\QueueInterface;
Chris@17: use Drupal\Core\StringTranslation\TranslatableMarkup;
Chris@17: 
Chris@17: /**
Chris@17:  * Builds an array for a batch process.
Chris@17:  *
Chris@17:  * Example code to create a batch:
Chris@17:  * @code
Chris@17:  * $batch_builder = (new BatchBuilder())
Chris@17:  *   ->setTitle(t('Batch Title'))
Chris@17:  *   ->setFinishCallback('batch_example_finished_callback')
Chris@17:  *   ->setInitMessage(t('The initialization message (optional)'));
Chris@17:  * foreach ($ids as $id) {
Chris@17:  *   $batch_builder->addOperation('batch_example_callback', [$id]);
Chris@17:  * }
Chris@17:  * batch_set($batch_builder->toArray());
Chris@17:  * @endcode
Chris@17:  */
Chris@17: class BatchBuilder {
Chris@17: 
Chris@17:   /**
Chris@17:    * The set of operations to be processed.
Chris@17:    *
Chris@17:    * Each operation is a tuple of the function / method to use and an array
Chris@17:    * containing any parameters to be passed.
Chris@17:    *
Chris@17:    * @var array
Chris@17:    */
Chris@17:   protected $operations = [];
Chris@17: 
Chris@17:   /**
Chris@17:    * The title for the batch.
Chris@17:    *
Chris@17:    * @var string|\Drupal\Core\StringTranslation\TranslatableMarkup
Chris@17:    */
Chris@17:   protected $title;
Chris@17: 
Chris@17:   /**
Chris@17:    * The initializing message for the batch.
Chris@17:    *
Chris@17:    * @var string|\Drupal\Core\StringTranslation\TranslatableMarkup
Chris@17:    */
Chris@17:   protected $initMessage;
Chris@17: 
Chris@17:   /**
Chris@17:    * The message to be shown while the batch is in progress.
Chris@17:    *
Chris@17:    * @var string|\Drupal\Core\StringTranslation\TranslatableMarkup
Chris@17:    */
Chris@17:   protected $progressMessage;
Chris@17: 
Chris@17:   /**
Chris@17:    * The message to be shown if a problem occurs.
Chris@17:    *
Chris@17:    * @var string|\Drupal\Core\StringTranslation\TranslatableMarkup
Chris@17:    */
Chris@17:   protected $errorMessage;
Chris@17: 
Chris@17:   /**
Chris@17:    * The name of a function / method to be called when the batch finishes.
Chris@17:    *
Chris@17:    * @var string
Chris@17:    */
Chris@17:   protected $finished;
Chris@17: 
Chris@17:   /**
Chris@17:    * The file containing the operation and finished callbacks.
Chris@17:    *
Chris@17:    * If the callbacks are in the .module file or can be autoloaded, for example,
Chris@17:    * static methods on a class, then this does not need to be set.
Chris@17:    *
Chris@17:    * @var string
Chris@17:    */
Chris@17:   protected $file;
Chris@17: 
Chris@17:   /**
Chris@17:    * An array of libraries to be included when processing the batch.
Chris@17:    *
Chris@17:    * @var string[]
Chris@17:    */
Chris@17:   protected $libraries = [];
Chris@17: 
Chris@17:   /**
Chris@17:    * An array of options to be used with the redirect URL.
Chris@17:    *
Chris@17:    * @var array
Chris@17:    */
Chris@17:   protected $urlOptions = [];
Chris@17: 
Chris@17:   /**
Chris@17:    * Specifies if the batch is progressive.
Chris@17:    *
Chris@17:    * If true, multiple calls are used. Otherwise an attempt is made to process
Chris@17:    * the batch in a single run.
Chris@17:    *
Chris@17:    * @var bool
Chris@17:    */
Chris@17:   protected $progressive = TRUE;
Chris@17: 
Chris@17:   /**
Chris@17:    * The details of the queue to use.
Chris@17:    *
Chris@17:    * A tuple containing the name of the queue and the class of the queue to use.
Chris@17:    *
Chris@17:    * @var array
Chris@17:    */
Chris@17:   protected $queue;
Chris@17: 
Chris@17:   /**
Chris@17:    * Sets the default values for the batch builder.
Chris@17:    */
Chris@17:   public function __construct() {
Chris@17:     $this->title = new TranslatableMarkup('Processing');
Chris@17:     $this->initMessage = new TranslatableMarkup('Initializing.');
Chris@17:     $this->progressMessage = new TranslatableMarkup('Completed @current of @total.');
Chris@17:     $this->errorMessage = new TranslatableMarkup('An error has occurred.');
Chris@17:   }
Chris@17: 
Chris@17:   /**
Chris@17:    * Sets the title.
Chris@17:    *
Chris@17:    * @param string|\Drupal\Core\StringTranslation\TranslatableMarkup $title
Chris@17:    *   The title.
Chris@17:    *
Chris@17:    * @return $this
Chris@17:    */
Chris@17:   public function setTitle($title) {
Chris@17:     $this->title = $title;
Chris@17:     return $this;
Chris@17:   }
Chris@17: 
Chris@17:   /**
Chris@17:    * Sets the finished callback.
Chris@17:    *
Chris@17:    * This callback will be executed if the batch process is done.
Chris@17:    *
Chris@17:    * @param callable $callback
Chris@17:    *   The callback.
Chris@17:    *
Chris@17:    * @return $this
Chris@17:    */
Chris@17:   public function setFinishCallback(callable $callback) {
Chris@17:     $this->finished = $callback;
Chris@17:     return $this;
Chris@17:   }
Chris@17: 
Chris@17:   /**
Chris@17:    * Sets the displayed message while processing is initialized.
Chris@17:    *
Chris@17:    * Defaults to 'Initializing.'.
Chris@17:    *
Chris@17:    * @param string|\Drupal\Core\StringTranslation\TranslatableMarkup $message
Chris@17:    *   The text to display.
Chris@17:    *
Chris@17:    * @return $this
Chris@17:    */
Chris@17:   public function setInitMessage($message) {
Chris@17:     $this->initMessage = $message;
Chris@17:     return $this;
Chris@17:   }
Chris@17: 
Chris@17:   /**
Chris@17:    * Sets the message to display when the batch is being processed.
Chris@17:    *
Chris@17:    * Defaults to 'Completed @current of @total.'.
Chris@17:    *
Chris@17:    * @param string|\Drupal\Core\StringTranslation\TranslatableMarkup $message
Chris@17:    *   The text to display.  Available placeholders are:
Chris@17:    *   - '@current'
Chris@17:    *   - '@remaining'
Chris@17:    *   - '@total'
Chris@17:    *   - '@percentage'
Chris@17:    *   - '@estimate'
Chris@17:    *   - '@elapsed'.
Chris@17:    *
Chris@17:    * @return $this
Chris@17:    */
Chris@17:   public function setProgressMessage($message) {
Chris@17:     $this->progressMessage = $message;
Chris@17:     return $this;
Chris@17:   }
Chris@17: 
Chris@17:   /**
Chris@17:    * Sets the message to display if an error occurs while processing.
Chris@17:    *
Chris@17:    * Defaults to 'An error has occurred.'.
Chris@17:    *
Chris@17:    * @param string|\Drupal\Core\StringTranslation\TranslatableMarkup $message
Chris@17:    *   The text to display.
Chris@17:    *
Chris@17:    * @return $this
Chris@17:    */
Chris@17:   public function setErrorMessage($message) {
Chris@17:     $this->errorMessage = $message;
Chris@17:     return $this;
Chris@17:   }
Chris@17: 
Chris@17:   /**
Chris@17:    * Sets the file that contains the callback functions.
Chris@17:    *
Chris@17:    * The path should be relative to base_path(), and thus should be built using
Chris@17:    * drupal_get_path(). Defaults to {module_name}.module.
Chris@17:    *
Chris@17:    * @param string $filename
Chris@17:    *   The path to the file.
Chris@17:    *
Chris@17:    * @return $this
Chris@17:    */
Chris@17:   public function setFile($filename) {
Chris@17:     $this->file = $filename;
Chris@17:     return $this;
Chris@17:   }
Chris@17: 
Chris@17:   /**
Chris@17:    * Sets the libraries to use when processing the batch.
Chris@17:    *
Chris@17:    * Adds the libraries for use on the progress page. Any previously added
Chris@17:    * libraries are removed.
Chris@17:    *
Chris@17:    * @param string[] $libraries
Chris@17:    *   The libraries to be used.
Chris@17:    *
Chris@17:    * @return $this
Chris@17:    */
Chris@17:   public function setLibraries(array $libraries) {
Chris@17:     $this->libraries = $libraries;
Chris@17:     return $this;
Chris@17:   }
Chris@17: 
Chris@17:   /**
Chris@17:    * Sets the options for redirect URLs.
Chris@17:    *
Chris@17:    * @param array $options
Chris@17:    *   The options to use.
Chris@17:    *
Chris@17:    * @return $this
Chris@17:    *
Chris@17:    * @see \Drupal\Core\Url
Chris@17:    */
Chris@17:   public function setUrlOptions(array $options) {
Chris@17:     $this->urlOptions = $options;
Chris@17:     return $this;
Chris@17:   }
Chris@17: 
Chris@17:   /**
Chris@17:    * Sets the batch to run progressively.
Chris@17:    *
Chris@17:    * @param bool $is_progressive
Chris@17:    *   (optional) A Boolean that indicates whether or not the batch needs to run
Chris@17:    *   progressively. TRUE indicates that the batch will run in more than one
Chris@17:    *   run. FALSE indicates that the batch will finish in a single run. Defaults
Chris@17:    *   to TRUE.
Chris@17:    *
Chris@17:    * @return $this
Chris@17:    */
Chris@17:   public function setProgressive($is_progressive = TRUE) {
Chris@17:     $this->progressive = $is_progressive;
Chris@17:     return $this;
Chris@17:   }
Chris@17: 
Chris@17:   /**
Chris@17:    * Sets an override for the default queue.
Chris@17:    *
Chris@17:    * The class will typically either be \Drupal\Core\Queue\Batch or
Chris@17:    * \Drupal\Core\Queue\BatchMemory. The class defaults to Batch if progressive
Chris@17:    * is TRUE, or to BatchMemory if progressive is FALSE.
Chris@17:    *
Chris@17:    * @param string $name
Chris@17:    *   The unique identifier for the queue.
Chris@17:    * @param string $class
Chris@17:    *   The fully qualified name of a class that implements
Chris@17:    *   \Drupal\Core\Queue\QueueInterface.
Chris@17:    *
Chris@17:    * @return $this
Chris@17:    */
Chris@17:   public function setQueue($name, $class) {
Chris@17:     if (!class_exists($class)) {
Chris@17:       throw new \InvalidArgumentException('Class ' . $class . ' does not exist.');
Chris@17:     }
Chris@17: 
Chris@17:     if (!in_array(QueueInterface::class, class_implements($class))) {
Chris@17:       throw new \InvalidArgumentException(
Chris@17:         'Class ' . $class . ' does not implement \Drupal\Core\Queue\QueueInterface.'
Chris@17:       );
Chris@17:     }
Chris@17: 
Chris@17:     $this->queue = [
Chris@17:       'name' => $name,
Chris@17:       'class' => $class,
Chris@17:     ];
Chris@17:     return $this;
Chris@17:   }
Chris@17: 
Chris@17:   /**
Chris@17:    * Adds a batch operation.
Chris@17:    *
Chris@17:    * @param callable $callback
Chris@17:    *   The name of the callback function.
Chris@17:    * @param array $arguments
Chris@17:    *   An array of arguments to pass to the callback function.
Chris@17:    *
Chris@17:    * @return $this
Chris@17:    */
Chris@17:   public function addOperation(callable $callback, array $arguments = []) {
Chris@17:     $this->operations[] = [$callback, $arguments];
Chris@17:     return $this;
Chris@17:   }
Chris@17: 
Chris@17:   /**
Chris@17:    * Converts a \Drupal\Core\Batch\Batch object into an array.
Chris@17:    *
Chris@17:    * @return array
Chris@17:    *   The array representation of the object.
Chris@17:    */
Chris@17:   public function toArray() {
Chris@17:     $array = [
Chris@17:       'operations' => $this->operations ?: [],
Chris@17:       'title' => $this->title ?: '',
Chris@17:       'init_message' => $this->initMessage ?: '',
Chris@17:       'progress_message' => $this->progressMessage ?: '',
Chris@17:       'error_message' => $this->errorMessage ?: '',
Chris@17:       'finished' => $this->finished,
Chris@17:       'file' => $this->file,
Chris@17:       'library' => $this->libraries ?: [],
Chris@17:       'url_options' => $this->urlOptions ?: [],
Chris@17:       'progressive' => $this->progressive,
Chris@17:     ];
Chris@17: 
Chris@17:     if ($this->queue) {
Chris@17:       $array['queue'] = $this->queue;
Chris@17:     }
Chris@17: 
Chris@17:     return $array;
Chris@17:   }
Chris@17: 
Chris@17: }