Initial commit

Author: David Bohn

.gitignore

@@ -0,0 +1,4 @@
+vendor
+composer.lock
+.idea
+.phpunit.result.cache

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 David Bohn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,47 @@
+# Laravel Lazy Chunk
+
+This library adds the ability to work with chunked query results using lazy collections.
+
+## Motivation
+
+Since Laravel 6, there are Lazy Collections, which are a nice way to use the Collection interface on generated data.
+
+One major use case for these were the database query cursors. This allows to work with a query result, as if all results were fetched,
+but with one query and small memory footprint.
+
+The issue with these cursors is, that eager loading relationships does not work.
+As there is always just one result at hand, eager loads are resolved with one query each.
+
+So if you are working with large data sets that are using relationships, you are still stuck with `chunk()` and `chunkById()`.
+
+Sadly these are still closure methods, which this library changes.
+
+## Usage
+
+Using this library, you gain two new query builder methods:
+
+```php
+Builder::lazyChunk($count, callable $callback = null): LazyCollection;
+```
+
+and
+
+```php
+Builder::lazyChunkById($count, callable $callback = null, $column = null, $alias = null): LazyCollection;
+```
+
+The main difference is, that both methods are now returning lazy collections that resolve the chunks. The callback is now optional.
+You can do this now:
+
+```php
+Article::with('author')->lazyChunk($chunkSize)->flatten(1)->map([$this, 'handleEachArticle']);
+```
+
+You can work with the articles there, as if you would have fetched those all in one query with the benefit of the eager loading.
+But using the chunking, we are not loading all results at once and thus holding memory usage low.
+In fact, the use case of flattening the chunks again to get the elements themselves, is seen as the main use case. Because of this,
+the library offers the `flatLazyChunk` alias:
+
+```php
+Article::with('author')->flatLazyChunk($chunkSize)->map([$this, 'handleEachArticle']);
+```

composer.json

@@ -0,0 +1,36 @@
+{
+    "name": "davidbohn/laravel-lazychunk",
+    "require": {
+        "php": ">=7.2",
+        "illuminate/support": "^6.14",
+        "illuminate/database": "^6.14"
+    },
+    "require-dev": {
+        "orchestra/testbench": "^4.6",
+        "phpunit/phpunit": "^8.5"
+    },
+    "autoload": {
+        "psr-4": {
+            "Dababo\\LazyChunk\\": "src"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Dababo\\LazyChunk\\Tests\\": "tests"
+        }
+    },
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "David Bohn",
+            "email": "davbohn@googlemail.com"
+        }
+    ],
+    "extra": {
+        "laravel": {
+            "providers": [
+                "Dababo\\LazyChunk\\LazyChunkServiceProvider"
+            ]
+        }
+    }
+}

phpunit.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit bootstrap="vendor/autoload.php"
+         backupGlobals="false"
+         backupStaticAttributes="false"
+         colors="true"
+         verbose="true"
+         convertErrorsToExceptions="true"
+         convertNoticesToExceptions="true"
+         convertWarningsToExceptions="true"
+         processIsolation="false"
+         stopOnFailure="false">
+    <testsuites>
+        <testsuite name="Versioning Test Suite">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+    <filter>
+        <whitelist>
+            <directory suffix=".php">src/</directory>
+        </whitelist>
+    </filter>
+</phpunit>

src/LazyChunkMixin.php

@@ -0,0 +1,100 @@
+<?php
+
+
+namespace Dababo\LazyChunk;
+
+
+use Illuminate\Support\LazyCollection;
+
+class LazyChunkMixin
+{
+    public function lazyChunk()
+    {
+        return function ($count, callable $callback = null) {
+            return new LazyCollection(function () use ($count, $callback) {
+
+                $this->enforceOrderBy();
+
+                $page = 1;
+
+                do {
+                    // We'll execute the query for the given page and get the results. If there are
+                    // no results we can just break and return from here. When there are results
+                    // we will call the callback with the current chunk of these results here.
+                    $results = $this->forPage($page, $count)->get();
+
+                    $countResults = $results->count();
+
+                    if ($countResults == 0) {
+                        break;
+                    }
+
+                    yield $page => $results;
+
+                    if ($callback !== null && $callback($results, $page) === false) {
+                        break;
+                    }
+
+                    unset($results);
+
+                    $page++;
+                } while ($countResults == $count);
+            });
+        };
+    }
+
+    public function flatLazyChunk()
+    {
+        return function ($count, callable $callback = null) {
+            return $this->lazyChunk($count, $callback)->flatten(1);
+        };
+    }
+
+    public function lazyChunkById()
+    {
+        return function ($count, callable $callback = null, $column = null, $alias = null) {
+            return new LazyCollection(function () use ($count, $callback, $column, $alias) {
+                $column = $column ?? $this->defaultKeyName();
+
+                $alias = $alias ?? $column;
+
+                $lastId = null;
+
+                do {
+                    $clone = clone $this;
+
+                    // We'll execute the query for the given page and get the results. If there are
+                    // no results we can just break and return from here. When there are results
+                    // we will call the callback with the current chunk of these results here.
+                    $results = $clone->forPageAfterId($count, $lastId, $column)->get();
+
+                    $countResults = $results->count();
+
+                    if ($countResults == 0) {
+                        break;
+                    }
+
+                    yield $results;
+
+                    // On each chunk result set, we will pass them to the callback and then let the
+                    // developer take care of everything within the callback, which allows us to
+                    // keep the memory low for spinning through large result sets for working.
+                    if ($callback !== null && $callback($results) === false) {
+                        return false;
+                    }
+
+                    $lastId = $results->last()->{$alias};
+
+                    unset($results);
+                } while ($countResults == $count);
+            });
+        };
+    }
+
+    public function flatLazyChunkById()
+    {
+        return function ($count, callable $callable = null, $column = null, $alias = null) {
+            return $this->lazyChunkById($count, $callable, $column, $alias)->flatten(1);
+        };
+    }
+}

src/LazyChunkServiceProvider.php

@@ -0,0 +1,19 @@
+<?php
+
+
+namespace Dababo\LazyChunk;
+
+
+use Illuminate\Database\Eloquent\Builder as EloquentBuilder;
+use Illuminate\Database\Query\Builder;
+use Illuminate\Support\ServiceProvider;
+
+class LazyChunkServiceProvider extends ServiceProvider
+{
+    public function register()
+    {
+        Builder::mixin(new LazyChunkMixin());
+
+        EloquentBuilder::mixin(new LazyChunkMixin());
+    }
+}

tests/Helpers/MockCallback.php

@@ -0,0 +1,51 @@
+<?php
+
+
+namespace Dababo\LazyChunk\Tests\Helpers;
+
+
+
+use PHPUnit\Framework\Assert;
+
+class MockCallback {
+    protected $invocations = 0;
+
+    protected $finalInvocations = null;
+
+    public static function mustBeCalled($times = 1, $action = null)
+    {
+        return (new static())->willBeCalled($times)->getCallable($action);
+    }
+
+    public function willBeCalled($times)
+    {
+        $this->finalInvocations = $times;
+
+        return $this;
+    }
+
+    public function __destruct()
+    {
+        if ($this->finalInvocations !== null) {
+            $this->assertHasBeenCalled($this->finalInvocations);
+        }
+    }
+
+    public function getCallable(callable $action = null): callable
+    {
+        return function (...$args) use ($action) {
+            $this->invocations++;
+
+            if ($action !== null) {
+                return $action(...$args);
+            }
+        };
+    }
+
+    public function assertHasBeenCalled($invocations = 1)
+    {
+        Assert::assertSame($invocations, $this->invocations, "The callback was not called correctly!");
+
+        $this->invocations = 0;
+    }
+}