<?php
/**
* Interface for batch data processors. See the BatchProcessingController class for usage details.
*/
namespace Automattic\WooCommerce\Internal\BatchProcessing;
/**
* Interface BatchProcessorInterface
*
* @package Automattic\WooCommerce\DataBase
*/
interface BatchProcessorInterface {
/**
* Get a user-friendly name for this processor.
*
* @return string Name of the processor.
*/
public function get_name() : string;
/**
* Get a user-friendly description for this processor.
*
* @return string Description of what this processor does.
*/
public function get_description() : string;
/**
* Get the total number of pending items that require processing.
* Once an item is successfully processed by 'process_batch' it shouldn't be included in this count.
*
* Note that the once the processor is enqueued the batch processor controller will keep
* invoking `get_next_batch_to_process` and `process_batch` repeatedly until this method returns zero.
*
* @return int Number of items pending processing.
*/
public function get_total_pending_count() : int;
/**
* Returns the next batch of items that need to be processed.
*
* A batch item can be anything needed to identify the actual processing to be done,
* but whenever possible items should be numbers (e.g. database record ids)
* or at least strings, to ease troubleshooting and logging in case of problems.
*
* The size of the batch returned can be less than $size if there aren't that
* many items pending processing (and it can be zero if there isn't anything to process),
* but the size should always be consistent with what 'get_total_pending_count' returns
* (i.e. the size of the returned batch shouldn't be larger than the pending items count).
*
* @param int $size Maximum size of the batch to be returned.
*
* @return array Batch of items to process, containing $size or less items.
*/
public function get_next_batch_to_process( int $size ) : array;
/**
* Process data for the supplied batch.
*
* This method should be prepared to receive items that don't actually need processing
* (because they have been processed before) and ignore them, but if at least
* one of the batch items that actually need processing can't be processed, an exception should be thrown.
*
* Once an item has been processed it shouldn't be counted in 'get_total_pending_count'
* nor included in 'get_next_batch_to_process' anymore (unless something happens that causes it
* to actually require further processing).
*
* @throw \Exception Something went wrong while processing the batch.
*
* @param array $batch Batch to process, as returned by 'get_next_batch_to_process'.
*/
public function process_batch( array $batch ): void;
/**
* Default (preferred) batch size to pass to 'get_next_batch_to_process'.
* The controller will pass this size unless it's externally configured
* to use a different size.
*
* @return int Default batch size.
*/
public function get_default_batch_size() : int;
}