Cleaver Laravel Package

Getting Started

Cleaver is installed like any Composer package and is ready to browse your data within a few minutes.

1. Install the package

   composer require aschmelyun/cleaver
   

   Before running this, sanity-check the require block on Packagist — the last tagged release is 2022-08-28 (v1.6.4), so verify the Laravel/PHP constraints match your app before you commit to it.

2. Publish the config

   php artisan vendor:publish --tag=cleaver-config
   

   This gives you config/cleaver.php, which is the control surface for everything: which tables are visible, the route prefix, and the middleware stack guarding the dashboard.

3. Publish the views (optional, but do it on day one if you plan to customize)

   php artisan vendor:publish --tag=cleaver-views
   

   Published Blade files live under resources/views/vendor/cleaver/ and become yours to edit. Publish before you start tweaking, otherwise you'll be editing files inside vendor/ that get blown away on the next composer update.

4. Lock down access immediately In config/cleaver.php, set the middleware to something like ['web', 'auth'] (or a gate/role middleware). Cleaver ships a live, unauthenticated CRUD interface — treat the default state as a red flag until you've protected it.

5. Point it at the tables you care about Whichever direction the config goes (whitelist of tables vs. exclusion list), explicitly enumerate the tables Cleaver should expose. It introspects the whole schema by default, which means users, password_resets, jobs, failed_jobs, sessions, personal_access_tokens etc. are all fair game unless you say otherwise.

6. First use case: navigate to the configured prefix (by default /cleaver), pick a table, and you have a working index with search and pagination, a show page, and create/edit/delete forms. This is the ideal "I need a back-office screen for this internal dataset by end of day" scenario — seed data, look at it, ship it behind auth.

Where to look first: config/cleaver.php for access control and table scoping, then the published index.blade.php and form.blade.php if the auto-generated columns aren't quite right.

Implementation Patterns

Treat it as an internal-ops tool, not a customer-facing admin. Cleaver is at its best on internal dashboards — content moderation queues, support lookups, ops toggles on a config table, a quick viewer for a table you'd otherwise query by hand in tinker. It is not a substitute for a product-grade admin panel with relationship editors, audit logs, and per-field permissioning (Filament/Nova territory).

Gate it behind an explicit ability, not just auth. The middleware stack is the only real security boundary. The pattern that works well:

• Add a Gate::define('viewCleaver', fn ($user) => $user->isAdmin()) in a service provider.
• Reference can:viewCleaver in the Cleaver middleware config, or wrap the whole route group in your own Route::middleware(...) if the package exposes route registration.
• Never rely on the route prefix being "hard to guess" as a security measure.

Scope tables aggressively, then relax. Start with a two-table whitelist, confirm the generated pages work against your actual data, then add tables one at a time. This keeps the surface area small and makes it obvious which table is causing a broken page when one does.

Customize the published views per-concern, not per-page. The generated views share a layout. If you need a column hidden, a badge colored, or a date formatted, edit the shared blade/partial rather than each page's Blade. Because the CRUD pages are generated from schema, editing views is the only hook you have — there is no resource class or policy layer to subclass.

Use it as a temporary scaffold while you build the real thing. A pragmatic workflow on a fresh project: stand up Cleaver early so PMs and QA have something to click through, keep building the real admin, and rip Cleaver out before launch. The composer remove exit cost is essentially zero — that's the main thing a scaffold should offer.

Combine it with php artisan db:seed for demos. Because Cleaver renders live data, a seeder plus Cleaver is the fastest way to give stakeholders something tangible to review without writing a single controller.

Keep a "cleaver-safe" set of tables. Designate a small group of tables (reference data, taxonomy, feature flags, config) where the auto-generated forms are genuinely safe to write to. Leave anything with money, PII, or state-machine columns read-only in practice, even if the package technically exposes create/edit.

Integration tip — pin it in composer.json with a caret that matches what you've tested, then run it behind a feature flag or in non-production environments first. That matches the low-commitment profile of the dependency: cheap to trial, cheap to remove.

Gotchas and Tips

• It's a 2022 package. The last release was v1.6.4 (Composer updates only). Before installing, check the composer.json require block for the Laravel and PHP upper bounds. On Laravel 10/11 you may hit constraint friction or need --ignore-platform-reqs, which is a smell worth taking seriously. Test on a branch you can throw away.

• Schema introspection runs at request time. Because the dashboard is built from the live schema, every request pays for schema reads. If the dashboard feels slow, look at caching the schema or reducing the table list — this isn't a per-table cost you can tune via a Model, it's global.

• No first-class relationship handling. Foreign keys render as raw integer IDs in the index and form. That's fine for a debugging tool, dangerous for a form — an operator typing 42 into user_id is one fat finger away from corrupting data. For any table where relationships matter, either add a select-backed partial to the published form view or leave the table read-only.

• Non-trivial column types render poorly. JSON, enums, binary, point, and long text columns will either print raw or overflow. Publish the views and add per-type formatting in the shared partial. Casts defined on Eloquent models are not applied — Cleaver is querying the schema, not going through your model layer.

• Search is per-table, not cross-table. The built-in search works within an index page. There is no global search, no saved filters, no query builder UI. If users ask for "find record X across all tables," that's a different tool.

• Published views drift. Once you publish Blade files, composer update won't update your copies — that's the point, but it also means security/HTML-escaping fixes in the upstream views won't reach you. Note it in your dependency review; for a 2022-era package, expect to own these files permanently.

• Routes can collide. The default prefix is /cleaver, but if you change it to something like /admin you'll fight any hand-rolled admin routes. Pick a namespace that won't be claimed and don't change it later without checking every hardcoded link in your published views.

• Migrations after install are invisible until the next request. That's actually a feature — add a column, refresh the page, it's there. But it also means a schema change can silently break a page that users rely on (e.g., adding a NOT NULL column with no default breaks the create form). Any migration touching a Cleaver-exposed table should be paired with a quick click-through of the affected page.

• Tailwind is expected but not built for you. The markup is Tailwind-friendly, but if your app doesn't already compile Tailwind (or you're not loading it via CDN in this context), the dashboard will look broken. Confirm your CSS pipeline picks up the Blade files under resources/views/vendor/cleaver/ — you may need to add that path to the Tailwind content glob.

• Composite primary keys and tables without an id are the first thing to break edit/delete links. Verify those tables work before exposing them; if they don't, exclude them.

• Deletes are real deletes. There's no soft-delete awareness, no trash, no confirmation beyond the form. For anything you'd want to recover, either soft-delete at the model level (which Cleaver likely bypasses) or exclude the table from create/edit/delete and keep it read-only.

• Extension point = views + config, nothing else. There's no plugin system, no resource registry, no ability to inject per-table behavior. If your requirement outgrows Blade edits and middleware, that's the signal to swap it for a real admin solution rather than fight the package.