/root/Elgg/engine/classes/ElggBatch.php

A lazy-loading proxy for a result array from a fetching functionA batch can be counted or iterated over via foreach, where the batch will internally fetch results several rows at a time. This allows you to efficiently work on large result sets without loading all results in memory.

A batch can run operations for any function that supports an options array and supports the keys "offset", "limit", and "count". This is usually used with elgg_get_entities() and friends, elgg_get_annotations(), and elgg_get_metadata(). In fact, those functions will return results as batches by passing in "batch" as true.

Unlike a real array, direct access of results is not supported.

If you pass a valid PHP callback, all results will be run through that callback. You can still foreach() through the result set after. Valid PHP callbacks can be a string, an array, or a closure. http://php.net/manual/en/language.pseudo-types.php

The callback function must accept 3 arguments: an entity, the getter used, and the options used.

Results from the callback are stored in callbackResult. If the callback returns only booleans, callbackResults will be the combined result of all calls. If no entities are processed, callbackResults will be null.

If the callback returns anything else, callbackresult will be an indexed array of whatever the callback returns. If returning error handling information, you should include enough information to determine which result you're referring to.

Don't combine returning bools and returning something else.

Note that returning false will not stop the foreach.

Warning

If your callback or foreach loop deletes or disable entities you MUST call setIncrementOffset(false) or set that when instantiating. This forces the offset to stay what it was in the $options array.

// using foreach $batch = new ('elgg_get_entities', array()); $batch->setIncrementOffset(false);

foreach ($batch as $entity) { $entity->disable(); }

// using both a callback $callback = function($result, $getter, $options) { var_dump("Looking at annotation id: $result->id"); return true; }

$batch = new ('elgg_get_annotations', array('guid' => 2), $callback);

// get a batch from an Elgg getter function $batch = elgg_get_entities([ 'batch' => true, ]);

<?php

use Elgg\BatchResult;

class ElggBatch implements BatchResult {

    private $results = array();

    private $getter = null;

    private $options = array();

    private $chunkSize = 25;

    private $callback = null;

    private $offset = 0;

    private $limit = 0;

    private $retrievedResults = 0;

    private $resultIndex = 0;

    private $chunkIndex = 0;

    private $processedResults = 0;

    private $validGetter = null;

    public $callbackResult = null;

    private $incrementOffset = true;

    private $incompleteEntities = array();

    private $totalIncompletes = 0;

    public function __construct($getter, $options, $callback = null, $chunk_size = 25,
            $inc_offset = true) {
        
        $this->getter = $getter;
        $this->options = $options;
        $this->callback = $callback;
        $this->chunkSize = $chunk_size;
        $this->setIncrementOffset($inc_offset);

        if ($this->chunkSize <= 0) {
            $this->chunkSize = 25;
        }

        // store these so we can compare later
        $this->offset = elgg_extract('offset', $options, 0);
        $this->limit = elgg_extract('limit', $options, elgg_get_config('default_limit'));

        // if passed a callback, create a new \ElggBatch with the same options
        // and pass each to the callback.
        if ($callback && is_callable($callback)) {
            $batch = new \ElggBatch($getter, $options, null, $chunk_size, $inc_offset);

            $all_results = null;

            foreach ($batch as $result) {
                $result = call_user_func($callback, $result, $getter, $options);

                if (!isset($all_results)) {
                    if ($result === true || $result === false || $result === null) {
                        $all_results = $result;
                    } else {
                        $all_results = array();
                    }
                }

                if (($result === true || $result === false || $result === null) && !is_array($all_results)) {
                    $all_results = $result && $all_results;
                } else {
                    $all_results[] = $result;
                }
            }

            $this->callbackResult = $all_results;
        }
    }

    public function reportIncompleteEntity(\stdClass $row) {
        $this->incompleteEntities[] = $row;
    }

    private function getNextResultsChunk() {

        // always reset results.
        $this->results = array();

        if (!isset($this->validGetter)) {
            $this->validGetter = is_callable($this->getter);
        }

        if (!$this->validGetter) {
            return false;
        }

        $limit = $this->chunkSize;

        // if someone passed limit = 0 they want everything.
        if ($this->limit != 0) {
            if ($this->retrievedResults >= $this->limit) {
                return false;
            }

            // if original limit < chunk size, set limit to original limit
            // else if the number of results we'll fetch if greater than the original limit
            if ($this->limit < $this->chunkSize) {
                $limit = $this->limit;
            } elseif ($this->retrievedResults + $this->chunkSize > $this->limit) {
                // set the limit to the number of results remaining in the original limit
                $limit = $this->limit - $this->retrievedResults;
            }
        }

        if ($this->incrementOffset) {
            $offset = $this->offset + $this->retrievedResults;
        } else {
            $offset = $this->offset + $this->totalIncompletes;
        }

        $current_options = array(
            'limit' => $limit,
            'offset' => $offset,
            '__ElggBatch' => $this,
        );

        $options = array_merge($this->options, $current_options);

        $this->incompleteEntities = array();
        $this->results = call_user_func($this->getter, $options);

        // batch result sets tend to be large; we don't want to cache these.
        _elgg_services()->db->disableQueryCache();

        $num_results = count($this->results);
        $num_incomplete = count($this->incompleteEntities);

        $this->totalIncompletes += $num_incomplete;

        if ($this->incompleteEntities) {
            // pad the front of the results with nulls representing the incompletes
            array_splice($this->results, 0, 0, array_pad(array(), $num_incomplete, null));
            // ...and skip past them
            reset($this->results);
            for ($i = 0; $i < $num_incomplete; $i++) {
                next($this->results);
            }
        }

        if ($this->results) {
            $this->chunkIndex++;

            // let the system know we've jumped past the nulls
            $this->resultIndex = $num_incomplete;

            $this->retrievedResults += ($num_results + $num_incomplete);
            if ($num_results == 0) {
                // This fetch was *all* incompletes! We need to fetch until we can either
                // offer at least one row to iterate over, or give up.
                return $this->getNextResultsChunk();
            }
            _elgg_services()->db->enableQueryCache();
            return true;
        } else {
            _elgg_services()->db->enableQueryCache();
            return false;
        }
    }

    public function setIncrementOffset($increment = true) {
        $this->incrementOffset = (bool) $increment;
    }

    public function rewind() {
        $this->resultIndex = 0;
        $this->retrievedResults = 0;
        $this->processedResults = 0;

        // only grab results if we haven't yet or we're crossing chunks
        if ($this->chunkIndex == 0 || $this->limit > $this->chunkSize) {
            $this->chunkIndex = 0;
            $this->getNextResultsChunk();
        }
    }

    public function current() {
        return current($this->results);
    }

    public function key() {
        return $this->processedResults;
    }

    public function next() {
        // if we'll be at the end.
        if (($this->processedResults + 1) >= $this->limit && $this->limit > 0) {
            $this->results = array();
            return false;
        }

        // if we'll need new results.
        if (($this->resultIndex + 1) >= $this->chunkSize) {
            if (!$this->getNextResultsChunk()) {
                $this->results = array();
                return false;
            }

            $result = current($this->results);
        } else {
            // the function above resets the indexes, so only inc if not
            // getting new set
            $this->resultIndex++;
            $result = next($this->results);
        }

        $this->processedResults++;
        return $result;
    }

    public function valid() {
        if (!is_array($this->results)) {
            return false;
        }
        $key = key($this->results);
        return ($key !== null && $key !== false);
    }

    public function count() {
        if (!is_callable($this->getter)) {
            $inspector = new \Elgg\Debug\Inspector();
            throw new RuntimeException("Getter is not callable: " . $inspector->describeCallable($this->getter));
        }

        $options = array_merge($this->options, ['count' => true]);

        return call_user_func($this->getter, $options);
    }

    public function __get($name) {
        if ($name === 'options') {
            elgg_deprecated_notice("The ElggBatch 'options' property is private and should not be used", "2.3");
            return $this->options;
        }

        _elgg_services()->logger->warn("Read of non-existent property '$name'");
        return null;
    }

    public function __set($name, $value) {
        if ($name === 'options') {
            elgg_deprecated_notice("The ElggBatch 'options' property is private and should not be used", "2.3");
        }

        $this->{$name} = $value;
    }
}