ElggBatch.php

Go to the documentation of this file.

<?php

use Elgg\Exceptions\RuntimeException as ElggRuntimeException;

class ElggBatch implements \Countable, \Iterator {

    private $results = [];

    private $getter = null;

    private $options = [];

    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 $reportedFailures = 0;

    public function __construct(callable $getter, array $options, $callback = null, int $chunk_size = 25, bool $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_services()->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 = [];
                    }
                }

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

            $this->callbackResult = $all_results;
        }
    }

    private function getNextResultsChunk(): bool {

        // always reset results.
        $this->results = [];

        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->reportedFailures;
        }

        $current_options = [
            'limit' => $limit,
            'offset' => $offset,
            '__ElggBatch' => $this,
        ];

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

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

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

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

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

            $this->retrievedResults += $num_results;
            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()->queryCache->enable();
            return true;
        }
        
        // no result
        _elgg_services()->queryCache->enable();
        return false;
    }

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

    public function setChunkSize(int $size = 25): void {
        $this->chunkSize = $size;
    }
    
    public function reportFailure(int $num = 1): void {
        $this->reportedFailures += $num;
    }
    
    #[\ReturnTypeWillChange]
    public function rewind() {
        $this->resultIndex = 0;
        $this->retrievedResults = 0;
        $this->processedResults = 0;
        $this->reportedFailures = 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();
        }
    }

    #[\ReturnTypeWillChange]
    public function current() {
        return current($this->results);
    }

    #[\ReturnTypeWillChange]
    public function key() {
        return $this->processedResults;
    }

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

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

            $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;
    }

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

    #[\ReturnTypeWillChange]
    public function count() {
        if (!is_callable($this->getter)) {
            $inspector = new \Elgg\Debug\Inspector();
            throw new ElggRuntimeException('Getter is not callable: ' . $inspector->describeCallable($this->getter));
        }

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

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