Update to PHP 8.2+, modernize CI and test setup

- Require PHP 8.2+ (drop 8.1)
- Add PHP 8.4 to test matrix
- Update dev dependencies (PHPUnit 10.5+/11, Mockery 1.6+, Scout 10.8+/11)
- Upgrade MySQL to 8.4 in CI
- Update PHPUnit config to v11 schema format
- Replace @test annotations with #[Test] attributes
- Clean up FUNDING.yml
- Add CLAUDE.md

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: aarondfrancis

.github/FUNDING.yml

@@ -1,15 +1,2 @@
-# These are supported funding model platforms
-
 github: [aarondfrancis]
-patreon: # Replace with a single Patreon username
-open_collective: # Replace with a single Open Collective username
-ko_fi: # Replace with a single Ko-fi username
-tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
-community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
-liberapay: # Replace with a single Liberapay username
-issuehunt: # Replace with a single IssueHunt username
-lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
-polar: # Replace with a single Polar username
-buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
-thanks_dev: # Replace with a single thanks.dev username
 custom: ['https://aaronfrancis.com/backstage']

.github/workflows/style.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: "8.3"
+          php-version: "8.4"
           extensions: json, dom, curl, libxml, mbstring
           coverage: none
 

.github/workflows/tests.yml

@@ -17,21 +17,15 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php: [8.1, 8.2, 8.3]
+        php: ['8.2', '8.3', '8.4']
         laravel: ['10.*', '11.*', '12.*']
-        dependency-version: [prefer-lowest, prefer-stable]
-
-        exclude:
-          - laravel: 11.*
-            php: 8.1
-          - laravel: 12.*
-            php: 8.1
+        dependency-version: [prefer-stable]
 
     name: P${{ matrix.php }} / L${{ matrix.laravel }} / ${{ matrix.dependency-version }}
 
     services:
       mysql:
-        image: mysql:8.0
+        image: mysql:8.4
         env:
           MYSQL_DATABASE: fast_paginate
           MYSQL_HOST: 127.0.0.1

CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Fast Paginate is a Laravel package that provides an optimized `limit`/`offset` pagination method using a "deferred join" technique. Instead of fetching full rows during pagination, it first retrieves only primary keys in an optimized subquery, then fetches full records for those specific IDs. This significantly improves performance on large datasets.
+
+## Commands
+
+**Run all tests:**
+```bash
+./vendor/bin/phpunit
+```
+
+**Run a specific test file:**
+```bash
+./vendor/bin/phpunit tests/Integration/BuilderTest.php
+```
+
+**Run a specific test method:**
+```bash
+./vendor/bin/phpunit --filter basic_test
+```
+
+**Note:** Tests require a MySQL database (8.4+). Configure via environment variables or `phpunit.xml`:
+- DB_DATABASE=fast_paginate
+- DB_USERNAME=test
+- DB_PASSWORD=root
+
+## Architecture
+
+The package registers macros on Laravel's Eloquent Builder and Relation classes via `FastPaginateProvider`:
+
+- **`FastPaginate`** (`src/FastPaginate.php`): Core pagination logic. Implements `fastPaginate()` and `simpleFastPaginate()` methods that:
+  1. Clone the query and select only primary keys
+  2. Run pagination on the key-only query
+  3. Use the retrieved IDs in a `WHERE IN` clause on the original query
+  4. Return full records with proper pagination metadata
+
+- **`BuilderMixin`** (`src/BuilderMixin.php`): Adds `fastPaginate()` and `simpleFastPaginate()` methods to Eloquent Builder
+
+- **`RelationMixin`** (`src/RelationMixin.php`): Adds the same methods to Eloquent Relations, with special handling for `BelongsToMany` and `HasManyThrough`
+
+- **`ScoutMixin`** (`src/ScoutMixin.php`): Provides `fastPaginate()` on Laravel Scout builders (defers to standard pagination as Scout already optimizes)
+
+### Fallback Behavior
+
+The package automatically falls back to standard pagination when:
+- Query contains `havings`, `groups`, or `unions`
+- `perPage` is set to `-1` (get all records)
+- Query contains incompatible expressions (detected via `QueryIncompatibleWithFastPagination`)
+
+### Key Implementation Detail
+
+Order-by columns that reference computed/aliased columns are preserved in the inner query to maintain correct ordering during the key-selection phase.

README.md

@@ -34,7 +34,7 @@ sure to test on your data!
 
 ## Installation
 
-This package supports Laravel 10, 11, and 12.
+This package supports Laravel 10, 11, and 12, and requires PHP 8.2 or higher.
 
 To install, require the package via composer:
 

composer.json

@@ -10,14 +10,14 @@
         }
     ],
     "require": {
-        "php": "^8.1",
+        "php": "^8.2",
         "illuminate/database": "^10.0|^11.0|^12.0"
     },
     "require-dev": {
         "orchestra/testbench": "^8.0|^9.0|^10.0",
-        "mockery/mockery": "^1.3.3",
-        "phpunit/phpunit": ">=8.5.23|^9|^10",
-        "laravel/scout": "^9.4|^10.8"
+        "mockery/mockery": "^1.6",
+        "phpunit/phpunit": "^10.5|^11.0",
+        "laravel/scout": "^10.8|^11.0"
     },
     "autoload": {
         "psr-4": {

phpunit.xml.dist

@@ -1,10 +1,18 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" bootstrap="vendor/autoload.php" backupGlobals="false" colors="true" processIsolation="false" stopOnFailure="false" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.0/phpunit.xsd" cacheDirectory=".phpunit.cache" backupStaticProperties="false">
-  <coverage>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         bootstrap="vendor/autoload.php"
+         backupGlobals="false"
+         colors="true"
+         processIsolation="false"
+         stopOnFailure="false"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.0/phpunit.xsd"
+         cacheDirectory=".phpunit.cache"
+         backupStaticProperties="false">
+  <source>
     <include>
       <directory suffix=".php">src/</directory>
     </include>
-  </coverage>
+  </source>
   <testsuites>
     <testsuite name="unit">
       <directory>tests/Unit</directory>

tests/Integration/BuilderTest.php

@@ -16,14 +16,15 @@
 use Illuminate\Database\QueryException;
 use Illuminate\Pagination\LengthAwarePaginator;
 use Illuminate\Pagination\Paginator;
+use PHPUnit\Framework\Attributes\Test;
 
 class BuilderTest extends Base
 {
     private const TOTAL_USERS = 29;
 
     private const TOTAL_POSTS_FIRST_USER = 1;
 
-    /** @test */
+    #[Test]
     public function basic_test()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -46,7 +47,7 @@ public function basic_test()
         $this->assertEquals(self::TOTAL_USERS, $results->total());
     }
 
-    /** @test */
+    #[Test]
     public function different_page_size()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -66,7 +67,7 @@ public function different_page_size()
         $this->assertEquals(self::TOTAL_USERS, $results->total());
     }
 
-    /** @test */
+    #[Test]
     public function page_2()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -86,7 +87,7 @@ public function page_2()
         $this->assertEquals(self::TOTAL_USERS, $results->total());
     }
 
-    /** @test */
+    #[Test]
     public function pk_attribute_mutations_are_skipped()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -102,7 +103,7 @@ public function pk_attribute_mutations_are_skipped()
         );
     }
 
-    /** @test */
+    #[Test]
     public function custom_page_is_preserved()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -122,7 +123,7 @@ public function custom_page_is_preserved()
         $this->assertEquals(self::TOTAL_USERS, $results->total());
     }
 
-    /** @test */
+    #[Test]
     public function not_exists_page_is_preserved()
     {
         $exists = User::query()->fastPaginate();
@@ -140,7 +141,7 @@ public function not_exists_page_is_preserved()
         $this->assertFalse($doesnt->hasMorePages());
     }
 
-    /** @test */
+    #[Test]
     public function custom_table_is_preserved()
     {
         $this->expectException(QueryException::class);
@@ -149,7 +150,7 @@ public function custom_table_is_preserved()
         UserCustomTable::query()->fastPaginate();
     }
 
-    /** @test */
+    #[Test]
     public function order_is_propagated()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -162,7 +163,7 @@ public function order_is_propagated()
         );
     }
 
-    /** @test */
+    #[Test]
     public function order_by_raw_is_propagated()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -175,7 +176,7 @@ public function order_by_raw_is_propagated()
         );
     }
 
-    /** @test */
+    #[Test]
     public function eager_loads_are_cleared_on_inner_query()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -192,7 +193,7 @@ public function eager_loads_are_cleared_on_inner_query()
         );
     }
 
-    /** @test */
+    #[Test]
     public function eager_loads_are_loaded_on_outer_query()
     {
         $this->withQueriesLogged(function () use (&$results) {
@@ -203,7 +204,7 @@ public function eager_loads_are_loaded_on_outer_query()
         $this->assertEquals(1, $results->first()->posts->count());
     }
 
-    /** @test */
+    #[Test]
     public function selects_are_overwritten()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -223,7 +224,7 @@ public function selects_are_overwritten()
         );
     }
 
-    /** @test */
+    #[Test]
     public function unquoted_selects_are_preserved_if_used_in_order_by()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -236,7 +237,7 @@ public function unquoted_selects_are_preserved_if_used_in_order_by()
         );
     }
 
-    /** @test */
+    #[Test]
     public function using_expressions_for_order_work()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -251,7 +252,7 @@ public function using_expressions_for_order_work()
         );
     }
 
-    /** @test */
+    #[Test]
     public function havings_defer()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -268,7 +269,7 @@ public function havings_defer()
         );
     }
 
-    /** @test */
+    #[Test]
     public function standard_with_count_works()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -287,7 +288,7 @@ public function standard_with_count_works()
         $this->assertEquals(self::TOTAL_USERS, $results->total());
     }
 
-    /** @test */
+    #[Test]
     public function aliased_with_count()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -301,7 +302,7 @@ public function aliased_with_count()
         );
     }
 
-    /** @test */
+    #[Test]
     public function unordered_with_count_is_ignored()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -315,7 +316,7 @@ public function unordered_with_count_is_ignored()
         );
     }
 
-    /** @test */
+    #[Test]
     public function uuids_are_bound_correctly()
     {
         $this->seedStringNotifications();
@@ -334,7 +335,7 @@ public function uuids_are_bound_correctly()
         $this->assertEquals('64bf6df6-06d7-11ed-b939-0001', $queries[2]['bindings'][0]);
     }
 
-    /** @test */
+    #[Test]
     public function groups_are_skipped()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -348,7 +349,7 @@ public function groups_are_skipped()
         );
     }
 
-    /** @test */
+    #[Test]
     public function basic_simple_test()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -370,7 +371,7 @@ public function basic_simple_test()
         $this->assertEquals(1, $results->currentPage());
     }
 
-    /** @test */
+    #[Test]
     public function basic_simple_test_page_two()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -392,7 +393,7 @@ public function basic_simple_test_page_two()
         $this->assertEquals(2, $results->currentPage());
     }
 
-    /** @test */
+    #[Test]
     public function basic_simple_test_from_relation()
     {
         $queries = $this->withQueriesLogged(function () use (&$results) {
@@ -414,15 +415,15 @@ public function basic_simple_test_from_relation()
         $this->assertEquals(1, $results->currentPage());
     }
 
-    /** @test */
+    #[Test]
     public function custom_collection_is_preserved()
     {
         $results = UserWithCustomCollection::query()->simpleFastPaginate();
 
         $this->assertInstanceOf(UserCollection::class, $results->getCollection());
     }
 
-    /** @test */
+    #[Test]
     public function with_sum_has_the_correct_number_of_parameters()
     {
         $queries = $this->withQueriesLogged(function () use (&$fast, &$regular) {