BatchProcessorInterface.php
| 1 | <?php |
| 2 | /** |
| 3 | * Interface for batch data processors. See the BatchProcessingController class for usage details. |
| 4 | */ |
| 5 | |
| 6 | namespace Automattic\WooCommerce\Internal\BatchProcessing; |
| 7 | |
| 8 | /** |
| 9 | * Interface BatchProcessorInterface |
| 10 | * |
| 11 | * @package Automattic\WooCommerce\Internal\BatchProcessing |
| 12 | */ |
| 13 | interface BatchProcessorInterface { |
| 14 | |
| 15 | /** |
| 16 | * Get a user-friendly name for this processor. |
| 17 | * |
| 18 | * @return string Name of the processor. |
| 19 | */ |
| 20 | public function get_name() : string; |
| 21 | |
| 22 | /** |
| 23 | * Get a user-friendly description for this processor. |
| 24 | * |
| 25 | * @return string Description of what this processor does. |
| 26 | */ |
| 27 | public function get_description() : string; |
| 28 | |
| 29 | /** |
| 30 | * Get the total number of pending items that require processing. |
| 31 | * Once an item is successfully processed by 'process_batch' it shouldn't be included in this count. |
| 32 | * |
| 33 | * Note that the once the processor is enqueued the batch processor controller will keep |
| 34 | * invoking `get_next_batch_to_process` and `process_batch` repeatedly until this method returns zero. |
| 35 | * |
| 36 | * @return int Number of items pending processing. |
| 37 | */ |
| 38 | public function get_total_pending_count() : int; |
| 39 | |
| 40 | /** |
| 41 | * Returns the next batch of items that need to be processed. |
| 42 | * |
| 43 | * A batch item can be anything needed to identify the actual processing to be done, |
| 44 | * but whenever possible items should be numbers (e.g. database record ids) |
| 45 | * or at least strings, to ease troubleshooting and logging in case of problems. |
| 46 | * |
| 47 | * The size of the batch returned can be less than $size if there aren't that |
| 48 | * many items pending processing (and it can be zero if there isn't anything to process), |
| 49 | * but the size should always be consistent with what 'get_total_pending_count' returns |
| 50 | * (i.e. the size of the returned batch shouldn't be larger than the pending items count). |
| 51 | * |
| 52 | * @param int $size Maximum size of the batch to be returned. |
| 53 | * |
| 54 | * @return array Batch of items to process, containing $size or less items. |
| 55 | */ |
| 56 | public function get_next_batch_to_process( int $size ) : array; |
| 57 | |
| 58 | /** |
| 59 | * Process data for the supplied batch. |
| 60 | * |
| 61 | * This method should be prepared to receive items that don't actually need processing |
| 62 | * (because they have been processed before) and ignore them, but if at least |
| 63 | * one of the batch items that actually need processing can't be processed, an exception should be thrown. |
| 64 | * |
| 65 | * Once an item has been processed it shouldn't be counted in 'get_total_pending_count' |
| 66 | * nor included in 'get_next_batch_to_process' anymore (unless something happens that causes it |
| 67 | * to actually require further processing). |
| 68 | * |
| 69 | * @throw \Exception Something went wrong while processing the batch. |
| 70 | * |
| 71 | * @param array $batch Batch to process, as returned by 'get_next_batch_to_process'. |
| 72 | */ |
| 73 | public function process_batch( array $batch ): void; |
| 74 | |
| 75 | /** |
| 76 | * Default (preferred) batch size to pass to 'get_next_batch_to_process'. |
| 77 | * The controller will pass this size unless it's externally configured |
| 78 | * to use a different size. |
| 79 | * |
| 80 | * @return int Default batch size. |
| 81 | */ |
| 82 | public function get_default_batch_size() : int; |
| 83 | } |
| 84 |