Server-side data with Laravel

This tutorial shows how to connect Handsontable’s dataProvider plugin to a Laravel backend. You will build a product inventory grid that loads data from a REST API with server-side pagination, sorting, and filtering, and that persists row create, update, and delete operations to a Laravel database.

View full example on GitHub

Difficulty: Intermediate
Time: ~30 minutes
Stack: Laravel 11 (PHP 8.2+), Eloquent ORM, Handsontable dataProvider

What You’ll Build

A product inventory data grid that:

Fetches paginated rows from GET /api/products on every page change
Sorts and filters rows on the server — the browser never loads the full dataset
Creates, updates, and deletes rows via POST, PATCH, and DELETE endpoints
Sends CSRF tokens for Blade-rendered pages or uses Sanctum for SPA auth
Shows a loading overlay while data loads and an error toast when a request fails

Before you begin

Docker and Docker Compose installed
Node.js 18 or later and npm 9 or later installed

No local PHP or Composer installation is required — the Laravel backend and MySQL 8 database run inside Docker.

Scaffold the backend

Run these Artisan commands in your Laravel project root:
Terminal window
```
1
php artisan make:model Product --migration
2
php artisan make:controller ProductController --model=Product
3
php artisan make:seeder ProductSeeder
```
What’s happening:
- make:model Product --migration creates app/Models/Product.php and a timestamped migration file in database/migrations/.
- make:controller ProductController --model=Product creates ProductController.php pre-bound to the Product model.
- make:seeder ProductSeeder creates database/seeders/ProductSeeder.php for sample data.

Define the migration

Replace the generated migration’s up() method with the products schema:

1
<?php
2

3
use Illuminate\Database\Migrations\Migration;
4
use Illuminate\Database\Schema\Blueprint;
5
use Illuminate\Support\Facades\Schema;
6

7
// Generated by: php artisan make:migration create_products_table
8
return new class extends Migration
9
{
10
    public function up(): void
11
    {
12
        Schema::create('products', function (Blueprint $table) {
13
            $table->id();                               // Auto-increment primary key
14
            $table->string('name');                     // Product name (filterable via LIKE)
15
            $table->string('sku')->unique();            // Stock-keeping unit (read-only in UI)
16
            $table->string('category');                 // Dropdown value (filterable via =)
17
            $table->decimal('price', 10, 2);           // Numeric — supports gt/lt/between
18
            $table->unsignedInteger('stock');           // Numeric — supports gt/lt/between
19
            $table->unsignedInteger('sort_order')->default(0); // Preserves insertion order when no sort is applied
20
            $table->timestamps();
21
        });
22
    }
23

24
    public function down(): void
25
    {
26
        Schema::dropIfExists('products');
27
    }
28
};

What’s happening:

id() creates an auto-increment primary key. This is the value Handsontable uses as rowId.
string('sku')->unique() is a server-generated field, so the grid marks it readOnly: true.
decimal('price', 10, 2) stores two decimal places, matching the numeric cell type in the frontend column definition.
unsignedInteger('stock') enforces a non-negative integer at the database level.

Run the migration:

1
php artisan migrate

Create the Eloquent model

Open app/Models/Product.php and set $fillable and $casts:

1
<?php
2

3
namespace App\Models;
4

5
use Illuminate\Database\Eloquent\Factories\HasFactory;
6
use Illuminate\Database\Eloquent\Model;
7

8
class Product extends Model
9
{
10
    use HasFactory;
11

12
    // Mass-assignable columns. 'id' is intentionally excluded (auto-increment).
13
    protected $fillable = ['name', 'sku', 'category', 'price', 'stock', 'sort_order'];
14

15
    // Cast numeric columns so Laravel returns real numbers, not strings.
16
    protected $casts = [
17
        'price' => 'float',
18
        'stock' => 'integer',
19
    ];
20
}

What’s happening:

$fillable lists the columns that Product::create() and update() may write to, protecting the id from mass-assignment.
$casts maps price to float and stock to integer. Without this, Eloquent returns all values as strings and Handsontable’s numeric cell type receives "1299.99" instead of 1299.99.

Seed the database

Open database/seeders/ProductSeeder.php and add at least 50 rows so that pagination spans multiple pages:

1
<?php
2

3
namespace Database\Seeders;
4

5
use App\Models\Product;
6
use Illuminate\Database\Seeder;
7

8
// Generated by: php artisan make:seeder ProductSeeder
9
// Run with:     php artisan db:seed --class=ProductSeeder
10
class ProductSeeder extends Seeder
11
{
12
    public function run(): void
13
    {
14
        $categories = ['Electronics', 'Accessories', 'Storage', 'Networking', 'Peripherals'];
15

16
        $products = [
17
            ['name' => 'Laptop Pro 15',              'sku' => 'LAP-001', 'category' => 'Electronics',  'price' => 1299.99, 'stock' => 42],
18
            ['name' => 'Wireless Mouse',             'sku' => 'MOU-002', 'category' => 'Accessories',  'price' => 29.99,   'stock' => 315],
19
            ['name' => 'USB-C Hub 7-in-1',           'sku' => 'HUB-003', 'category' => 'Accessories',  'price' => 49.99,   'stock' => 178],
20
            ['name' => 'NVMe SSD 1 TB',              'sku' => 'SSD-004', 'category' => 'Storage',      'price' => 109.99,  'stock' => 260],
21
            ['name' => 'Mechanical Keyboard',        'sku' => 'KEY-005', 'category' => 'Peripherals',  'price' => 139.99,  'stock' => 95],
22
            ['name' => 'Gigabit Switch 8-Port',      'sku' => 'SW8-006', 'category' => 'Networking',   'price' => 59.99,   'stock' => 74],
23
            ['name' => 'Portable Monitor 15"',       'sku' => 'MON-007', 'category' => 'Electronics',  'price' => 249.99,  'stock' => 38],
24
            ['name' => 'Webcam 4K',                  'sku' => 'CAM-008', 'category' => 'Peripherals',  'price' => 89.99,   'stock' => 112],
25
            ['name' => 'External HDD 2 TB',          'sku' => 'HDD-009', 'category' => 'Storage',      'price' => 74.99,   'stock' => 193],
26
            ['name' => 'Wi-Fi 6 Router',             'sku' => 'RTR-010', 'category' => 'Networking',   'price' => 179.99,  'stock' => 55],
27
            ['name' => 'Noise-Cancelling Headphones','sku' => 'HP-011',  'category' => 'Accessories',  'price' => 199.99,  'stock' => 67],
28
            ['name' => 'Thunderbolt Dock',           'sku' => 'DOC-012', 'category' => 'Accessories',  'price' => 219.99,  'stock' => 31],
29
            ['name' => 'Laptop Stand',               'sku' => 'STD-013', 'category' => 'Accessories',  'price' => 39.99,   'stock' => 220],
30
            ['name' => 'Gaming Controller',          'sku' => 'CTR-014', 'category' => 'Peripherals',  'price' => 69.99,   'stock' => 148],
31
            ['name' => 'HDMI Cable 2 m',             'sku' => 'CBL-015', 'category' => 'Accessories',  'price' => 12.99,   'stock' => 500],
32
            ['name' => 'MicroSD 256 GB',             'sku' => 'MSD-016', 'category' => 'Storage',      'price' => 29.99,   'stock' => 387],
33
            ['name' => 'PoE Switch 24-Port',         'sku' => 'POE-017', 'category' => 'Networking',   'price' => 299.99,  'stock' => 18],
34
            ['name' => 'Smart Plug 4-Pack',          'sku' => 'PLG-018', 'category' => 'Electronics',  'price' => 34.99,   'stock' => 142],
35
            ['name' => 'USB Microphone',             'sku' => 'MIC-019', 'category' => 'Peripherals',  'price' => 79.99,   'stock' => 89],
36
            ['name' => 'Ergonomic Chair Mat',        'sku' => 'MAT-020', 'category' => 'Accessories',  'price' => 44.99,   'stock' => 61],
37
            ['name' => 'Tablet 10" Wi-Fi',           'sku' => 'TAB-021', 'category' => 'Electronics',  'price' => 349.99,  'stock' => 27],
38
            ['name' => 'Power Bank 20000 mAh',       'sku' => 'PBK-022', 'category' => 'Accessories',  'price' => 49.99,   'stock' => 203],
39
            ['name' => 'OLED Monitor 27"',           'sku' => 'MON-023', 'category' => 'Electronics',  'price' => 699.99,  'stock' => 14],
40
            ['name' => 'USB-A 4-Port Hub',           'sku' => 'HUB-024', 'category' => 'Accessories',  'price' => 19.99,   'stock' => 341],
41
            ['name' => 'SSD Enclosure',              'sku' => 'ENC-025', 'category' => 'Storage',      'price' => 24.99,   'stock' => 115],
42
            ['name' => 'Network Cable Cat 6 10 m',  'sku' => 'CBL-026', 'category' => 'Networking',   'price' => 9.99,    'stock' => 620],
43
            ['name' => 'Drawing Tablet',             'sku' => 'TAB-027', 'category' => 'Peripherals',  'price' => 189.99,  'stock' => 43],
44
            ['name' => 'Smart Switch',               'sku' => 'SW2-028', 'category' => 'Electronics',  'price' => 44.99,   'stock' => 78],
45
            ['name' => 'Desk Lamp LED',              'sku' => 'LMP-029', 'category' => 'Accessories',  'price' => 34.99,   'stock' => 99],
46
            ['name' => 'RAID Controller',            'sku' => 'RAD-030', 'category' => 'Storage',      'price' => 149.99,  'stock' => 22],
47
            ['name' => 'VPN Router',                 'sku' => 'VPN-031', 'category' => 'Networking',   'price' => 219.99,  'stock' => 30],
48
            ['name' => 'Foot Pedal USB',             'sku' => 'FTP-032', 'category' => 'Peripherals',  'price' => 59.99,   'stock' => 47],
49
            ['name' => 'Mini PC',                    'sku' => 'MPC-033', 'category' => 'Electronics',  'price' => 449.99,  'stock' => 19],
50
            ['name' => 'Cable Management Kit',       'sku' => 'KIT-034', 'category' => 'Accessories',  'price' => 14.99,   'stock' => 265],
51
            ['name' => 'M.2 SSD 500 GB',             'sku' => 'SSD-035', 'category' => 'Storage',      'price' => 59.99,   'stock' => 183],
52
            ['name' => 'Managed Switch 48-Port',     'sku' => 'MSW-036', 'category' => 'Networking',   'price' => 599.99,  'stock' => 8],
53
            ['name' => 'RGB LED Strip',              'sku' => 'LED-037', 'category' => 'Electronics',  'price' => 24.99,   'stock' => 320],
54
            ['name' => 'Monitor Arm Single',         'sku' => 'ARM-038', 'category' => 'Accessories',  'price' => 54.99,   'stock' => 73],
55
            ['name' => 'Barcode Scanner USB',        'sku' => 'SCN-039', 'category' => 'Peripherals',  'price' => 119.99,  'stock' => 56],
56
            ['name' => 'NAS Enclosure 4-Bay',        'sku' => 'NAS-040', 'category' => 'Storage',      'price' => 329.99,  'stock' => 11],
57
            ['name' => 'Fiber Converter',            'sku' => 'FBC-041', 'category' => 'Networking',   'price' => 89.99,   'stock' => 25],
58
            ['name' => 'Wireless Presenter',         'sku' => 'PRE-042', 'category' => 'Peripherals',  'price' => 39.99,   'stock' => 67],
59
            ['name' => 'UPS 1500 VA',                'sku' => 'UPS-043', 'category' => 'Electronics',  'price' => 259.99,  'stock' => 16],
60
            ['name' => 'Zip Ties 100-Pack',          'sku' => 'ZTP-044', 'category' => 'Accessories',  'price' => 7.99,    'stock' => 950],
61
            ['name' => 'HDD 4 TB Desktop',          'sku' => 'HDD-045', 'category' => 'Storage',      'price' => 89.99,   'stock' => 94],
62
            ['name' => 'Patch Panel 24-Port',        'sku' => 'PNL-046', 'category' => 'Networking',   'price' => 49.99,   'stock' => 35],
63
            ['name' => 'Numeric Keypad',             'sku' => 'KPD-047', 'category' => 'Peripherals',  'price' => 29.99,   'stock' => 130],
64
            ['name' => 'Server Rack 12U',            'sku' => 'RCK-048', 'category' => 'Networking',   'price' => 349.99,  'stock' => 7],
65
            ['name' => 'Thermal Paste 5 g',         'sku' => 'TPT-049', 'category' => 'Accessories',  'price' => 8.99,    'stock' => 480],
66
            ['name' => 'Flash Drive 128 GB',         'sku' => 'USB-050', 'category' => 'Storage',      'price' => 17.99,   'stock' => 740],
67
            ['name' => 'HDMI Splitter 4-Port',       'sku' => 'SPL-051', 'category' => 'Electronics',  'price' => 29.99,   'stock' => 88],
68
            ['name' => 'Smart Card Reader',          'sku' => 'SCR-052', 'category' => 'Peripherals',  'price' => 19.99,   'stock' => 210],
69
        ];
70

71
        foreach ($products as $i => $data) {
72
            Product::create(array_merge($data, ['sort_order' => $i + 1]));
73
        }
74
    }
75
}

What’s happening:

Product::create($data) inserts each row through Eloquent so the $fillable guard and timestamps apply.
The 52 rows create six pages at the default pageSize: 10, making pagination controls visible from the first load.

Run the seeder:

1
php artisan db:seed --class=ProductSeeder

Build the ProductController

ProductController handles all four HTTP verbs. Each method maps to one Handsontable dataProvider callback:

1
<?php
2

3
namespace App\Http\Controllers;
4

5
use App\Models\Product;
6
use Illuminate\Http\JsonResponse;
7
use Illuminate\Http\Request;
8
use Illuminate\Support\Facades\DB;
9

10
// Generated by: php artisan make:controller ProductController --model=Product
11
class ProductController extends Controller
12
{
13
    private const ALLOWED_COLUMNS = ['name', 'sku', 'category', 'price', 'stock'];
14

15
    // GET /api/products
16
    // Query string — what Handsontable sends via buildUrl():
17
    //   page, pageSize, sort[prop], sort[order],
18
    //   filters[0][prop], filters[0][condition], filters[0][value], filters[0][value2]
19
    public function index(Request $request): JsonResponse
20
    {
21
        $page     = (int) $request->input('page', 1);
22
        $pageSize = (int) $request->input('pageSize', 10);
23
        $sort     = $request->input('sort');      // array ['prop' => ..., 'order' => ...]
24
        $filters  = $request->input('filters');   // array of filter objects
25

26
        $query = Product::query();
27

28
        // --- Filtering ---------------------------------------------------------
29
        // Handsontable condition names map directly to SQL clauses.
30
        // Add more cases here as you enable additional condition types in the UI.
31
        if (is_array($filters)) {
32
            foreach ($filters as $filter) {
33
                $prop      = $filter['prop']      ?? null;
34
                $condition = $filter['condition'] ?? null;
35
                $value     = $filter['value']     ?? null;
36
                $value2    = $filter['value2']    ?? null;
37

38
                // Validate $prop against an allowlist of filterable columns before
39
                // interpolating it into any raw SQL to prevent SQL injection.
40
                if (!$prop || !$condition || !in_array($prop, self::ALLOWED_COLUMNS, true)) {
41
                    continue;
42
                }
43

44
                // Text conditions — use LOWER() for case-insensitive matching.
45
                // escapeLike() escapes LIKE metacharacters in user input.
46
                switch ($condition) {
47
                    case 'contains':
48
                        $safe = $this->escapeLike(strtolower((string)$value));
49
                        $query->whereRaw("LOWER({$prop}) LIKE ?", ['%' . $safe . '%']);
50
                        break;
51
                    case 'not_contains':
52
                        $safe = $this->escapeLike(strtolower((string)$value));
53
                        $query->whereRaw("LOWER({$prop}) NOT LIKE ?", ['%' . $safe . '%']);
54
                        break;
55
                    case 'begins_with':
56
                        $safe = $this->escapeLike(strtolower((string)$value));
57
                        $query->whereRaw("LOWER({$prop}) LIKE ?", [$safe . '%']);
58
                        break;
59
                    case 'ends_with':
60
                        $safe = $this->escapeLike(strtolower((string)$value));
61
                        $query->whereRaw("LOWER({$prop}) LIKE ?", ['%' . $safe]);
62
                        break;
63
                    // Numeric / exact conditions
64
                    case 'eq':    $query->where($prop, '=', $value);  break;
65
                    case 'neq':   $query->where($prop, '!=', $value); break;
66
                    case 'gt':    $query->where($prop, '>', $value);  break;
67
                    case 'gte':   $query->where($prop, '>=', $value); break;
68
                    case 'lt':    $query->where($prop, '<', $value);  break;
69
                    case 'lte':   $query->where($prop, '<=', $value); break;
70
                    case 'between':
71
                        $query->whereBetween($prop, [$value, $value2]);
72
                        break;
73
                    case 'not_between':
74
                        $query->whereNotBetween($prop, [$value, $value2]);
75
                        break;
76
                    case 'empty':
77
                        $isString = in_array($prop, ['name', 'sku', 'category'], true);
78
                        $query->where(function ($q) use ($prop, $isString) {
79
                            $q->whereNull($prop);
80
                            if ($isString) {
81
                                $q->orWhere($prop, '');
82
                            }
83
                        });
84
                        break;
85
                    case 'not_empty':
86
                        $isString = in_array($prop, ['name', 'sku', 'category'], true);
87
                        $query->where(function ($q) use ($prop, $isString) {
88
                            $q->whereNotNull($prop);
89
                            if ($isString) {
90
                                $q->where($prop, '!=', '');
91
                            }
92
                        });
93
                        break;
94
                }
95
            }
96
        }
97

98
        // --- Sorting -----------------------------------------------------------
99
        // Handsontable sends sort[prop] and sort[order] ('asc'|'desc').
100
        // Use manual skip/take rather than Laravel's paginate() because
101
        // Handsontable sends 1-based page + pageSize directly.
102
        if (is_array($sort) && isset($sort['prop'], $sort['order'])
103
            && in_array($sort['prop'], self::ALLOWED_COLUMNS, true)) {
104
            $direction = in_array(strtolower($sort['order']), ['asc', 'desc'])
105
                ? strtolower($sort['order'])
106
                : 'asc';
107
            $query->orderBy($sort['prop'], $direction);
108
        } else {
109
            // Default: preserve insertion order
110
            $query->orderBy('sort_order');
111
        }
112

113
        // --- Pagination --------------------------------------------------------
114
        // Count filtered rows first so Handsontable knows the total row count.
115
        $total = $query->count();
116

117
        $data = $query
118
            ->skip(($page - 1) * $pageSize)
119
            ->take($pageSize)
120
            ->get();
121

122
        // Return the shape that fetchRows expects: { data: [...], total: n }
123
        return response()->json(['data' => $data, 'total' => $total]);
124
    }
125

126
    // POST /api/products
127
    // Body (JSON): { position, referenceRowId, rowsAmount }
128
    // Matches the onRowsCreate payload shape. Returns the created rows so the
129
    // frontend can show a success notification with the generated SKU.
130
    public function store(Request $request): JsonResponse
131
    {
132
        $rowsAmount     = max(1, (int) $request->input('rowsAmount', 1));
133
        $position       = $request->input('position', 'below');
134
        $referenceRowId = $request->input('referenceRowId');
135

136
        $created = [];
137

138
        DB::transaction(function () use ($rowsAmount, $position, $referenceRowId, &$created) {
139
            $insertAt = $this->resolveInsertOrder($referenceRowId, $position, $rowsAmount);
140

141
            for ($i = 0; $i < $rowsAmount; $i++) {
142
                $created[] = Product::create([
143
                    'name'       => '',
144
                    'sku'        => 'NEW-' . strtoupper(bin2hex(random_bytes(3))),
145
                    'category'   => 'Electronics',
146
                    'price'      => 0,
147
                    'stock'      => 0,
148
                    'sort_order' => $insertAt + $i,
149
                ]);
150
            }
151
        });
152

153
        return response()->json($created, 201);
154
    }
155

156
    // PATCH /api/products
157
    // Body (JSON): [{ id, changes: { name?, price?, ... }, rowData? }, ...]
158
    // Matches the onRowsUpdate payload shape.
159
    public function batchUpdate(Request $request): JsonResponse
160
    {
161
        $rows = $request->json()->all();
162

163
        foreach ($rows as $row) {
164
            $product = Product::find($row['id'] ?? null);
165
            if ($product) {
166
                // Only update the changed columns — never overwrite the primary key or sort order.
167
                $changes = $row['changes'] ?? [];
168
                unset($changes['id'], $changes['sort_order']);
169
                $product->update($changes);
170
            }
171
        }
172

173
        return response()->json(null, 200);
174
    }
175

176
    // DELETE /api/products
177
    // Body (JSON): [1, 4, 7]  — array of product IDs
178
    // Matches the onRowsRemove payload shape.
179
    public function batchDestroy(Request $request): JsonResponse
180
    {
181
        $ids = $request->json()->all();
182

183
        Product::whereIn('id', $ids)->delete();
184

185
        return response()->json(null, 204);
186
    }
187

188
    // Determines the sort_order for the new row(s) and shifts existing rows to make room.
189
    private function resolveInsertOrder(?int $referenceRowId, string $position, int $rowsAmount): int
190
    {
191
        if ($referenceRowId !== null) {
192
            $ref = Product::find($referenceRowId);
193
            if ($ref) {
194
                $insertAt = $position === 'above'
195
                    ? $ref->sort_order
196
                    : $ref->sort_order + 1;
197

198
                Product::where('sort_order', '>=', $insertAt)
199
                    ->increment('sort_order', $rowsAmount);
200

201
                return $insertAt;
202
            }
203
        }
204

205
        // No reference row — append after the current maximum
206
        return (int) (Product::max('sort_order') ?? 0) + 1;
207
    }
208

209
    // Escapes LIKE metacharacters so literal % and _ in user input don't act as
210
    // wildcards. MySQL's default escape char is \, so we prefix \, %, and _ with \.
211
    private function escapeLike(string $value): string
212
    {
213
        return addcslashes($value, '\\%_');
214
    }
215
}

What’s happening:

`index()` — paginate, sort, and filter

Handsontable sends query parameters through the buildUrl() frontend helper:

Query parameter	Example value	PHP access
`page`, `pageSize`	`1`, `10`	`$request->input('page')`
`sort[prop]`, `sort[order]`	`'name'`, `'asc'`	`$request->input('sort')`
`filters[0][prop]`, `filters[0][condition]`, `filters[0][value]`	`'price'`, `'gt'`, `'100'`	`$request->input('filters')`

The filter loop maps Handsontable condition names to SQL clauses. Text conditions use LOWER() for case-insensitive matching:

Handsontable condition	SQL equivalent
`contains`	`LIKE '%value%'`
`begins_with`	`LIKE 'value%'`
`gt`	`> value`
`between`	`BETWEEN value AND value2`
`empty`	`IS NULL OR = ''`

Both $prop values (for filters and for sort) are validated against an allowlist of column names before being used in any query, preventing SQL injection through unsanitized user input.

Why skip()/take() instead of paginate()?

Laravel’s paginate(n) manages its own ?page= parameter and returns a LengthAwarePaginator JSON shape. Handsontable already sends page and pageSize directly, so manual skip(($page - 1) * $pageSize)->take($pageSize) returns the { data, total } shape that fetchRows expects without any adapter code.

`store()` — create rows

When the user inserts rows from the context menu, onRowsCreate calls POST /api/products with:

1
{ "position": "above", "referenceRowId": 5, "rowsAmount": 1 }

store() reads position, referenceRowId, and rowsAmount. It runs a DB::transaction() that calls resolveInsertOrder() to find the correct sort_order value, shifts existing rows to make room, and inserts the new blank rows. It returns the created rows as JSON with HTTP 201 so the frontend can show a success notification with the generated SKU.

`batchUpdate()` — update changed cells

After a cell edit, onRowsUpdate calls PATCH /api/products with:

1
[{ "id": 4, "changes": { "price": 149.99 }, "rowData": { "..." } }]

batchUpdate() finds each product by id and calls update() with only the changes object, so unchanged fields are not overwritten.

`batchDestroy()` — delete rows

onRowsRemove calls DELETE /api/products with a plain array of row IDs:

1
[4, 7, 12]

batchDestroy() deletes them in one whereIn()->delete() query and returns HTTP 204.

Register API routes

Open routes/api.php and add the four product routes:

1
<?php
2

3
use App\Http\Controllers\ProductController;
4
use Illuminate\Support\Facades\Route;
5

6
// Add these routes to routes/api.php.
7
// All four verbs share the same base URL. Laravel matches them by HTTP method.
8

9
Route::get('/products',    [ProductController::class, 'index']);          // Paginate, sort, filter
10
Route::post('/products',   [ProductController::class, 'store']);          // Insert new blank rows
11
Route::patch('/products',  [ProductController::class, 'batchUpdate']);    // Batch-update changed cells
12
Route::delete('/products', [ProductController::class, 'batchDestroy']);   // Delete rows by ID
13

14
// If you use Sanctum for SPA authentication, protect these routes by wrapping
15
// them in the 'auth:sanctum' middleware:
16
//
17
// Route::middleware('auth:sanctum')->group(function () {
18
//     Route::get('/products',    [ProductController::class, 'index']);
19
//     Route::post('/products',   [ProductController::class, 'store']);
20
//     Route::patch('/products',  [ProductController::class, 'batchUpdate']);
21
//     Route::delete('/products', [ProductController::class, 'batchDestroy']);
22
// });

What’s happening:

All four routes share the same /api/products path. Laravel matches them by HTTP method.
The Sanctum middleware group is shown commented out. Uncomment it when you add authentication to your API.

Verify the routes are registered:

1
php artisan route:list --path=api/products

Set up the Vite dev server

Create a vite.config.js at the root of your frontend project and configure a proxy so requests go to Vite (:5173) and are forwarded to Laravel without triggering CORS:
```
1
import { defineConfig } from 'vite';
2

3
export default defineConfig({
4
  server: {
5
    port: 5173,
6
    proxy: {
7
      '/api': {
8
        target: 'http://localhost:8000',
9
        changeOrigin: true,
10
      },
11
    },
12
  },
13
});
```
What’s happening:
- The Vite dev server forwards every /api/* request to the Laravel server running on port 8000. Because both the HTML page and the API requests share the same origin (localhost:5173), the browser never sees a cross-origin request — no CORS headers are needed on the backend.
- In production, deploy the frontend and backend behind the same reverse proxy (nginx or Apache), or configure CORS headers in config/cors.php for your production origin.

Wire up Handsontable

Start the backend and the Vite dev server with bash setup.sh (or make setup), then open http://localhost:5173. The Laravel API runs on http://localhost:8000 inside Docker; Vite proxies all /api/* requests to it. The complete frontend code is in the files below.

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3

4
registerAllModules();
5

6
// Serializes fetchRows query parameters into a URL query string that Laravel
7
// reads via request()->input().
8
//
9
// Handsontable sends:
10
//   sort:    { prop: 'name', order: 'asc' }  or  null
11
//   filters: [{ prop: 'price', conditions: [{ name: 'gt', args: [100] }] }]  or  null
12
//
13
// Laravel reads:
14
//   sort[prop], sort[order]
15
//   filters[0][prop], filters[0][condition], filters[0][value], filters[0][value2]
16
function buildUrl(base, { page, pageSize, sort, filters }) {
17
  const params = new URLSearchParams({
18
    page: String(page),
19
    pageSize: String(pageSize),
20
  });
21

22
  if (sort) {
23
    params.set('sort[prop]', sort.prop);
24
    params.set('sort[order]', sort.order);
25
  }
26

27
  if (filters?.length) {
28
    let idx = 0;
29
    filters.forEach(({ prop, conditions }) => {
30
      (conditions || []).forEach(({ name, args }) => {
31
        if (!name) return;
32
        params.set(`filters[${idx}][prop]`, prop);
33
        params.set(`filters[${idx}][condition]`, name);
34
        const a = args ?? [];
35
        // Single-value conditions: contains, gt, eq, begins_with …
36
        if (a[0] != null) params.set(`filters[${idx}][value]`, String(a[0]));
37
        // Range conditions: between, not_between
38
        if (a[1] != null) params.set(`filters[${idx}][value2]`, String(a[1]));
39
        idx++;
40
      });
41
    });
42
  }
43

44
  return `${base}?${params}`;
45
}
46

47
// For Blade-rendered pages, inject via <meta name="csrf-token" content="{{ csrf_token() }}">.
48
// For this standalone SPA the API routes are stateless so the header is a no-op,
49
// but it's kept here so the code mirrors the recipe exactly.
50
function csrfToken() {
51
  return document.querySelector('meta[name="csrf-token"]')?.content ?? '';
52
}
53

54
const container = document.querySelector('#example1');
55

56
let removeConfirmed = false;
57

58
// eslint-disable-next-line no-unused-vars
59
const hot = new Handsontable(container, {
60
  dataProvider: {
61
    // rowId must match the primary key field in your Laravel model.
62
    // Handsontable uses this value in every update and remove callback.
63
    rowId: 'id',
64

65
    // fetchRows is called on every page change, sort, and filter.
66
    // queryParameters: { page, pageSize, sort, filters }
67
    // signal: AbortSignal — pass it to fetch() so stale requests cancel
68
    // when the user sorts, filters, or changes pages quickly.
69
    fetchRows: async ({ page, pageSize, sort, filters }, { signal }) => {
70
      const url = buildUrl('/api/products', { page, pageSize, sort, filters });
71
      const res = await fetch(url, { signal });
72

73
      if (!res.ok) throw new Error(`HTTP ${res.status}`);
74

75
      // Laravel returns: { data: [...], total: n }
76
      const json = await res.json();
77

78
      return { rows: json.data, totalRows: json.total };
79
    },
80

81
    // onRowsCreate fires when the user inserts rows from the context menu.
82
    // payload: { position: 'above'|'below', referenceRowId, rowsAmount }
83
    onRowsCreate: async (payload) => {
84
      const res = await fetch('/api/products', {
85
        method: 'POST',
86
        headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': csrfToken() },
87
        body: JSON.stringify(payload),
88
      });
89
      if (!res.ok) throw new Error(`HTTP ${res.status}`);
90
      const data = await res.json();
91
      const row = data[0];
92
      hot.getPlugin('notification').showMessage({
93
        variant: 'success',
94
        title: 'Row added',
95
        message: `Created: ${row.sku} (id: ${row.id})`,
96
        duration: 3000,
97
      });
98
      return data;
99
    },
100

101
    // onRowsUpdate fires after a cell edit, paste, or autofill batch.
102
    // rows is an array of { id, changes, rowData } objects.
103
    // Changes appear in the grid immediately (optimistic update) and roll back
104
    // if this callback throws or rejects.
105
    onRowsUpdate: async (rows) => {
106
      const res = await fetch('/api/products', {
107
        method: 'PATCH',
108
        headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': csrfToken() },
109
        body: JSON.stringify(rows),
110
      });
111
      if (!res.ok) throw new Error(`HTTP ${res.status}`);
112
    },
113

114
    // onRowsRemove fires after the user confirms deletion.
115
    // rowIds is an array of stable row IDs (values of the rowId field).
116
    onRowsRemove: async (rowIds) => {
117
      const res = await fetch('/api/products', {
118
        method: 'DELETE',
119
        headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': csrfToken() },
120
        body: JSON.stringify(rowIds),
121
      });
122
      if (!res.ok) throw new Error(`HTTP ${res.status}`);
123
      hot.getPlugin('notification').showMessage({
124
        variant: 'success',
125
        title: 'Rows deleted',
126
        message: `Deleted ${rowIds.length} row${rowIds.length !== 1 ? 's' : ''}`,
127
        duration: 3000,
128
      });
129
    },
130
  },
131

132
  // beforeRowsMutation is sync (checks for a strict `=== false` return), so
133
  // we cannot await an async prompt inline. Instead: cancel the original
134
  // attempt, show a notification with Delete/Cancel actions, and on Delete
135
  // re-issue the remove via the DataProvider API. The flag lets the second
136
  // pass through without re-prompting.
137
  beforeRowsMutation(operation, payload) {
138
    if (operation === 'remove' && !removeConfirmed) {
139
      const count = payload.rowsRemove.length;
140
      const notification = hot.getPlugin('notification');
141
      const id = notification.showMessage({
142
        variant: 'warning',
143
        title: 'Delete rows',
144
        message: `Delete ${count} row${count !== 1 ? 's' : ''}? This cannot be undone.`,
145
        duration: 0,
146
        actions: [
147
          {
148
            label: 'Delete',
149
            type: 'primary',
150
            callback: () => {
151
              notification.hide(id);
152
              removeConfirmed = true;
153
              hot.getPlugin('dataProvider').removeRows(payload.rowsRemove).finally(() => {
154
                removeConfirmed = false;
155
              });
156
            },
157
          },
158
          {
159
            label: 'Cancel',
160
            type: 'secondary',
161
            callback: () => notification.hide(id),
162
          },
163
        ],
164
      });
165
      return false;
166
    }
167
  },
168

169
  // pagination: pageSize controls how many rows fetchRows requests per call.
170
  pagination: { pageSize: 10 },
171

172
  // columnSorting sends { prop, order } in queryParameters.sort.
173
  // Keep multiColumnSorting off — it conflicts with dataProvider.
174
  columnSorting: true,
175

176
  // filters sends condition objects in queryParameters.filters.
177
  // The grid resets to page 1 automatically on each filter change.
178
  filters: true,
179

180
  // dropdownMenu shows the column header filter button.
181
  dropdownMenu: true,
182

183
  // contextMenu exposes "Insert row above / below" and "Remove row".
184
  contextMenu: true,
185

186
  // emptyDataState shows a loading overlay while fetchRows is in flight
187
  // and an empty-state overlay when the result set is empty.
188
  emptyDataState: true,
189

190
  // notification shows an error toast when fetchRows or any CRUD callback
191
  // rejects. Fetch failures include a Refetch button.
192
  notification: true,
193

194
  rowHeaders: true,
195
  colHeaders: ['Name', 'SKU', 'Category', 'Price', 'Stock'],
196
  columns: [
197
    { data: 'name', type: 'text' },
198
    // SKU is generated server-side, so it is read-only in the grid.
199
    { data: 'sku', type: 'text', readOnly: true },
200
    {
201
      data: 'category',
202
      type: 'dropdown',
203
      source: ['Electronics', 'Accessories', 'Storage', 'Networking', 'Peripherals'],
204
    },
205
    { data: 'price', type: 'numeric', numericFormat: { pattern: '$0,0.00' } },
206
    { data: 'stock', type: 'numeric' },
207
  ],
208
  width: '100%',
209
  height: 'auto',
210
  licenseKey: 'non-commercial-and-evaluation',
211
});
212

213
export default hot;

What’s happening:

`buildUrl` helper

buildUrl serializes the queryParameters object that fetchRows receives into a URL query string that Laravel reads with request()->input(). It converts the Handsontable filter shape — { prop, conditions: [{ name, args }] } (each filter can carry multiple conditions) — into the flat bracket-notation parameters Laravel parses automatically.

`csrfToken` helper

Laravel requires a CSRF token on POST, PATCH, and DELETE requests. For Blade-rendered pages, inject the token via <meta name="csrf-token" content="{{ csrf_token() }}"> in your layout. For a Sanctum SPA, call GET /sanctum/csrf-cookie once on startup and send the X-XSRF-TOKEN cookie value instead.

`fetchRows`

fetchRows is called on every page change, sort, and filter. Passing signal to fetch() lets the browser cancel stale in-flight requests when the user sorts or pages quickly. Throwing on a non-ok response lets notification: true display an error toast automatically.

`onRowsCreate`, `onRowsUpdate`, `onRowsRemove`

onRowsCreate must return the array of rows created by the server (including server-assigned id values). Handsontable uses the returned rows to update its internal row map so that subsequent updates and deletes reference the correct primary keys.

onRowsCreate and onRowsRemove call notification.showMessage() with a success variant to confirm the operation to the user.

Cell edits via onRowsUpdate appear in the grid immediately (optimistic update). If the server returns a non-2xx response or any callback throws, Handsontable rolls back the values and fires afterRowsMutationError.

`beforeRowsMutation`

beforeRowsMutation fires before any create, update, or remove operation. Returning false cancels the operation — onRowsRemove is not called and no rows are deleted on the server.

Because beforeRowsMutation is synchronous and checks for a strict === false return, you cannot use window.confirm() or any async dialog. Instead, use notification.showMessage() with variant: 'warning' and two action buttons. Cancel the first attempt by returning false, then on Delete re-issue the remove via hot.getPlugin('dataProvider').removeRows(rowsRemove). The removeConfirmed flag lets the second pass through without re-prompting.

`notification: true` and `emptyDataState: true`

notification: true enables the built-in error toast. When fetchRows or a mutation callback throws, Handsontable shows a translated error message. Fetch failures also add a Refetch action that retries the last request.

emptyDataState: true shows a loading overlay while fetchRows is in flight and an empty-state message when the server returns zero rows.

contextMenu: true enables the right-click context menu with “Insert row above / below” and “Remove row” items.

How It Works — Complete Flow

Initial load: fetchRows fires with { page: 1, pageSize: 10, sort: null, filters: null }. Laravel returns { data: [...10 rows...], total: 52 }. The grid renders the first page with a pagination bar.
Sort: The user clicks the Price header. fetchRows fires with sort: { prop: 'price', order: 'asc' }. Laravel applies orderBy('price', 'asc') and returns the first page sorted by price.
Filter: The user opens the Category filter and types “Electronics”. fetchRows fires with the filter condition. Laravel applies WHERE LOWER(category) LIKE '%electronics%' and returns the matching rows.
Edit: The user changes a price cell. The new value appears immediately. onRowsUpdate fires with [{ id: 4, changes: { price: 149.99 } }]. Laravel updates the row. On success, Handsontable silently refetches the current page.
Insert: The user right-clicks and selects Insert row below. onRowsCreate fires with { position: 'below', referenceRowId: 4, rowsAmount: 1 }. Laravel creates a blank row and returns it. Handsontable refetches and shows a “Row added” success notification.
Delete: The user selects two rows and chooses Remove rows. beforeRowsMutation intercepts the operation, returns false, and shows a warning notification with Delete and Cancel action buttons. On Delete, onRowsRemove fires with [4, 7]. Laravel deletes both rows and a “Rows deleted” success notification appears.
Error: The server returns 500. fetchRows throws. Handsontable shows an error toast with a Refetch button.

What you learned

How to map Handsontable’s queryParameters to Laravel request()->input() with the buildUrl() helper.
How to apply Handsontable filter condition names as Eloquent where() clauses.
Why skip()/take() is simpler than paginate() when Handsontable sends page and pageSize directly.
How to validate column names against an allowlist before using them in whereRaw() and orderBy() to prevent SQL injection.
How to send CSRF tokens for Blade-rendered pages and for SPA Sanctum apps.
How notification: true provides error toasts and a Refetch action with no extra code.
How beforeRowsMutation intercepts operations before they reach the server.

Next steps

Server-side data overview — DataProvider plugin reference
Configuration and query parameters — all fetchRows query fields
Server-side CRUD — mutation lifecycle and hooks
Fetching, hooks, and examples — error handling and loading UI
Server-side data with Spring Boot — the same Handsontable frontend wired to a Java backend
Server-side data with Symfony — the same Handsontable frontend wired to a Symfony backend

Server-side data with Laravel

What You’ll Build

Before you begin

Scaffold the backend

Define the migration

Create the Eloquent model

Seed the database

Build the ProductController

index() — paginate, sort, and filter

store() — create rows

batchUpdate() — update changed cells

batchDestroy() — delete rows

Register API routes

Set up the Vite dev server

Wire up Handsontable

buildUrl helper

csrfToken helper

fetchRows

onRowsCreate, onRowsUpdate, onRowsRemove

beforeRowsMutation

notification: true and emptyDataState: true

How It Works — Complete Flow

What you learned

Next steps

`index()` — paginate, sort, and filter

`store()` — create rows

`batchUpdate()` — update changed cells

`batchDestroy()` — delete rows

`buildUrl` helper

`csrfToken` helper

`fetchRows`

`onRowsCreate`, `onRowsUpdate`, `onRowsRemove`

`beforeRowsMutation`

`notification: true` and `emptyDataState: true`