Laravel Simplegrid Laravel Package

Getting Started

• Install: composer require rafwell/laravel-simplegrid. Laravel ≥5.5 auto-discovers the service provider; no migrations or required config.
• It is a rendering component, not an ORM or admin panel — it takes a query builder + field list and returns HTML for search, sort, and pagination.
• Fastest first use case: a searchable/paginated table over an Eloquent model in an admin controller.

use Rafwell\Simplegrid\Grid;

public function index()
{
    $grid = new Grid(User::class, 'users-grid');
    $grid->query(User::query());

    $grid->fields([
        'id'         => 'ID',
        'name'       => 'Name',
        'email'      => 'Email',
        'created_at' => 'Created',
    ]);

    return view('users.index', compact('grid'));
}

{{-- users/index.blade.php --}}
{!! $grid->render() !!}

Where to look first

1. README.md — the de-facto API reference.
2. src/Grid.php (and sibling classes) — authoritative method list; docs lag behind code on small packages.
3. resources/views/ — the Blade template the package renders; publish or override if the markup needs to match your layout.

Implementation Patterns

One Grid class per resource (recommended) Wrap each list view in a dedicated class — typically under app/Grids/ — extending Rafwell\Simplegrid\Grid. This centralises fields, actions, filter hooks, and default ordering, and lets you reuse the same grid on a dashboard and a full index page. Keep the controller thin: build the query, inject scopes, render.

Customising field output Field definitions usually accept either a plain label or an array with a render closure. Use the closure for:

• Formatting dates ($row->created_at->format('d/m/Y'))
• Badges for status columns
• Links to related resources (route('users.show', $row->id))
• Composite columns (e.g. avatar + name)

$grid->fields([
    'name' => [
        'label'  => 'User',
        'render' => fn($row) => '<strong>'.e($row->name).'</strong>',
    ],
    'status' => [
        'label'  => 'Status',
        'render' => fn($row) => $row->active
            ? '<span class="badge bg-success">Active</span>'
            : '<span class="badge bg-secondary">Inactive</span>',
    ],
]);

Relations and computed columns Eager-load anything a render callback touches (User::with('profile', 'roles')). Sorting on related/computed columns requires a join + select alias in the base query — accessor-only attributes cannot be ORDER BY server-side.

Row actions Wire per-row Edit / Delete buttons through the grid's action API (or a render closure that outputs an inline form). For deletes, always use a real <form> with @csrf and @method('DELETE'); a GET link will bypass CSRF.

Search and sort

• Fields are usually searchable/sortable by default; disable them on computed or high-cardinality columns.
• Set a deterministic default order so pagination is stable.
• Drive searchable text through an indexed column — LIKE '%term%' on a large unindexed table is the usual performance cliff.

Filters

• Build the base query in the controller with scopes, then hand it to the grid: $grid->query(User::where('tenant_id', auth()->id())).
• Add custom filter UI (date ranges, dropdowns) in the Blade view and feed the values into the query before passing it to the grid.

Blade integration

• render() returns HTML/HtmlString; always {!! !!}.
• If views are publishable, override the template to match your layout and add Tailwind/Bootstrap classes.

Gotchas and Tips

• Escaping: render() output is inserted raw. Escape user-controlled values inside callbacks with e(), or you reintroduce XSS.
• Search column safety: only expose trusted column names to the search mechanism. Never let a request parameter influence column, table, or SQL snippets.
• Sorting computed fields: accessor-only columns can't be sorted — either join+select a real column or disable sorting on that field, otherwise the header click throws or silently no-ops.
• N+1: any relation touched in a render/action closure must be eager-loaded. Watch DB::listen the first time you render a grid.
• Pagination + filters: when you build pagination URLs manually, always ->appends(request()->query()), or filters disappear on page 2.
• Default ordering: without a stable orderBy (ideally on the primary key), rows can shuffle between pages on large tables.
• Delete actions: use @method('DELETE') + @csrf; a plain link silently fails or, worse, deletes via GET.
• Package maturity: at 36 stars this is a small, low-bus-factor package. Pin the version in composer.json, check Grid.php when the README looks stale, and test after every Laravel upgrade — Blade views and method signatures can shift between minors.
• Debugging an empty grid: verify the query has rows (->toSql()), field keys match real attributes, and render() is being echoed with {!! !!} — a silent {{ }} is the most common "broken grid".
• Extension points: subclass Grid, override field/query setup, and reuse the base for consistent styling. Publish the Blade view for markup changes rather than forking the package.
• Performance checklist for large tables: index searchable/sortable columns, disable search on wide text fields, cap perPage, and prefer select() with only the columns you display.
• Testing: assert on grid configuration (fields, default order, query) rather than rendered HTML — HTML assertions are brittle across package patches.