Merge pull request #77 from aarondfrancis/fix-74

Fix #74: Add $total parameter to fastPaginate()

Author: aarondfrancis

.claude/commands/issue.md

@@ -0,0 +1,29 @@
+Fix GitHub issue #$ARGUMENTS
+
+Follow these steps:
+
+1. **Fetch the issue**: Use `gh issue view $ARGUMENTS` to read the issue details from the GitHub repository. Understand what the bug or feature request is about.
+
+2. **Create a branch**: Create and checkout a new branch named `fix-$ARGUMENTS` from main:
+   ```
+   git checkout -b fix-$ARGUMENTS
+   ```
+
+3. **Write a failing test**: Based on the issue description, write a test that reproduces the problem. The test should fail initially, demonstrating the bug exists.
+
+4. **Run the test**: Execute the failing test to confirm it fails as expected. If the test requires a database and fails due to connection issues, that's acceptable - focus on the test logic being correct.
+
+5. **Diagnose the issue**: Analyze the codebase to understand why the bug occurs. Look at the relevant source files and trace through the logic.
+
+6. **Implement the fix**: Make the necessary code changes to fix the issue. Keep changes minimal and focused.
+
+7. **Verify the fix**: Run the test again to confirm it now passes (or would pass with a database connection).
+
+8. **Commit and push**: Stage all changes, commit with a descriptive message referencing the issue number, and push the branch:
+   ```
+   git add -A
+   git commit -m "Fix #$ARGUMENTS: <brief description>"
+   git push -u origin fix-$ARGUMENTS
+   ```
+
+9. **Report**: Summarize what was done, what the fix was, and provide the branch name for creating a PR.

.claude/settings.local.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(composer update:*)",
+      "Bash(./vendor/bin/phpunit:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(gh issue view:*)",
+      "Bash(gh api:*)",
+      "Bash(git checkout:*)",
+      "Bash(php -l:*)",
+      "Bash(git push:*)",
+      "Bash(git remote set-url:*)",
+      "Bash(gh run list:*)",
+      "Bash(gh run view:*)",
+      "Bash(gh run watch:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

CHANGELOG.md

@@ -1,3 +1,4 @@
 # Changelog
 ## Unreleased
 - Add default `ORDER BY` primary key when no order is specified to ensure deterministic pagination results ([#73](https://github.com/aarondfrancis/fast-paginate/issues/73))
+- Add `$total` parameter to `fastPaginate()` to allow skipping the COUNT query ([#74](https://github.com/aarondfrancis/fast-paginate/issues/74))

src/FastPaginate.php

@@ -11,6 +11,21 @@
 
 class FastPaginate
 {
+    /**
+     * Laravel 11+ added a $total parameter to paginate(). We need to
+     * conditionally pass it to avoid errors on Laravel 10.
+     *
+     * @internal
+     */
+    public static function callPaginator($builder, string $method, $perPage, $columns, $pageName, $page, $total)
+    {
+        if (version_compare(app()->version(), '11.0.0', '>=')) {
+            return $builder->{$method}($perPage, $columns, $pageName, $page, $total);
+        }
+
+        return $builder->{$method}($perPage, $columns, $pageName, $page);
+    }
+
     public function fastPaginate()
     {
         return $this->paginate('paginate', function (array $items, $paginator) {
@@ -38,7 +53,7 @@ public function simpleFastPaginate()
 
     protected function paginate(string $paginationMethod, Closure $paginatorOutput)
     {
-        return function ($perPage = null, $columns = ['*'], $pageName = 'page', $page = null) use (
+        return function ($perPage = null, $columns = ['*'], $pageName = 'page', $page = null, $total = null) use (
             $paginationMethod,
             $paginatorOutput
         ) {
@@ -48,7 +63,7 @@ protected function paginate(string $paginationMethod, Closure $paginatorOutput)
             // we are counting on each row of the inner query to return a primary key
             // that we can use. When grouping, that's not always the case.
             if (filled($base->havings) || filled($base->groups) || filled($base->unions)) {
-                return $this->{$paginationMethod}($perPage, $columns, $pageName, $page);
+                return FastPaginate::callPaginator($this, $paginationMethod, $perPage, $columns, $pageName, $page, $total);
             }
 
             $model = $this->newModelInstance();
@@ -60,13 +75,13 @@ protected function paginate(string $paginationMethod, Closure $paginatorOutput)
             // fast pagination, we'll just return the normal paginator in that case.
             // https://github.com/aarondfrancis/fast-paginate/issues/39
             if ($perPage === -1) {
-                return $this->{$paginationMethod}($perPage, $columns, $pageName, $page);
+                return FastPaginate::callPaginator($this, $paginationMethod, $perPage, $columns, $pageName, $page, $total);
             }
 
             try {
                 $innerSelectColumns = FastPaginate::getInnerSelectColumns($this);
             } catch (QueryIncompatibleWithFastPagination $e) {
-                return $this->{$paginationMethod}($perPage, $columns, $pageName, $page);
+                return FastPaginate::callPaginator($this, $paginationMethod, $perPage, $columns, $pageName, $page, $total);
             }
 
             // If no order is specified, we need to add a default order by
@@ -79,15 +94,16 @@ protected function paginate(string $paginationMethod, Closure $paginatorOutput)
 
             // This is the copy of the query that becomes
             // the inner query that selects keys only.
-            $paginator = $this->clone()
+            $innerQuery = $this->clone()
                 // Only select the primary key, we'll get the full
                 // records in a second query below.
                 ->select($innerSelectColumns)
                 // We don't need eager loads for this cloned query, they'll
                 // remain on the query that actually gets the records.
                 // (withoutEagerLoads not available on Laravel 8.)
-                ->setEagerLoads([])
-                ->{$paginationMethod}($perPage, ['*'], $pageName, $page);
+                ->setEagerLoads([]);
+
+            $paginator = FastPaginate::callPaginator($innerQuery, $paginationMethod, $perPage, ['*'], $pageName, $page, $total);
 
             // Get the key values from the records on the current page without mutating them.
             $ids = $paginator->getCollection()->map->getRawOriginal($key)->toArray();

tests/Integration/BuilderTest.php

@@ -87,6 +87,29 @@ public function page_2()
         $this->assertEquals(self::TOTAL_USERS, $results->total());
     }
 
+    #[Test]
+    public function total_can_be_passed_to_skip_count_query()
+    {
+        $queries = $this->withQueriesLogged(function () use (&$results) {
+            // Pass a custom total to skip the COUNT(*) query
+            $results = User::query()->fastPaginate(5, ['*'], 'page', 1, 100);
+        });
+
+        /** @var \Illuminate\Pagination\LengthAwarePaginator $results */
+        $this->assertEquals(5, $results->count());
+
+        // The $total parameter was added in Laravel 11. On Laravel 10,
+        // we can't pass it through, so the COUNT query still runs.
+        if (version_compare(app()->version(), '11.0.0', '>=')) {
+            // Should only be 2 queries (inner select + outer select), no COUNT query
+            $this->assertCount(2, $queries);
+
+            // The total should be the custom value we passed
+            $this->assertEquals(100, $results->total());
+            $this->assertTrue($results->hasMorePages());
+        }
+    }
+
     #[Test]
     public function pk_attribute_mutations_are_skipped()
     {