Rapyd Admin Laravel Package

Getting Started

Rapyd Admin is an older, batteries-included admin panel: you install it, publish a config, and it gives you login, a menu, and CRUD scaffolding on top of your Eloquent models. It predates Nova/Filament conceptually (controller + trait + widget style, not Livewire components), so the mental model to hold is "Rails-style scaffolding for Laravel."

Minimal path:

composer require zofe/rapyd-admin
php artisan vendor:publish --provider="Zofe\Rapyd\RapydServiceProvider"
php artisan rapyd:install

rapyd:install is where you should look first — it creates the admin user/roles migration, seeds an admin account, publishes assets (CSS/JS/theme views), and wires up the admin routes. Run it and read what it prints before touching anything else.

Where to look first, in order:

1. config/rapyd.php (or the file the install command publishes) — URI prefix, middleware, login route, theme, menu definition.
2. app/Http/Controllers/Admin/ — the generated admin controllers and the base RapydController pattern.
3. resources/views/vendor/rapyd/ — the Blade theme; every widget and layout is overridable here.
4. routes/web.php — confirm the admin route group and middleware match the config.

First use case — scaffold CRUD for one small, non-critical model (e.g. Category):

php artisan rapyd:crud Category

That generates a controller and views for index/create/edit/delete. Log in at /<admin-uri>/login, hit the menu entry it registers, and verify list, create, edit, delete round-trip. Do this on a throwaway model before pointing it at a model with relationships, soft deletes, or custom primary keys — those are where you'll need to intervene.

If rapyd:install fails on a modern Laravel version (very common with this package), check composer.json constraints against your Laravel version before going further; the package's supported Laravel range is the single biggest deciding factor in whether this is viable for your project.

Implementation Patterns

1. The generated-controller pattern. Day to day, most of your work happens in the generated admin controller, not in Rapyd itself. The typical shape is: define the model, build a grid for the index, build a form for create/edit, and let the base class handle routing and persistence. Treat the generated controller as a starting point you edit in place — regenerating with rapyd:crud will overwrite, so diff carefully.

2. Declarative fields with dataForm / dataSet. For forms that aren't simple model persistence (wizards, settings pages, filters, multi-step import screens), Rapyd's field builder is the right tool:

$form = \Rapyd::dataForm()
    ->text('name', 'Name')->rule('required|max:120')
    ->select('status', 'Status')->options(['draft' => 'Draft', 'live' => 'Live'])
    ->textarea('notes', 'Notes')
    ->submit('Save');

Attach rules at the field level (->rule()) rather than a separate $rules array — it keeps the field definition self-contained and makes the form reusable across create and edit.

3. Grids for index pages. Configure the index grid with only the columns you actually want: searchable/sortable fields, formatted columns, and row actions. For relationships, eager-load in the query backing the grid rather than letting the grid lazy-load per row — an N+1 in an admin list at page 1 looks fine and at page 50 does not.

4. Menus and widgets. The admin shell (menu, dashboard cards, login) is assembled from widgets. Register a new menu item in the config/menu definition, and build dashboard cards as widgets rather than editing the layout Blade directly. Widgets are the intended extension point; layout edits fight the theme on upgrade.

5. Embedding admin forms in the front end. Because forms are just builder objects, you can render a Rapyd form inside any Blade view — useful for "user-facing settings" or a quick internal tool without building a full admin controller. Keep the validation rules in the form definition so both entry points share them.

6. ACL / auth integration. Rapyd leans on Laravel's auth plus a role/permission layer it seeds. Gate admin routes by middleware in the config's route group, and check permissions per-controller rather than per-view. If you need custom authorization, do it in the controller's __construct or middleware — don't scatter checks in views.

7. Extension pattern: custom field types. When you need a field Rapyd doesn't ship (e.g. a tag input or a dependent select), register a custom field type with its own Blade partial inside resources/views/vendor/rapyd/ and use it like any built-in field. This is cheaper and more upgrade-safe than post-processing generated HTML.

Gotchas and Tips

Version compatibility is the whole ballgame. Rapyd Admin's release history tracks Laravel 5.x–6.x era APIs. On Laravel 8+ you will hit hard failures in service provider registration, facade aliases, and Blade directives. Before committing, verify the package's composer.json illuminate/* constraints against your app, and be prepared to pin an older Laravel or vendor/patch the package. This is exactly why the package's practical score sits low despite its star count.

Regeneration overwrites. rapyd:crud and rapyd:field write into app/ and resources/views/. Commit before running them, and never run them against a controller you've customized without reviewing the diff. The commands are scaffolding tools, not idempotent generators.

Config cache hides route/menu changes. php artisan config:cache will freeze the admin URI, middleware, and menu. If a new menu entry "doesn't appear," clear config and route caches first — this accounts for a large fraction of confused debugging sessions.

Asset publishing is a manual step after every update. vendor:publish --force for Rapyd's theme assets on upgrade, or the UI will silently serve stale CSS/JS while the backend changes. Better: publish once, then diff the vendor assets on upgrade rather than blanket-forcing (blanket-forcing wipes your theme overrides).

Auth guard collisions. If your app uses a non-default guard or a custom User model, Rapyd's login may authenticate against the wrong provider. Set the guard explicitly in config and confirm the seeded admin user exists in the right table.

Validation belongs in the field definition. ->rule() on each field is easy to forget when you add a field later — a field with no rule is silently unvalidated. Do a pass over the form definition before shipping.

Relationships need explicit handling. Rapyd's generated CRUD assumes a flat model. Belongs-to needs a select populated from the related table; many-to-many needs manual sync in the controller's store/update. Don't expect the scaffold to infer this.

Pagination and large tables. Default page sizes and the searchable-field configuration are easy to leave at defaults; on real tables this means slow queries. Set per-page and the searchable/sortable column set deliberately in the grid.

Debugging approach. When a grid or form renders blank or throws, the failure is almost always in the field/grid definition (a missing label, an options array where a closure was expected) rather than in the package. Dump the builder object before render — the config is data, and inspecting it is faster than reading package source.

Extension points to prefer, in order: custom field types → widgets → published Blade views → patching vendor code. Only the last one is a trap, and it's the one people reach for first when the docs are thin. Wrap any vendor patch behind a fork you control so composer update doesn't silently revert it.

Realistic scope. Use this package for internal tools, back-office screens, and low-stakes CRUD where "good enough admin" beats "weeks of UI work." For anything customer-facing, heavily permissioned, or expected to live through multiple Laravel majors, budget for migrations off it — the maintenance trajectory is the risk, not the API.