README

A lightweight Laravel package for custom query pagination with a standardized pagination response structure.

Features

• Custom pagination implementation
• Supports query builders and Eloquent models
• Configurable page size via request query parameters
• Returns pagination metadata
• Laravel 11 & Laravel 12 compatible

Installation

Install via Composer:

composer require oyedele/laravel-custom-pagination

Laravel auto-discovery will automatically register the service provider.

Package Structure

laravel-custom-pagination/
├── src/
│   ├── Traits/
│   │   └── CustomPagination.php
│   └── CustomPaginationServiceProvider.php
├── tests/
├── composer.json
├── README.md
└── LICENSE

Trait

<?php

namespace Oyedele\CustomPagination\Traits;

trait CustomPagination
{
    public function paginate(
        object $request,
        $model,
        $otherParams = null
    ): array {
        $records_per_page = $request->query('per_page') ?? 20;
        $page = intval($request->query('page'));

        $totalRecords = $model->count();

        $pagination = [
            'total' => null,
            'current' => null,
            'from' => null,
            'to' => null,
            'pages' => null,
        ];

        $page = ($page > 1) ? $page : 1;

        $offset = ($page > 1)
            ? ($records_per_page * ($page - 1))
            : 0;

        $pages = ceil($totalRecords / $records_per_page);

        $modelRecords = $model
            ->offset($offset)
            ->limit($records_per_page)
            ->get();

        if ($modelRecords->count()) {
            $pagination['total'] = $totalRecords;
            $pagination['current'] = $page;
            $pagination['from'] = $offset + 1;
            $pagination['to'] = min(
                $offset + $records_per_page,
                $totalRecords
            );
            $pagination['pages'] = $pages;
        }

        return [
            'data' => $modelRecords,
            'pagination' => $pagination
        ];
    }
}

Usage

Import the trait:

use Oyedele\CustomPagination\Traits\CustomPagination;

class UserController extends Controller
{
    use CustomPagination;
}

Example

public function index(Request $request)
{
    $users = User::query();

    $result = $this->paginate(
        $request,
        $users
    );

    return response()->json([
        'status' => true,
        'message' => 'Users retrieved successfully',
        'data' => $result['data'],
        'pagination' => $result['pagination']
    ]);
}

Request Example

GET /api/users?page=2&per_page=10

Response Example

{
    "status": true,
    "message": "Users retrieved successfully",
    "data": [
        {
            "id": 11,
            "name": "John Doe"
        }
    ],
    "pagination": {
        "total": 100,
        "current": 2,
        "from": 11,
        "to": 20,
        "pages": 10
    }
}

Service Provider

<?php

namespace Oyedele\CustomPagination;

use Illuminate\Support\ServiceProvider;

class CustomPaginationServiceProvider extends ServiceProvider
{
    public function register(): void
    {
    }

    public function boot(): void
    {
    }
}

composer.json

{
    "name": "oyedele/laravel-custom-pagination",
    "description": "Custom pagination helper for Laravel applications.",
    "type": "library",
    "license": "MIT",
    "autoload": {
        "psr-4": {
            "Oyedele\\CustomPagination\\": "src/"
        }
    },
    "extra": {
        "laravel": {
            "providers": [
                "Oyedele\\CustomPagination\\CustomPaginationServiceProvider"
            ]
        }
    },
    "require": {
        "php": "^8.2",
        "illuminate/support": "^11.0|^12.0"
    }
}

Versioning

Create your first release:

git tag v1.0.0
git push origin v1.0.0

Subsequent releases:

git tag v1.0.1
git push origin v1.0.1

Requirements

• PHP 8.2+
• Laravel 11+
• Laravel 12+

License

MIT License.