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
/* file: app.component.ts */
2
import {
3
  Component,
4
  ViewChild,
5
  ViewEncapsulation,
6
  CUSTOM_ELEMENTS_SCHEMA,
7
} from '@angular/core';
8
import { HotTableModule, HotTableComponent } from '@handsontable/angular-wrapper';
9
import type {
10
  DataProviderQueryParameters,
11
  RowsCreatePayload,
12
  RowUpdatePayload,
13
  RowMutationPayload,
14
  RowMutationRemovePayload,
15
} from 'handsontable/plugins/dataProvider';
16

17
// Serializes fetchRows query parameters into a URL query string that Laravel
18
// reads via request()->input().
19
//
20
// Handsontable sends:
21
//   sort:    { prop: 'name', order: 'asc' }  or  null
22
//   filters: [{ prop: 'price', conditions: [{ name: 'gt', args: [100] }] }]  or  null
23
//
24
// Laravel reads:
25
//   sort[prop], sort[order]
26
//   filters[0][prop], filters[0][condition], filters[0][value], filters[0][value2]
27
function buildUrl(base: string, { page, pageSize, sort, filters }: DataProviderQueryParameters): string {
28
  const params = new URLSearchParams({
29
    page: String(page),
30
    pageSize: String(pageSize),
31
  });
32

33
  if (sort) {
34
    params.set('sort[prop]', sort.prop);
35
    params.set('sort[order]', sort.order);
36
  }
37

38
  if (filters?.length) {
39
    let idx = 0;
40
    filters.forEach(({ prop, conditions }) => {
41
      (conditions || []).forEach(({ name, args }) => {
42
        if (!name) return;
43
        params.set(`filters[${idx}][prop]`, prop);
44
        params.set(`filters[${idx}][condition]`, name);
45
        const a = args ?? [];
46
        if (a[0] != null) params.set(`filters[${idx}][value]`, String(a[0]));
47
        if (a[1] != null) params.set(`filters[${idx}][value2]`, String(a[1]));
48
        idx++;
49
      });
50
    });
51
  }
52

53
  return `${base}?${params}`;
54
}
55

56
// For Blade-rendered pages, inject via <meta name="csrf-token" content="{{ csrf_token() }}">.
57
// For this standalone SPA the API routes are stateless so the header is a no-op,
58
// but it's kept here so the code mirrors the recipe exactly.
59
function csrfToken(): string {
60
  return (document.querySelector('meta[name="csrf-token"]') as HTMLMetaElement)?.content ?? '';
61
}
62

63
@Component({
64
  selector: 'example1-server-side-laravel',
65
  standalone: true,
66
  encapsulation: ViewEncapsulation.None,
67
  imports: [HotTableModule],
68
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
69
  template: `<hot-table [settings]="settings"></hot-table>`,
70
})
71
export class AppComponent {
72
  @ViewChild(HotTableComponent) hotRef!: HotTableComponent;
73

74
  private removeConfirmed = false;
75

76
  settings = {
77
    dataProvider: {
78
      // rowId must match the primary key returned by the Laravel model.
79
      rowId: 'id',
80

81
      // Called on every page change, sort, and filter.
82
      fetchRows: async (queryParameters: DataProviderQueryParameters, { signal }: { signal: AbortSignal }) => {
83
        const url = buildUrl('/api/products', queryParameters);
84
        const res = await fetch(url, { signal });
85

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

88
        const json = await res.json();
89
        return { rows: json.data, totalRows: json.total };
90
      },
91

92
      // Fires when the user inserts rows via the context menu.
93
      // payload: { position: 'above'|'below', referenceRowId, rowsAmount }
94
      onRowsCreate: async (payload: RowsCreatePayload) => {
95
        const res = await fetch('/api/products', {
96
          method: 'POST',
97
          headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': csrfToken() },
98
          body: JSON.stringify(payload),
99
        });
100
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
101

102
        const data = await res.json();
103
        const row = data[0];
104
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
105
        (this.hotRef.hotInstance!.getPlugin('notification') as any).showMessage({
106
          variant: 'success',
107
          title: 'Row added',
108
          message: `Created: ${row.sku} (id: ${row.id})`,
109
          duration: 3000,
110
        });
111
        return data;
112
      },
113

114
      // Fires after a cell edit, paste, or autofill batch.
115
      // rows: [{ id, changes: { price: 149.99 }, rowData: {...} }, ...]
116
      onRowsUpdate: async (rows: RowUpdatePayload[]) => {
117
        const res = await fetch('/api/products', {
118
          method: 'PATCH',
119
          headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': csrfToken() },
120
          body: JSON.stringify(rows),
121
        });
122
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
123
      },
124

125
      // Fires after the user confirms deletion.
126
      // rowIds: [4, 7, 12]
127
      onRowsRemove: async (rowIds: unknown[]) => {
128
        const res = await fetch('/api/products', {
129
          method: 'DELETE',
130
          headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': csrfToken() },
131
          body: JSON.stringify(rowIds),
132
        });
133
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
134

135
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
136
        (this.hotRef.hotInstance!.getPlugin('notification') as any).showMessage({
137
          variant: 'success',
138
          title: 'Rows deleted',
139
          message: `Deleted ${rowIds.length} row${rowIds.length !== 1 ? 's' : ''}`,
140
          duration: 3000,
141
        });
142
      },
143
    },
144

145
    // beforeRowsMutation is sync (checks for a strict `=== false` return), so
146
    // we can't await an async prompt inline. Instead: cancel the original
147
    // attempt, show a notification with Delete/Cancel actions, and on Delete
148
    // re-issue the remove via the DataProvider API. The flag lets the second
149
    // pass through without re-prompting.
150
    beforeRowsMutation: (operation: 'create' | 'update' | 'remove', payload: RowMutationPayload): false | void => {
151
      if (operation === 'remove' && !this.removeConfirmed) {
152
        const { rowsRemove } = payload as RowMutationRemovePayload;
153
        const hot = this.hotRef.hotInstance!;
154
        const count = rowsRemove.length;
155
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
156
        const notification = (hot.getPlugin('notification') as any);
157
        const id = notification.showMessage({
158
          variant: 'warning',
159
          title: 'Delete rows',
160
          message: `Delete ${count} row${count !== 1 ? 's' : ''}? This cannot be undone.`,
161
          duration: 0,
162
          actions: [
163
            {
164
              label: 'Delete',
165
              type: 'primary',
166
              callback: () => {
167
                notification.hide(id);
168
                this.removeConfirmed = true;
169
                // eslint-disable-next-line @typescript-eslint/no-explicit-any
170
                (hot.getPlugin('dataProvider') as any)
171
                  .removeRows(rowsRemove)
172
                  .finally(() => {
173
                    this.removeConfirmed = false;
174
                  });
175
              },
176
            },
177
            {
178
              label: 'Cancel',
179
              type: 'secondary',
180
              callback: () => notification.hide(id),
181
            },
182
          ],
183
        });
184
        return false;
185
      }
186
    },
187

188
    pagination: { pageSize: 10 },
189
    columnSorting: true,
190
    filters: true,
191
    dropdownMenu: true,
192
    contextMenu: true,
193
    emptyDataState: true,
194
    notification: true,
195

196
    width: '100%',
197
    height: 'auto',
198
    rowHeaders: true,
199
    colHeaders: ['Name', 'SKU', 'Category', 'Price', 'Stock'],
200
    columns: [
201
      { data: 'name', type: 'text' },
202
      { data: 'sku', type: 'text', readOnly: true },
203
      {
204
        data: 'category',
205
        type: 'dropdown',
206
        source: ['Electronics', 'Accessories', 'Storage', 'Networking', 'Peripherals'],
207
      },
208
      { data: 'price', type: 'numeric', numericFormat: { pattern: '$0,0.00' } },
209
      { data: 'stock', type: 'numeric' },
210
    ],
211
    licenseKey: 'non-commercial-and-evaluation',
212
  };
213
}
214
/* end-file */
215

216
/* file: app.config.ts */
217
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
218
import { registerAllModules } from 'handsontable/registry';
219
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
220

221
registerAllModules();
222

223
export const appConfig: ApplicationConfig = {
224
  providers: [
225
    provideZoneChangeDetection({ eventCoalescing: true }),
226
    {
227
      provide: HOT_GLOBAL_CONFIG,
228
      useValue: { license: NON_COMMERCIAL_LICENSE } as HotGlobalConfig,
229
    },
230
  ],
231
};
232
/* end-file */

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`