README

A powerful Laravel library for server-side pagination with advanced search, filtering, and sorting capabilities. Perfect for building data tables, card views, and list interfaces with complex data requirements.

Features

Advanced pagination with search, filter, and sorting
Flexible search across multiple columns including relationships
Easy filtering with key-value pairs or whereIn conditions
Sorting by any column including related table columns
Cursor-based pagination for large datasets
Customizable response format including camelCase conversion
Configurable through simple config file
Easy to use with trait-based implementation

Requirements

PHP 8.2 or higher
Laravel 11.x or 12.x

Installation

Install the package via Composer:

composer require refkinscallv/laravel-datakits

The package will automatically register its service provider.

Publish Configuration (Optional)

If you want to customize the configuration, publish the config file:

php artisan vendor:publish --tag=datakits-config

This will create a config/datakits.php file in your application.

Quick Start

Step 1: Add Trait to Your Model

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use RF\Datakits\Traits\HasPagination;

class Product extends Model
{
    use HasPagination;

    protected $fillable = ['name', 'description', 'price', 'category_id'];

    public function category()
    {
        return $this->belongsTo(Category::class);
    }

    public static function getSearchableColumns(): array
    {
        return ['name', 'description', 'sku', 'category.name'];
    }

    public static function getFilterableColumns(): array
    {
        return ['category_id', 'status'];
    }

    public static function getSortableColumns(): array
    {
        return ['name', 'price', 'created_at'];
    }
}

Step 2: Use in Controller

<?php

namespace App\Http\Controllers;

use App\Models\Product;
use Illuminate\Http\Request;

class ProductController extends Controller
{
    public function index(Request $request)
    {
        $result = Product::query()->paginateWithOptions([
            'search' => $request->get('search'),
            'search_columns' => Product::getSearchableColumns(),
            'order_by' => $request->get('order_by', 'created_at'),
            'order_direction' => $request->get('order_direction', 'desc'),
            'per_page' => $request->get('per_page', 15),
            'filters' => [
                'category_id' => $request->get('category_id'),
                'status' => $request->get('status'),
            ],
        ]);

        return response()->json($result);
    }
}

Step 3: Make API Request

GET /api/products?search=laptop&category_id=1&order_by=price&order_direction=asc&per_page=20&page=1

Response Format

{
    "data": [
        {
            "id": 1,
            "name": "Gaming Laptop",
            "price": 1500,
            "category_id": 1
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 50,
        "total_pages": 3,
        "has_more": true,
        "next_page": 2,
        "prev_page": null,
        "from": 1,
        "to": 20
    },
    "options": {
        "search": "laptop",
        "order_by": "price",
        "order_direction": "asc",
        "filters": {
            "category_id": 1
        }
    }
}

Basic Usage Examples

Simple Pagination

$result = Product::query()->customPaginate(page: 1, perPage: 15);

Cursor Pagination (for large datasets)

$result = Product::query()->customCursorPaginate(perPage: 50);

Using Facade

use RF\Datakits\Facades\Datakits;

$result = Datakits::paginateWithOptions(Product::query(), [
    'search' => 'laptop',
    'search_columns' => ['name', 'description'],
    'per_page' => 20,
]);

Configuration

The configuration file provides several options to customize the behavior:

return [
    'pagination' => [
        'default_per_page' => 12,
        'max_per_page' => 100,
        'default_order_direction' => 'desc',
        'allowed_order_directions' => ['asc', 'desc'],
    ],
    'search' => [
        'wildcard_position' => 'both', // 'both', 'start', or 'end'
    ],
    'response' => [
        'include_options' => true,
        'camel_case_keys' => false,
    ],
];

Advanced Features

Search with Relationships

$result = Product::with('category')->paginateWithOptions([
    'search' => 'electronics',
    'search_columns' => ['name', 'description', 'category.name'],
]);

Multiple Filters

$result = Product::query()->paginateWithOptions([
    'filters' => [
        'category_id' => [1, 2, 3], // whereIn
        'status' => 'active',        // where
        'featured' => true,
    ],
]);

Sort by Related Column

$result = Product::query()->paginateWithOptions([
    'order_by' => 'category.name',
    'order_direction' => 'asc',
]);

Documentation

For detailed documentation, please refer to:

Testing

Run the test suite:

composer test

Run tests with coverage:

composer test-coverage

Code Quality

Format code with Laravel Pint:

composer format

Run static analysis with Larastan:

composer analyse

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security

If you discover any security related issues, please email refkinscallv@gmail.com instead of using the issue tracker.

Credits

Refkinscallv

License

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

refkinscallv / laravel-datakits

Maintainers

Details