Download the PHP package companue/auto-paginate without Composer

Companue Auto-Paginate

A Laravel package that provides automatic API pagination with infinite scroll support. Add pagination to any controller endpoint with just one line of code!

Features

• ✅ One-Line Integration - Add pagination with a single method call
• ✅ Automatic Scroll Detection - Perfect for infinite scroll UIs
• ✅ Consistent Response Format - Standardized across all endpoints
• ✅ Backward Compatible - Supports both paginated and non-paginated responses
• ✅ Flexible - Works with Query Builders and Collections
• ✅ Type Safe - Full PHP type hints and return types
• ✅ Zero Configuration - Works out of the box

Installation

Install via Composer:

The package will automatically register its service provider.

Quick Installation

Run the installation command for an interactive setup:

This will guide you through two installation options:

1. Publish AutoPaginatedController (Recommended) - Extend your controllers from it
2. Update base Controller.php - Inject trait directly into the base controller

Manual Installation Options

Option 1: Publish AutoPaginatedController (Recommended)

Publish the AutoPaginatedController to your project:

Or use the command with the default option:

This creates app/Http/Controllers/API/AutoPaginatedController.php with pagination methods built-in.

Then update your API controllers to extend it:

Alternative: Use Trait Directly

If you prefer not to use AutoPaginatedController, add the trait to your controllers:

Option 2: Update Base Controller (Direct Injection)

Inject the trait directly into your base Controller.php:

This will:

• Create a backup of your Controller.php at app/Http/Controllers/Controller.php.backup
• Add use Companue\AutoPaginate\Traits\PaginatesQueries; import statement
• Add PaginatesQueries to your existing trait list in the Controller class

Before:

After:

After installation, all your controllers will have pagination methods without extending anything:

Usage

Basic Usage

Add the trait to your base controller or any specific controller:

Then in your controller methods:

That's it! Your endpoint now supports pagination.

With Filters

Custom Page Size

Without Resource Transformation

Paginating Collections

API Requests

Paginated Requests

Non-Paginated Requests

Response Format

Paginated Response

Non-Paginated Response

Available Methods

indexResponse($query, $resourceClass = null, $request = null)

Smart method that automatically handles pagination based on request parameters.

Parameters:

• $query - Query Builder or Collection
• $resourceClass - Optional resource class for transformation
• $request - Optional request object (defaults to request())

Returns: Array with data and pagination info, or raw collection

applyPagination($query, $request = null, $defaultPerPage = 15)

Manually apply pagination to a query or collection.

Parameters:

• $query - Query Builder or Collection
• $request - Optional request object
• $defaultPerPage - Default items per page (default: 15, max: 100)

Returns: LengthAwarePaginator

paginatedResponse($paginator, $resourceClass = null)

Build standardized paginated response from a paginator.

Parameters:

• $paginator - LengthAwarePaginator instance
• $resourceClass - Optional resource class

Returns: Array with data and pagination metadata

shouldPaginate($request = null)

Check if pagination should be applied based on request.

Parameters:

• $request - Optional request object

Returns: Boolean

Configuration

The package works with sensible defaults:

• Default page size: 15 items
• Maximum page size: 100 items
• Pagination parameter: page
• Page size parameter: per_page

Frontend Integration

Perfect for infinite scroll implementations:

Migration from Manual Pagination

Before:

After:

Testing

Requirements

• PHP 8.1 or higher
• Laravel 10.0, 11.0, or 12.0

License

The MIT License (MIT). Please see License File for more information.

Credits

• mimalefdal
• All Contributors

Support

For support, please open an issue on GitHub or contact [email protected]