Laravel Datakits

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:

• Complete Usage Guide
• API Reference

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.