README

A high-performance, feature-rich Laravel package for creating responsive DataTables with real-time search, sorting, filtering, pagination, and advanced export capabilities (CSV, PDF, XLSX, Image) without page reloads.

🚨 Quick Fix for Common Errors

Error: "Can't locate path: .../Resources/dist"

Solution: Build the assets first!

# Windows (PowerShell)
.\quick-fix.bat

# Linux/Mac
chmod +x quick-fix.sh
./quick-fix.sh

OR manually:

cd vendor/subhashladumor/laravel-datatablepro
npm install
npm run build
cd ../../..
php artisan vendor:publish --provider="SubhashLadumor1\\DataTablePro\\Providers\\DataTableServiceProvider" --tag="datatable-assets" --force

Error: "DTable is not defined"

Solution: Make sure your layout has:

<!-- In <head> -->
@stack('styles')

<!-- Before </body> -->
@stack('scripts')

See BUILD.md for detailed troubleshooting.

Features

✨ Core Features:

Fluent, Yajra-compatible API
Eloquent, Query Builder, and Collection support
Real-time search across multiple columns and relationships
Multi-column sorting (including relationship columns)
Advanced filtering (text, select, date-range, numeric-range, custom callbacks)
Responsive design with mobile card layout
Server-side and client-side rendering
XSS protection with safe HTML escaping

🚀 Advanced Features:

Export System: CSV (streaming), XLSX (chunked & queued), PDF, Image (html2canvas)
Virtual Scrolling: Handle large datasets efficiently
Realtime Updates: Polling or WebSocket support
Column Persistence: Save column visibility and order per user
Custom Renderers: Built-in renderers (link, avatar, badge, date, currency, etc.)
Whitelisting: Secure column and relationship access control
Deep Linking: History API integration for shareable states

Requirements

PHP ^8.2
Laravel ^10.0 | ^11.0

Installation

composer require subhashladumor/laravel-datatablepro

Optional Dependencies

# For XLSX export
composer require maatwebsite/excel

# For PDF export
composer require barryvdh/laravel-dompdf

# For advanced image processing
composer require intervention/image

Publish Assets

# Publish configuration
php artisan vendor:publish --provider="SubhashLadumor1\\DataTablePro\\Providers\\DataTableServiceProvider" --tag="datatable-config"

# Publish views
php artisan vendor:publish --provider="SubhashLadumor1\\DataTablePro\\Providers\\DataTableServiceProvider" --tag="datatable-views"

# Publish assets (after building - see above)
php artisan vendor:publish --provider="SubhashLadumor1\\DataTablePro\\Providers\\DataTableServiceProvider" --tag="datatable-assets"

# Run migrations for table presets
php artisan migrate

Build Frontend Assets

npm install
npm run build

Quick Start

1. Create a Controller

use SubhashLadumor1\DataTablePro\DataTable\Builder;
use SubhashLadumor1\DataTablePro\DataTable\Column;
use App\Models\User;

class UserController extends Controller
{
    public function index()
    {
        return view('users.index');
    }

    public function datatable(Request $request)
    {
        return Builder::make()
            ->eloquent(User::query())
            ->columns([
                Column::make('id', 'ID')->orderable(),
                Column::make('name', 'Name')->searchable()->orderable(),
                Column::make('email', 'Email')->searchable(),
                Column::make('created_at', 'Created')->orderable()
                    ->format(fn($value) => $value->format('Y-m-d')),
            ])
            ->with(['posts', 'profile'])
            ->pageLength(25)
            ->responsive()
            ->exportable()
            ->toResponse($request);
    }

    public function export(Request $request)
    {
        return Builder::make()
            ->eloquent(User::query())
            ->columns([
                Column::make('name', 'Name')->exportable(),
                Column::make('email', 'Email')->exportable(),
            ])
            ->exportable()
            ->toExport($request->get('format', 'csv'), $request);
    }
}

2. Add Routes

Route::get('/users', [UserController::class, 'index']);
Route::post('/users/datatable', [UserController::class, 'datatable']);
Route::post('/users/export', [UserController::class, 'export']);

3. Create Blade View

@extends('layouts.app')

@section('content')
    <x-dtable-table
        id="users-table"
        :ajax="route('users.datatable')"
        :columns="[
            ['key' => 'id', 'label' => 'ID', 'orderable' => true],
            ['key' => 'name', 'label' => 'Name', 'searchable' => true, 'orderable' => true],
            ['key' => 'email', 'label' => 'Email', 'searchable' => true],
            ['key' => 'created_at', 'label' => 'Created', 'orderable' => true],
        ]"
        :page-length="25"
        :responsive="true"
        :export-url="route('users.export')"
    />
@endsection

Advanced Usage

Custom Renderers

Server-side rendering:

Column::make('status', 'Status')
    ->render(function ($value, $row) {
        return "<span class='badge badge-{$value}'>" . ucfirst($value) . "</span>";
    })
    ->raw(); // Allow HTML

Client-side rendering:

// In your controller
Column::make('avatar', 'Avatar')
    ->render('avatar') // Use built-in avatar renderer
    ->attributes(['imageKey' => 'avatar_url', 'size' => 40]);

Column::make('price', 'Price')
    ->render('currency')
    ->attributes(['currency' => 'USD', 'symbol' => '$']);

Filters

use SubhashLadumor1\DataTablePro\DataTable\Filter;

Builder::make()
    ->eloquent(User::query())
    ->filters([
        Filter::text('name', 'Search Name'),
        Filter::select('status', 'Status', [
            'active' => 'Active',
            'inactive' => 'Inactive'
        ]),
        Filter::dateRange('created_at', 'Registration Date'),
        Filter::numericRange('age', 'Age'),
        
        // Custom filter with callback
        Filter::make('custom', 'select', 'Department')
            ->options(['IT' => 'IT', 'HR' => 'HR'])
            ->callback(function ($query, $value) {
                $query->whereHas('department', fn($q) => $q->where('name', $value));
            }),
    ]);

Relationship Columns

Builder::make()
    ->eloquent(Post::query())
    ->columns([
        Column::make('title', 'Title'),
        Column::make('name', 'Author')
            ->relationship('user') // belongsTo relationship
            ->searchable()
            ->orderable(),
    ])
    ->with(['user']); // Eager load to avoid N+1

Export Configuration

// Simple export
Builder::make()
    ->eloquent(User::query())
    ->columns([
        Column::make('name', 'Name')->exportable(),
        Column::make('email', 'Email')->exportable(),
        Column::make('password', 'Password')->exportable(false), // Exclude from export
    ])
    ->exportable()
    ->toExport('xlsx', $request);

For large datasets, queued exports are automatically triggered and a signed download URL is returned.

Virtual Scrolling

Builder::make()
    ->eloquent(User::query())
    ->columns([...])
    ->virtualScroll()
    ->pageLength(100);

Realtime Updates

Builder::make()
    ->eloquent(User::query())
    ->columns([...])
    ->realtime(); // Poll every 5 seconds (default)

Verification Checklist

To verify the package locally:

# 1. Install dependencies
composer install
npm install

# 2. Build assets
npm run build

# 3. Publish package resources
php artisan vendor:publish --provider="SubhashLadumor1\DataTablePro\Providers\DataTableServiceProvider" --tag="datatable-views"
php artisan vendor:publish --provider="SubhashLadumor1\DataTablePro\Providers\DataTableServiceProvider" --tag="datatable-assets"

# 4. Run migrations
php artisan migrate

# 5. Run tests
composer test

# 6. Run static analysis
composer static

# 7. Check code style
composer cs-check

Documentation

Usage Guide - Comprehensive usage examples
API Reference - Complete API documentation
Examples - Real-world examples
Implementation Details - Design rationale and trade-offs
Upgrade Guide - Migration guide between versions

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Security

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

subhashladumor1 / laravel-datatablepro

Maintainers

Details