README

PHP Batcher is a simple library providing batching functionality for PHP projects.

Features

Efficient batching of items.
Ordinality tracking (e.g., first, middle, last batch).
Custom state management whiten the batch processing.

Requirements

PHP 8.4 or higher.

Installation

Install the library using Composer:

composer require double-break/php-batcher

Usage

Basic Example

Here is an example of how to use the library:

use DoubleBreak\PhpBatcher\Batcher\Generic;

$batcher = new Generic(5, function (array $batch) {
    // Process the batch
    echo "Processing batch: " . implode(", ", $batch) . PHP_EOL;
});

$batcher->add("Item 1");
$batcher->add("Item 2");
$batcher->add("Item 3");
$batcher->add("Item 4");
$batcher->add("Item 5"); // Important: WILL NOT trigger the flush callback
$batcher->add("Item 6"); // This triggers the automatic flush before adding the new item

$batcher->flush(); // Manually flush remaining items

Example with Ordinality Tracking

This example demonstrates how to track the ordinality of batches (e.g., first, middle, last):

<?php
use DoubleBreak\PhpBatcher\Batcher\Generic;

$batcher = new Generic(11, function($batch, $state) {
    echo "Batch number: " . $state->get('batchNumber') . "\n";
    echo "Total processed items: " . $state->get('totalProcessedItems') . "\n";
    echo "Batch size: " . count($batch) . "\n";
    echo "Items in batch: " . implode(", ", $batch) . "\n";
    echo "Is FIRST: " . ($state->get('ordinality') == Generic::ORDINALITY_FIRST ? 'true' : 'false') . "\n";
    echo "Is LAST: " . ($state->get('ordinality') == Generic::ORDINALITY_LAST ? 'true' : 'false') . "\n";
    echo "Is MIDDLE: " . ($state->get('ordinality') == Generic::ORDINALITY_MIDDLE ? 'true' : 'false') . "\n";
    echo "\n\n";
});

$numbers = range(1, 104);
foreach ($numbers as $number) {
    $batcher->add($number);
}
$batcher->flush();

Example with Custom State Management

This example shows how to manage custom state during batch processing:

<?php
use DoubleBreak\PhpBatcher\Batcher\Generic;

function submit($data) {
    // Simulate a submission process
    echo "Submitting:" . PHP_EOL;
    print_r($data);
    echo PHP_EOL;

    // Simulates downstream logic managing tracking key creation or reuse
    return $data['isFirst'] ? uniqid() : $data['trackingKey'];
}

$batcher = new Generic(11, function($batch, $state) {
    $trackingKey = $state->get('myTrackingKey');

    $data = [
        'isFirst' => $state->get('ordinality') == Generic::ORDINALITY_FIRST,
        'isLast' => $state->get('ordinality') == Generic::ORDINALITY_LAST,
        'items' => $batch,
    ];

    if ($trackingKey !== null) {
        $data['trackingKey'] = $trackingKey;
    }

    $trackingKey = submit($data);

    $state->set('myTrackingKey', $trackingKey);
});

$numbers = range(1, 104);
foreach ($numbers as $number) {
    $batcher->add($number);
}
$batcher->flush();

Development

Running Tests

To run the tests, use PHPUnit:

composer install
vendor/bin/phpunit tests

double-break / php-batcher

Maintainers

Details