Download the PHP package ngos/admin-core without Composer

ngos/admin-core

Build a full Laravel admin panel fast. One command scaffolds a CRUD resource — model, migration, controller, form requests, Blade views, permissions and a searchable/sortable/exportable DataTable — on a clean, branded Bootstrap 5 theme.

• One generator. admin-core:make Product → a complete, permission-gated admin screen.
• Batteries included (all opt-in flags): login + users/roles/permissions, CSV import/export, soft-deletes, audit log, error log, a JSON API, and a dynamic, permission-aware sidebar.
• Multi-portal. Stand up a second portal (merchant, vendor…) on its own auth guard in one command.
• Thin & conventional. Generated code lives in your App\ namespace and extends a small base (WebController + BaseService) — no magic, easy to read and edit.

🚀 New here? Start with the step-by-step tutorial — it builds a working catalog admin from scratch (install → categories → products with a relation, image & status → roles → a custom action) and explains every step. The reference below is for once you know the loop.

Contents

• 🚀 Tutorial — zero to a working admin, hand-held
• Quickstart — a working admin + your first resource
• Installation (minimal vs --access)
• field types · add a field later
• What every list gets: export / import / bulk-delete · field-level permissions · reorder · error log
• Media library — reusable files via media / gallery fields + HasMedia
• Dashboard widgets — config-driven stat / chart / list cards
• API token auth
• Multi-portal — a separate-guard merchant/vendor area
• Notifications — in-app bell + notifications page
• Config & commands

Want the layer map? ARCHITECTURE.md — web + JSON API over one shared service, plus a "where do I put X?" cheat sheet.

Quickstart

A working, authenticated admin in two steps.

1. Install (scaffolds login + users/roles/permissions + the theme, then builds assets and seeds an admin):

Log in at /login with [email protected] / password.

2. Generate your first resource:

Visit /admin/products — full CRUD with search, sort, status filter-tabs and CSV export. That's the whole loop; everything below is detail.

No styling? The theme needs a front-end build. The --build flag above runs it; otherwise run npm install && npm run build yourself. (The admin still renders without it — just unstyled.)

Requirements

• PHP ^8.3, Laravel ^13
• spatie/laravel-permission ^8, yajra/laravel-datatables-oracle ^13 (pulled in automatically)

Installation

There are two levels. Most people want --access (the Quickstart above) — a working, authenticated admin.

Minimal — just the CRUD engine

Scaffolds only the glue generated pages need (idempotent; --force to overwrite). You bring your own auth:

Full access module (--access) — login + users/roles/permissions

--access ships its own create_permission_tables migration (uuid + group_id aware) — don't also vendor:publish Spatie's, or migrate fails with "table 'permissions' already exists". If you already did, the installer now removes the duplicate for you.

On top of the minimal install, --access adds (all in your App\ namespace, yours to edit):

• Auth — a session LoginController + login view + /login /logout; the admin route group is auth-gated.
• Users / Roles / Permissions screens built on the CRUD core, with role/permission assignment.
• App\Models\Role / App\Models\Permission (extending spatie), HasRoles on App\Models\User, the sidebar, and an AccessSeeder (an admin role with every permission + the [email protected] user).
• The themed front-end kit (--build runs npm install && npm run build).

Syncing permissions (admin-core:sync-permissions)

admin-core:make writes only files — it never touches the database (so generation works offline, in CI, and against an unreachable database). The routes it generates gate on permission:{action}-{resource}; run admin-core:sync-permissions to create those permissions and grant them to the configured role. It reads the permissions from the routes (no manifest), is idempotent (safe to re-run any time — after a deploy, a database restore, or generating a new resource), and never throws when the database is unavailable:

Exit codes (for CI): 0 on success or --dry-run; 2 when the database is unreachable on a real run (nothing written). Grants go to config('admin-core.permission.default_roles') (or the per-guard/global super_role when empty). Run admin-core:doctor (below) to check which route-enforced permissions are still missing. (Detailed docs to follow.)

Keeping published assets in sync (admin-core:doctor)

The front-end kit (the JS behaviour in resources/js, the theme SCSS, the layout Blade) is copied out of the package at install time — so those copies freeze, and a later package fix to, say, resources/js/datepicker.js never reaches an app that installed an older version (stub drift). After upgrading the package, run:

Behaviour files (.js) are flagged distinctly — they're the ones that usually carry bug/security fixes. Your own theme/layout edits live in these files too, so --fix is opt-in (and refuses non-interactively without --force); review with git diff before committing, then rebuild assets.

admin-core:doctor also runs a Permission Health check: it reports route-enforced permissions with no database row, permissions not granted to the super role, and orphan permissions, and recommends admin-core:sync-permissions (it never changes anything automatically). Doctor exits non-zero when it finds missing/ungranted permissions, so CI can catch a resource that was generated but never synced.

Finally, admin-core:doctor flags stale generated resource files. The per-resource controllers and trash views that admin-core:make writes into your app also freeze — a later framework fix to what the generator emits (e.g. a raw LIKE filter superseded by Support\Search, or a trash route keyed off ->id instead of the public route key) doesn't reach already-generated resources. Doctor idiom-lints those files against a catalog of superseded framework idioms and lists each stale file under a distinct Generated Resource Staleness heading with the idiom, the version that superseded it, and the remedy (regenerate or hand-patch). This check is report-only — it never rewrites a generated file, even under --fix — and severity-gated: only a security/correctness idiom makes doctor exit non-zero; a cosmetic one is advisory.

Generating a resource

Generates the model, service, controller, form requests, a route module, the Blade views, and the list/create/edit/delete-product permissions. Visit /admin/products.

Run it for a new resource without --fields and it prompts you for them interactively — enter a name, pick a type from the menu, answer nullable/unique, repeat until you leave the name blank — then generates from your answers. (You don't have to know the --fields DSL below to get started; pass --fields to skip the prompts, and non-interactive runs — CI, scripts — just scaffold the default name field.) Prefer to write the DSL by hand? php artisan admin-core:make --list-fields prints every type and modifier it accepts.

Generating fields too (--fields)

Pass a field list and the generator fills in the migration columns, $fillable, validation rules, form inputs, table headers, and DataTable columns — a ready-to-use CRUD, no manual edits:

Field DSL — name:type, comma-separated:

The model also gets a casts() method (boolean, date, datetime, decimal:2, money → MoneyCast, json → array, password → hashed, enum → its backed enum class). A slug left blank is derived from name in the creating hook; a json field round-trips through a textarea (decoded in prepareForValidation, stored via the array cast); a blank password on update is dropped so the existing hash is preserved.

Date inputs use a themed calendar. date/datetime fields render as Air Datepicker text inputs (--access bundles it) — a Bootstrap-themed calendar (with a time picker for datetime) that matches your accent and flips with dark mode, instead of the unstyled native picker. The submitted value keeps the Y-m-d / Y-m-d H:i shape the date rule and the model cast expect. The bundle auto-attaches it to any .js-datepicker input on load; for a modal/AJAX-loaded form, call window.acInitDatepickers(formEl).

Money is stored exactly, as an integer. price:money keeps the amount in minor units (cents) in a bigInteger column and casts it to a Ngos\AdminCore\Support\Money value object — so amounts and sums stay exact (no 0.1 + 0.2 = 0.30000000000000004 float drift). The form edits the major amount ("15.00") prefixed with the currency symbol; the list/show render $object->price->format() ("$15.00"). The default currency is config('admin-core.money.currency') (set ADMIN_CORE_CURRENCY); pin one column with price:money:KHR. Each currency's decimals/symbol/position/separators live in config('admin-core.money.currencies') — Khmer Riel (KHR) is 0-decimal, so ៛15,000 stores as 15000 (not ×100), while USD ($15.00) stores as 1500. In code: $product->price->minor() (1500), ->major() ("15.00"), ->format() ("$15.00"), ->add()/->subtract()/->multiply() (exact, same-currency); assigning a number or a Money both work ($product->price = '15.00'). CSV export writes the plain major() value so a round-tripped import re-parses exactly.

Per-record currency (multi-currency). When one column holds amounts in different currencies row by row (a Purchase in USD next to one in KHR), use total:money:@currency — the cast reads each row's code from a sibling currency column instead of a fixed one:

Each row stores its exact minor units for its own currency (USD 1500, KHR 15000) and reads back formatted in that currency ($15.00, ៛15,000); the form shows the record's symbol when editing. The currency column must be a user-settable enum or string holding the code, and — because a write parses the amount with that column's decimals — declare it before the money column so the form/rules fill it first (the make command warns if not; otherwise a new record's amount is parsed with the default currency). Reads are correct as long as the whole row is loaded (don't select() away the currency column). A Money of a currency other than the row's is refused, never silently reinterpreted.

Two things follow from the amount being stored as bare minor units: changing only the currency does not convert an existing amount ($15.00 re-saved as KHR reads ៛15, by design — re-enter the amount), and a per-record column isn't given an amount range filter (one bound can't honour each row's decimals — filter by the currency column instead).

Computed fields are derived, not stored. total:computed:qty*price adds a read-only Eloquent accessor — no column, not fillable, not in the form, but shown read-only in the list and on the show page and appended to the model's array/JSON. The expression is a typed arithmetic formula (+ - * / ( ), numbers, and other field names) compiled at generation time:

• numeric operands (integer/decimal) use operators — qty*price → ($this->qty * $this->price).
• money operands compose too — qty * unit_price (where unit_price is money) → $this->unit_price?->multiply($this->qty), returning an exact Money that's shown formatted ($7.50). money + money → ->add(), money - money → ->subtract(), money / scalar → ->divide().
• nonsensical mixes are rejected at generation (money * money, money + number, ÷ money), as are typos, non-numeric references, and anything that isn't a well-formed formula — so nothing user-written becomes arbitrary or broken PHP.

For string concatenation, dates, or formulas the compiler doesn't cover, use a bare total:computed and fill in the generated accessor stub. Computed columns can't be sorted or searched in SQL (there's no column behind them); the value is appended to every serialization, so make sure its source columns are loaded (a partial select() that omits them makes a numeric formula read them as 0; money operands are null-safe via ?->). Add computed fields at make time — admin-core:field defers them to the full generator.

Rollups total up a master-detail document. total:rollup:lines.line_total adds a read-only accessor that sums a child hasMany — the document total = the sum of each line's line_total. It's money-aware (Ngos\AdminCore\Support\Rollup::sum): money line totals sum to an exact Money (shown formatted), plain numbers sum numerically, an empty document totals 0. Like computed it's derived — no column, not in the form, appended to array/JSON, shown read-only in the list and on show — and the rolled-up relation is eager-loaded in the list so it isn't N+1. The relation must be a hasMany declared on the same resource (lines:hasMany:invoice_lines, total:rollup:lines.line_total), which completes the master-detail story: line items (hasMany) → per-line money totals (money + computed) → document total (rollup). The summed attribute can itself be a child computed/money value. For very large child sets, sum a real column with a database aggregate instead (the rollup loads the children to sum them).

Two things to know: the rolled-up child value must be consistently one type and money rows must share a currency — a mix fails loudly (a silently-wrong money total is worse). And the hasMany child is a separate resource this command doesn't scaffold — generate it (admin-core:make InvoiceLine …) too, or the list/show/API will error when the rollup dereferences a missing model (the generator warns you about this).

Denormalise from a picked relation (--derived). A line item usually copies + computes from the row the user selects — a qty_base from the chosen unit's conversion factor, the variant_id behind the picked product-unit. computed/rollup work over the same row / a child, but not a belongsTo you just picked, so --derived writes those columns in the model's saving() hook:

The expression is arithmetic (+ - * / ( )) over same-row columns and fk_column.attribute references (the FK's related row); a lone reference is a copy (kept as-is — an id, a code; write it alone, since any operator forces float maths that would corrupt a large id). The related row is fetched once per FK and the columns recompute on every write (create + update) when a source changes; a missing relation / blank value resolves to 0/null (a divide-by-zero yields 0, never an error). A derived target is not in the form, validation or $fillable (the hook owns it) but stays a normal, nullable, displayed column; unknown columns, non-foreign references, self-references and malformed expressions are rejected at generation. Two limits: a bulk Model::query()->update() fires no model events so it won't re-derive (save models individually), and each save issues one find() per referenced FK. Pair it with data-ac-compute for the live in-form preview.

Enums are code, not schema. status:enum:draft|published generates App\Enums\ProductStatus (a string-backed PHP enum) as the single source of truth: validation uses Rule::enum, the model casts to it, and the form select, index filter-tabs and factory iterate its cases(). The DB column stays a plain string — so adding a value is one new case in that file, no migration, and every layer picks it up.

image/file also generate upload handling in the service (store on the public disk, delete the old file on update, clean up on delete) and add enctype="multipart/form-data" to the form — run php artisan storage:link once. belongsToMany generates the pivot migration, a belongsToMany relation, a multi-select, and sync() in the service. Both infer the related model/table from the field name, so generate the related resource first.

Modifiers (suffix, any order):

E.g. slug:string^, published_at:date?# (nullable + indexed), status:enum:new|paid#, sku:string^~ (unique, locked after create).

Composite unique — for a constraint spanning several columns (one product per order line, one SKU per branch), the ^ modifier isn't enough. Pass --unique="col,col" (repeatable):

It generates a DB $table->unique(['order_id', 'product_id']) and a FormRequest Rule::unique (riding on the group's first column, with a ->where() for each of the others, ignoring self on update) so a duplicate combination fails with a clean message before it ever hits the database constraint. Each group needs ≥2 distinct scalar columns (string/integer/money/foreign/enum/date/… — not text/json/translatable). A group that includes a system (@) or write-once (~) column is enforced by the DB constraint alone (its value isn't in the form to validate, so a duplicate surfaces as a database error — the generator warns you).

Typed system helpers (imply @, auto-filled in the generated booted() hook — no TODO to wire up):

E.g. --fields="name:string, code:sku, created_by:auth" gives you an auto SKU and an owner stamp with zero hand-editing — neither is user-fillable.

Sequence — sequential document numbers. invoice_no:sequence:INV assigns the next number in the model's creating hook: "INV-0001", "INV-0002", … (bare invoice_no:sequence → "0001"). It's concurrency-safe — Ngos\AdminCore\Support\Sequence locks a per-(key, period) counter row (number_sequences table, a package-shipped migration — run php artisan migrate after upgrading), so two simultaneous creates never collide. The column is unique, and a number you set yourself is kept (the hook uses ??=). The number is allocated inside the create's transaction, so a rolled-back create releases its number for the next one — committed rows stay sequential and gap-free, with no number burned by a failed attempt. (For numbering that must never reuse a value even across rolled-back attempts, allocate out-of-band.) Edit the generated hook for other formats — Sequence::next('invoices.invoice_no', 'INV-', 5, 'year') zero-pads to 5 and restarts each year ("INV-2026-00001"); pass 'month' to reset monthly.

Security note: ~ and @ enforce on the server (missing update rule / not fillable), not just the readonly input — so a user editing the DOM or POSTing directly still can't change them.

Foreign keys: category_id:foreign adds a belongsTo relation on the model, a Select2 dropdown of the related rows in the form, and a related-label column in the table. Every related-label surface — the select (current value + remote search), the list column (display, filter, sort), the list-filter dropdown, the API resource, and the show/trash views — resolves the related model's display column the same way: an explicit displayColumn() method on the related model, else the first of name → title → label present on its table, else the route key (so a title-based model like a Course labels/filters/sorts by title, and a name-based model is unchanged). The related table is inferred (category_id → categories), so it must already exist — generate the parent resource first.

This resolution is exposed as structured metadata via ac_display_descriptor($model) (kind = column / computed / none, plus the backing column), and the related-label read path (ac_related_label()) resolves through it. For a label-less related model (no name/title/label and no displayColumn() override) that relation cell renders empty (Explicit NONE) by default since v3.0.0; set admin-core.explicit_none (env ADMIN_CORE_EXPLICIT_NONE) to false to restore the pre-v3.0.0 route-key display — a deprecated opt-out (see UPGRADING.md). The column resolution itself still falls back to the route key, so search/sort keyed on it are unaffected.

App shell (with --access)

The --access kit now ships a complete admin shell beyond the access screens:

• Profile / account (/admin/profile) — edit name/email, change password, upload an avatar.
• Settings (/admin/settings) — grouped key-value app settings with a Setting::get('key') helper (cached), gated by the manage-settings permission. Seeded with app_name, support_email, etc.
• Dashboard — stat-card widgets (Users / Roles / Permissions / Group Permissions counts).
• Dynamic, permission-aware sidebar — the menu is a data array in config('admin-core.menu'), rendered by <x-admin-core::sidebar-menu />. Each item is dropped automatically when the user lacks its can permission or its route doesn't exist (so menus for un-installed features vanish on their own), and empty section headers are pruned. admin-core:make appends the new resource there — no hand-editing Blade. (Older installs with the static sidebar still work: the generator falls back to injecting the link.)
• Database-driven menu + Menu manager (optional) — manage the sidebar at runtime instead of editing config. Set config('admin-core.menu_source') to 'database' (default 'config') and the same <x-admin-core::sidebar-menu /> renders the menu_items table — cached (MenuItem::tree(), busted on every write) and filtered by the same permission/route rules. The Menu manager at /admin/menu (System → Menu, manage-menu) lets admins add/edit/delete items and drag to reorder & nest them; each item is a label + icon + a named route or custom URL (or none → a section header) + optional permission + active toggle. Move your existing menu into the table with php artisan admin-core:menu:import. Ships with --access.
• Multi-portal — stand up a second portal (merchant, vendor, …) in one command: php artisan admin-core:portal merchant scaffolds its own-guard user model + migration, login + dashboard, route group, and menu/permission config. Then admin-core:make Order --portal=merchant generates straight into it: routes under routes/Merchant/Modules with merchant.* names, permissions + gates on the merchant guard, and a menus.merchant entry rendered by <x-admin-core::sidebar-menu menu="merchant" guard="merchant" /> (filtered against that portal's user). Single-guard apps just don't use it — nothing changes. See UPGRADING for details.
• Show / detail view — every resource gets a read-only show page + a View button in the table.

Every list comes with export, import & bulk delete

Generated index screens ship these out of the box:

• Export — an Export button (a dropdown with a checkbox per field) streams the chosen columns to CSV (export route + ?columns[]=, gated by list-*; leave all checked for everything). Relations are included as readable columns — belongsTo as the related name (next to the FK) and belongsToMany as the related names joined (e.g. tags = "red, blue"). The output is injection-safe (formula cells are neutralised) and leads with a UTF-8 BOM so Excel reads it correctly.
• Import — an Import button opens a modal to upload a CSV (same shape as Export). The modal links a blank template (importTemplate route) — a header-only CSV of the importable columns (fillable, minus password/file columns) so users don't have to guess the fields. Each row is validated against the resource's store rules; only fillable columns are kept (so a round-tripped export with id/uuid/timestamps imports cleanly), invalid rows are skipped and reported (import route, gated by create-*).
• Bulk delete — a select-all checkbox column + a "Delete selected" button that soft/hard-deletes the chosen rows in one request (bulkDelete route, gated by delete-*).

All live on the base WebController (export() / import() / bulkDelete()), plus a single DataTables search box (server-side via yajra), so they apply to every resource. Relation columns are searchable by the related record's name out of the box (via whereHas): a belongsTo column is also sortable (a correlated subquery), and a belongsToMany column is searchable but not sortable (sorting a multi-value relation is ambiguous). Both assume the related model has a name column — the same assumption used to display it.

Advanced list filters

Beyond the global search box, generated lists get a filter bar above the table: a dropdown per enum (its cases), boolean (Yes/No) and foreign (the related rows) field, a from–to date range per date/datetime, and a min–max number range per money/decimal (a money filter's typed amount is converted to the stored minor units). A text LIKE filter and an integer range are supported too — add them to listFilters() by hand (strings are covered by the global search, so they aren't auto-generated; a text value's %/_ act as wildcards, matching the global search). The foreign dropdown loads its options at render time (not on each data request), so it suits small/conventional relations — for a large or translatable-name relation, replace that listFilters() entry with a remote source. Changing a control reloads the table server-side (the shared datatable.js appends ?filter[col]=… to each request); Clear resets them.

It's declared on the controller (the generator fills it from the fields) and whitelisted — only the listed columns are filterable, so a crafted ?filter[…] can't touch an arbitrary column:

WebController::applyListFilters() applies them (exact match for select, whereDate ≥/≤ for date) before yajra's own search/sort/paging run. The <x-admin-core::list-filters :filters="$acFilters ?? []" table="…_table" /> component renders the bar (it's in the generated index view). Existing installs: republish the package datatable.js (admin-core:doctor flags it) and add the component + listFilters() to opt a screen in.

Saved views. The filter bar also has a per-user Views dropdown: save the current filters as a named view, re-apply one in a click, or delete it. Views are stored per user, per resource in a package-shipped saved_views table (run php artisan migrate after upgrading); Route::adminCoreSavedViews() exposes the endpoints (admin-core:install adds it — existing installs add it to their admin route group). Every row is scoped to the current user, so one user never sees or deletes another's. The dropdown only appears when those routes are wired, so it degrades silently if you haven't opted in.

List footer totals

Turn a list into a report with a totals row — revenue, on-hand stock value — without leaving the skeleton. The generator auto-sums every money column; the footer total is computed server-side over the filtered set (all pages, honouring the active list filters — not just the visible rows), formatted as exact Money:

datatable.js builds the footer row and fills it from each AJAX response, so the total updates live as filters change. Notes: a per-record / multi-currency money column isn't auto-totalled (mixed currencies can't sum to one amount); the total reflects the structured list filters, not the free-text search box. Opt in by adding listAggregates() (the generator does it for money columns); a list that declares none has no footer.

Read-only resources (reports)

A report is a list you read, not edit. --read-only scaffolds exactly that — the list, show and export, with all the DataTable filters/totals — but no create / edit / delete / import:

It skips the FormRequests and the create/edit/form views, registers only the read routes (Route::crud(..., readOnly: true) → index/getData/select + show + export), and seeds only the list permission — so the create/edit/delete buttons (gated on those absent permissions) never render. Every write button is also Route::has()-guarded, so it stays hidden even with permissions off. Point the generated model at a real table or a database view; add listAggregates() for a totals row. --soft-deletes and --sortable (write features) are ignored with a notice. With --api, the JSON API is read-only too (index + show, no store/update/destroy).

Singleton resources (--singleton)

Some screens edit one record, not a table — Settings, a company profile, tax config, the current user's profile. --singleton scaffolds exactly that: an edit form (index) + a save (update), with no list / create / delete:

The generated controller extends SingletonController and registers only two routes via Route::crudSingleton(...) — GET / (the form) and PUT / (save) — both gated by edit-{resource} (the only permission seeded). The single row is the one (or first) row, created on first save. For a per-owner singleton (a profile), override recordScope() — the scope both resolves the row and is force-re-applied after the form fills, so a posted value can never repoint the row to another owner (it's safe whether or not the scope column is fillable):

(Point the model at a table that holds one row per scope — an unscoped singleton over a multi-row table just edits the first row.)

It fits the gap between admin-core:make (a full CRUD table) and admin-core:page (a model-less static page): a model-backed, validated, one-record screen. --soft-deletes / --sortable / --api don't apply (a singleton has no list or API surface) and are ignored with a notice.

Create / update / delete (and restore) flash a success message that the layout renders automatically. Customise or translate it by overriding one method on the generated controller:

Custom table actions

Beyond delete, every list can carry custom bulk + per-row actions. Declare them once in the controller's resourceActions() and the package wires the toolbar button, the row-menu item, the route, the permission gate, the confirm dialog and the toast:

The handler receives the selected models — resolved through the resource query, so scopes / soft-deletes / tenancy apply (you can only act on rows you can see). Fluent options: ->permission('…') (defaults to {key}-{resource}), ->withoutPermission(), ->onlyBulk(), ->onlyOnRow(), ->confirm('Sure?'), ->success('Done!'). The permission is enforced server-side — hiding a button is cosmetic. Add the permission (e.g. mark-paid-product) to your seeder.

Field-level permissions

Lock individual fields to a permission — a user without it can't see the field (it's disabled in the form) nor write it (stripped server-side, so a crafted POST can't set it either):

Covers direct fillable columns. On update the stored value is merged past validation, so locking a required field still lets a restricted user save the rest of the form.

Approval workflow

Mark a sensitive action ->requiresApproval() and it won't run for a user who can request it but not approve it — instead it files a pending request that an approver clears from the Approvals inbox:

• A requester (has refund-order, not approve-refund-order) → files a request; approvers are notified.
• An approver opens admin.approvals.index → Approve (re-runs the action over the captured rows) or Reject (with a reason); the requester is notified of the decision. A user who can approve runs it directly (no self-request).

Run php artisan admin-core:install (adds Route::adminCoreApprovals()) + php artisan migrate (the approvals table), and grant approve-{action}-{resource} to your approver role.

Document state machine — transitions + input actions

A document-style resource declares a transitions() state machine — each Transition is a show-page button that moves one record between states, atomically (lock → verify the from state → run the side-effect → claim the to state in one transaction, so a double-click can't post twice), gated by {key}-{resource}:

Actions that take input. Add a form() and the action collects validated input first (the show page auto-renders a modal); the validated values reach the handler's second argument — so close-with-a-count, approve-with-a-note, ship-with-a-tracking-number, refund-with-an-amount no longer drop you into a bespoke route:

The input is validated before the lock (an invalid form redirects back with errors and re-opens the modal, holding no lock). Field types are inferred from the rules (numeric→number, boolean→checkbox, date→date, else text) or set explicitly (type ⇒ text/number/textarea/select/date/checkbox).

Pure actions (no state move). Pass to(null) (or just omit to()) and the action runs its guarded + validated + atomic handler without advancing a state column — a cash pay-in, a recompute. With no state to claim, the action is kept idempotent by the form's one-time submit token (a double-submit 409s; a failed run releases the token so a genuine retry still goes through), the same guard the create form uses — so the auto-rendered modal always carries it. A direct/programmatic POST that omits _idempotency_key (or with admin-core.forms.idempotency off) isn't deduped, exactly as for any form:

A handler written fn ($record) => … (one parameter) still works — it just ignores the input. The transition route is wired by Route::crud() (skipped on a --read-only resource).

Drag-to-reorder (--sortable)

Adds a sort column and a Sort toggle button on the index that reveals a drag-and-drop panel (reusing the bundled nestable plugin) — the DataTable stays put. Dragging a row posts the new order to a reorder route, which persists each row's sort position via BaseService::reorder(). Best paired with the --access kit (which bundles the nestable JS).

Audit trail (--audit)

Adds the package's LogsActivity trait to the model, recording every create/update/delete in activity_logs (the actor, the subject, and the changed attributes — sensitive fields like password are filtered out). The activity_logs table migration is published by admin-core:install; the --access kit adds a read-only Activity Log viewer (gated by list-activity). Set 'generator' => ['audit' => true] to audit every generated resource, or add the trait to any model:

Error log

The --access kit ships an Error Log: unhandled exceptions are written to an error_logs table (type, message, file:line, stack trace, URL/method, user) and browsable at admin/error-logs (gated by view-error-log) with a per-row detail view, delete, and "Clear all". Capture is wired by a reportable callback the package registers on the framework's exception handler — no bootstrap/app.php edit needed. It's deliberately quiet: expected exceptions (validation, auth, 404 and other 4xx HttpExceptions) are skipped, only genuine faults (5xx / uncaught) are recorded, and capture is fully defensive — if the table is missing or anything throws while logging, it no-ops rather than masking the original error. The error_logs migration is published by admin-core:install --access.

The log self-trims: rows older than config('admin-core.error_log.retention_days') (default 30) are pruned by a daily model:prune the package schedules for you (needs the app's scheduler cron running). Set it to 0 to keep errors forever, or prune on demand with php artisan model:prune --model="Ngos\AdminCore\Models\ErrorLog".

Soft deletes & extras

Every admin-core:make also generates a Factory (field-aware fake data), a Seeder, and a permission-mapped Policy. Add --soft-deletes for a trash workflow:

It adds the SoftDeletes trait + deleted_at column, a Trash button on the index, and a trash screen with Restore / Delete permanently (routes trash / restore / forceDelete, backed by trashedQuery() / restore() / forceDelete() on the base service). "Delete permanently" is a true hard delete; resources generated without soft deletes hard-delete on the normal delete.

To make every generated resource soft-delete by default, set 'generator' => ['soft_deletes' => true] in config/admin-core.php (override per-resource with --no-soft-deletes for high-churn tables like sale lines or ledger rows that should hard-delete).

Generated tests (--tests)

Writes a self-contained tests/Feature/ProductTest.php that drives the resource over HTTP: the index + getData render, store persists (faking any image/file uploads), update + delete resolve by the public route key, and the index is forbidden without permission. It creates its own user and grants the resource's permissions (via config('admin-core.permission.model')), so it runs green out of the box — pair it with --migration so RefreshDatabase has the table.

JSON API (--api)

For a decoupled front-end (Nuxt, mobile, another SPA) or a multi-tenant merchant portal, --api adds a clean JSON API alongside the Blade admin:

Generates a ProductResource (JsonResource), a Api\ProductApiController (index/show/store/ update/destroy), and a apiResource route file under api.products.* — Sanctum-gated, with each action carrying the same permission as the web admin (list/create/edit/delete-product), so the API and the back office enforce one permission model.

Channels are independent — pick what you need, add the rest later:

Re-running is additive (existing files are skipped): a web-only resource gains the API by re-running with --api; an api-only resource gains the web channel by re-running without --api-only. When you add a channel to a resource that already exists, you can omit --fields entirely — they're reconstructed from the existing model + migration (types and all), so adding the API to ten web resources is just:

(Upload image/file columns can't be told apart from plain strings when inferring — pass --fields explicitly for those.) Both channels share the same model/service/requests, so nothing is duplicated. The controller reuses the same Service + FormRequests as the web CRUD, so validation/authorization live in one place; the index is paginated (?per_page=). Crucially, the public id is always the uuid route key, never the bigint id — so internal ids are never enumerable across tenants:

List query — the index supports ?search=, ?sort=, ?filter[col]= and ?per_page=, so a front-end data table works out of the box:

The generated controller derives the whitelists from the fields — $searchable (text columns, LIKE), $sortable (scalar columns + created_at; -col = desc), $filterable (enum/foreign/boolean, exact match). Anything not on a whitelist is silently ignored, so a client can't sort/filter by an arbitrary column. per_page is clamped to config('admin-core.api.max_per_page') (default 100).

Configure the guard + page size in config('admin-core.api') (default ['auth:sanctum'], 25) — add a tenant-scoping middleware there for multi-tenant setups. API route files are auto-loaded if routes/api.php globs routes/Api/Modules/*.php:

API auth — token login (admin-core:install --api-auth)

Your --api resources are guarded, but the SPA/mobile client needs a way to log in and get a token. admin-core:install --api-auth scaffolds OAuth2 auth (Laravel Passport, password grant):

It publishes Api\AuthController (/api/login, /api/logout, /api/me) + an ApiAuthServiceProvider (short-lived tokens: 1h access / 14d refresh; login throttled 6/min), wires routes/api.php (auth routes

• the Api/Modules loader) and bootstrap/app.php, and flips admin-core.api.middleware to auth:api. /api/login proxies the password grant in-process so the client secret never leaves the server:

Passport can't be pulled in by an artisan command, so the install prints the finishing steps: composer require laravel/passport → vendor:publish --tag=passport-migrations (Passport 12+ no longer auto-loads them) → migrate (oauth tables) → passport:keys → passport:client --password (put the id/secret in .env as PASSPORT_PASSWORD_CLIENT_ID/_SECRET) → add the api guard (driver: passport) to config/auth.php → add Laravel\Passport\HasApiTokens to App\Models\User. Then POST /api/login.

Non-enumerable URLs — the hybrid key strategy (--uuid)

--uuid gives a resource a public UUID for its URLs while keeping a fast bigint primary key:

It generates:

• $table->id(); — the bigint primary key (all foreign keys and joins use this → lean indexes that never bloat)
• $table->uuid('uuid')->unique(); — the public key used in URLs/APIs (/admin/products/019eadac-…, non-enumerable)
• foreignId('category_id')->constrained() — bigint FK (not foreignUuid)
• a model using the package's HasPublicUuid trait, which auto-fills the uuid and sets getRouteKeyName() => 'uuid'

So you get non-guessable URLs without the index/join cost of uuid primary keys — the best default for a system that may grow. The base BaseService resolves every action by the model's route key, so edit/show/update/delete/bulk-delete/reorder all use the uuid automatically; plain id models (no --uuid) keep using id unchanged.

To make every generated resource hybrid, set 'generator' => ['uuid' => true] in config/admin-core.php (override per-resource with --no-uuid). The --access module (users/roles/permissions/group-permissions) ships hybrid too. Use a plain model? Add Ngos\AdminCore\Concerns\HasPublicUuid + a uuid column to any model.

Omitting --fields gives the default single name column (backward-compatible). The generated routes are gated by permission:* middleware. Either assign the new permissions to a role and wrap the admin-core:routes group in ['auth', ...], or set permission.enabled => false in config/admin-core.php to browse without auth while developing.

Adding a field later (admin-core:field)

admin-core:make scaffolds a resource once; to add a field afterwards (the part you'd otherwise do by hand — migration and model and views), use admin-core:field:

It generates an add_…_to_products_table migration and surgically patches the model ($fillable, casts, and the booted() slug-derive hook), the store/update requests (validation rules + the prepareForValidation() hook for json/password), the form / table-header / DataTable-script / detail (show) views, and the factory — adding just those fields. Same --fields DSL (so status:enum:a|b also creates the backed enum class). Fields that already exist are detected and skipped — by the model's $fillable and the real DB column (so a column that isn't in $fillable is still caught, never producing a duplicate-column migration). Re-running is safe — pass a mix of old and new and only the new ones are added:

It resolves the resource by singular name, so admin-core:field Products … and … Product … both hit the Product model. If the model doesn't exist — or the table has no create migration and doesn't exist — it refuses up front (so you never get an add_… migration that can't run) and tells you to admin-core:make … --migration first.

If the resource has an --api channel, the new field is also added to its JsonResource and the search/sort/filter whitelists (by type) — so it shows up in the API too, not just the admin.

Scope: it handles scalar fields (string/text/number/bool/date/enum/json/slug/password/…). Relation and upload fields (foreign, belongsToMany, image, file) and system fields (@ / sku / auth — not mass-assignable, so $fillable can't track them for idempotency) need wiring it can't surgically patch (model relations, the controller's getData eager-load, the service's pivot-sync / file-storage, a trusted value-setter), so it skips them with a note — add those by regenerating with admin-core:make … --force.

Patching assumes the views/model still match the generated shape; heavily hand-edited files may need a manual touch-up (it never duplicates, so a re-run won't hurt).

Custom (non-CRUD) page (admin-core:page)

admin-core:make builds CRUD resources; for a standalone page — a Reports screen, a Settings page, a custom dashboard — use admin-core:page:

It scaffolds a thin invokable controller (app/Http/Controllers/Backend/ReportsController.php — fill in __invoke() with whatever data the page needs), a Blade view (resources/views/backend/pages/reports.blade.php, already composing <x-admin-core::page-header> + <x-admin-core::card> + a <x-admin-core::empty-state> placeholder), and a route under routes/Web/Backend/Modules/ (auto-loaded inside the admin group → admin.reports at /admin/reports). By default it also adds a sidebar menu entry and creates a view-reports permission granted to the super role — mirroring how admin-core:make wires things. Multi-word names kebab-case (admin-core:page "Sales Report" → admin.sales-report). Flags: --no-menu, --no-permission, --force.

Add --report to scaffold a data-driven read-only report instead of a blank page — the controller hands the view a $rows collection, and the view ships the report shell (a count badge, an empty-state, and a @foreach table you fill with columns):

Media library

A browsable, reusable media library. Add a media (single) or gallery (multiple) field and the generator wires the whole flow — a picker control, validation, and the save:

These are relations, not columns, so one library file can be reused across records. The owning model gets the HasMedia trait:

The library screen (browse / upload / delete) lives at admin.media.index — wired by admin-core:install (Route::adminCoreMedia()), gated by manage-media. Uploads are compressed (WebP) and stored on the configured disk; deleting a file is refused while it's still attached to a record.

Dashboard widgets

A config-driven dashboard: drop <x-admin-core::dashboard /> into your dashboard view and declare the widgets in config('admin-core.dashboard.widgets'). A widget is either a class or an inline array:

Scaffold a class widget with php artisan admin-core:make-widget Revenue --type=stat (or chart / list) — it extends StatWidget / ChartWidget / ListWidget. The $c (DashboardContext) carries the active date range: $c->scope($query) filters to it, $c->scopePrevious($query) to the previous period (for trends). A date-range toolbar and per-user drag-reorder/hide (saved per user) are on by default (dashboard.date_filter / dashboard.customizable). Wire it with Route::adminCoreDashboard() (added by admin-core:install).

Multi-portal

Need a second admin area — a merchant or vendor portal with its own login, separate from your staff admin? One command scaffolds the whole thing:

You get, all on a separate merchant auth guard (its own users, its own login):

• App\Models\Merchant (guard-scoped) + migration, a login + dashboard, and a factory + seeder;
• a merchant route group at /merchant/* (login, dashboard, and its own module folder);
• the guard + provider in config/auth.php, and the menu + super-role entries in config/admin-core.php.

Log in at /merchant/login. Then generate resources straight into the portal:

--portal=merchant routes everything to that portal — routes under /merchant with merchant.* names, permissions on the merchant guard, and the link added to the merchant sidebar. Add more portals by changing the name; single-guard apps never touch any of this.

One guard, not separate logins? If admin and merchant are the same users with different roles, skip --portal/--guard entirely and just give each area a named menu — see .

Which user is "acting" when several guards are active? admin-core resolves the acting (user, guard) pair through one place — Ngos\AdminCore\Support\ActorResolver — with a single canonical order: configured portal guards first, then the default guard. So the audit trail, media attribution, saved views, dashboard layout, and locale all agree on one identity for any authentication state; if a request is signed in on the default and a portal guard at once, the portal user is the actor. The precedence is fixed (not a per-app knob) — see docs/adr/ADR-0008-guard-precedence.md.

Notifications

--access installs an in-app notification system on the Notification Platform store: a bell in the top bar (<x-admin-core::notifications-bell />) with an unread badge and a recent-list dropdown, a full notifications page at /admin/notifications, and mark-read / mark-all-read / delete.

Send one in a single line — no message class to write — with the bundled AdminNotification, through the platform facade:

AdminNotification is a platform NotificationMessage; message maps to the stored body. Richer alerts? Implement Ngos\AdminCore\Notifications\Platform\Contracts\NotificationMessage yourself and send it the same way.

The bell renders only where the routes exist (Route::adminCoreNotifications(), added to the admin group by --access) and a user is authenticated — so it's safe everywhere. Existing installs: re-run php artisan admin-core:install --access, then php artisan migrate (admin-core's package migration creates the hybrid store). This release does not migrate old rows — if you have a pre-v4.0.0 Laravel notifications table, back it up and drop it first (the migration recreates the table); see UPGRADING.

Migrating from $user->notify(new AdminNotification(...))? The platform cutover replaced the Laravel-notification send path: call NotificationPlatform::send(new AdminNotification(...), $user) instead. AdminNotification is no longer a Laravel Notification (it has no via()/toArray()/broadcast:).

By default the bell is pull-based (updates on page load): every send() fans out to the InApp channel and lands in the platform's hybrid store, read back via Ngos\AdminCore\Models\Notification.

Optional realtime (broadcast). A peer broadcast channel can push notifications live over Laravel Echo. It is off by default — the channel binds a NullPublisher, so routing to it is a safe no-op until you enable it under config('admin-core.notifications'):

• default_channels — the channels a send() fans out to (default ['inapp']); add 'broadcast' to also push realtime by default (routing only; or opt in per send with ->channel('inapp', 'broadcast')).
• broadcast.enabled (env ADMIN_CORE_BROADCAST) — swaps the NullPublisher for the real publisher (driver: reverb | null, plus connection, event, channel_prefix; each user's private channel is <prefix>.<morphType>.<morphId>, authorized owner-only).

Broadcast publishes only after the DB transaction commits and is best-effort — the store stays the source of truth, and the fresh resources/js/echo.js + resources/js/realtime.js stubs (shipped by --access) re-sync the bell from the store on connect/reconnect, so a dropped message self-heals.

Translation & multi-language

Two features, both middleware-based (no public translate endpoint to secure) and multi-language — list every language you offer in config('admin-core.translation.locales'):

1. Per-user UI language. Each user gets their own language — one admin in English, another in Khmer. Drop the switcher in your topbar:

Each item is a plain ?setlang=km link the SetLocale middleware picks up, applies with App::setLocale(), and remembers — persisted to a users.locale column (a migration for it ships with --access, so per-user language is durable across devices out of the box; without the column it falls back to the session). The middleware auto-registers on the web group, so no route changes are needed. Use the shipped strings via __('admin-core::admin-core.actions.save'), etc. (publish/extend with --tag=admin-core-lang; for a no-access install, add the column yourself: $table->string('locale', 8)->nullable();).

2. Content auto-translate (bidirectional). For multilingual data (e.g. a product name per language), render a translatable input:

It shows one box per locale (name[en], name[km], …) plus a hidden marker. On save, the AutoTranslate middleware takes whichever language you filled and fills the empty ones for you — type Khmer, get English (and Thai, …); or type English, get the rest. It runs inside the authenticated, CSRF-protected submit, never overwrites what you typed, and caps outbound calls per request. (Store the values however you like — e.g. a JSON-cast attribute or a translatable package.)

Auto-generate a language file. Instead of translating the UI strings by hand, machine-translate them:

Then add the code to translation.locales and review the output (machine translation is a draft).

Drivers & privacy. mymemory is free and needs no key. For privacy, point libretranslate.url at a self-hosted instance so text never leaves your servers. null disables auto-translate (UI language still works). All drivers are fail-safe — if the provider is down, the original text is kept, so a save never breaks. API keys live in .env, server-side only. Machine output is a draft to review, especially for Khmer.

Lifecycle commands

Everything install injects is wrapped in // >>> admin-core:* … // <<< admin-core:* sentinels, so uninstall removes exactly what it added. Your admin-core:make-generated resources are never touched — only package-owned files (config, layout, access module, front-end kit) are purged. Add --force to skip the confirmation prompt.

UI components & theme

The --access kit ships a custom Bootstrap-5 theme (no AdminLTE) plus reusable Blade components:

• <x-admin-core::page-header title="…" description="…"> — breadcrumb + title + description, with an <x-slot:actions> for the primary button. For sub-pages, add parent + :parent-url for a Dashboard › Posts › Edit trail. Used on every index / create / edit / show.
• <x-admin-core::filter-tabs table="#x_table" :column="2" :tabs="['' => 'All', 'draft' => 'Draft']" /> — segmented tabs that drive a server-side DataTables column search (auto-added for enum fields).
• <x-admin-core::data-table id="products_table" thead="…partials.thead"> — the list-page shell: a card with an <x-slot:toolbar> (export / import / bulk-delete), the <table> your DataTable binds to, and a default slot under it (e.g. the sort panel). Every generated index uses it.
• <x-admin-core::export-menu :route="route('admin.products.export')" :fields="['name' => 'Name', …]" /> — the CSV export dropdown with a per-column checkbox picker (all checked = everything).
• <x-admin-core::import-modal :route="route('admin.products.import')" :template="…" title="Products" /> — the “Import CSV” button + modal (file upload, optional blank-template link). Gate it with @can(...).
• <x-admin-core::form-row name="price" label="Price">…control…</x-admin-core::form-row> — one labelled horizontal field row with the validation-error message wired; the generated forms emit one per field.
• <x-admin-core::editor name="description" label="…" :value="old('description', $object?->description)" min-height="250px" /> — a CKEditor 5 rich-text field (loaded from CDN, paste-from-Word cleanup); min-height sets the editable area height (CKEditor 5 otherwise collapses to ~1 line). Generated forms use it for rich text fields.
• <x-admin-core::repeater name="units" :rows="old('units', $rows)" row="…partials.unit-row" add-label="Add unit" /> — repeatable rows for a master-detail form (a variant's units, an order's line items). You supply a row partial that renders one row's inputs named with the :index it's given (e.g. name="units[{{ '$index' }}][unit_id]"), wrapping each row in [data-ac-repeater-row] with a [data-ac-repeater-remove] button. The component renders it once per existing row, plus a hidden <template> the Add button clones with a fresh unique index. Add/remove is inline JS (no build step); it posts name[i][...] arrays (indexes need not be sequential — re-index server-side).
• Live computed fields (data-ac-compute). A field whose value derives from sibling fields, updated as the user types — a line item's line_total = qty × unit_price, a qty_base = qty × conversion_factor. Put data-ac-compute="qty * unit_price" on any input (it fills + posts the value) or element (it shows the result as text); data-ac-compute-decimals="2" rounds it. Names resolve within the enclosing [data-ac-repeater-row] first (so each line computes independently), else the <form>. It's a safe arithmetic evaluator (+ - * / ( ), numbers, field names — never eval), so a money line preview is client-side while the server re-computes the stored value authoritatively (pair it with a computed column). The generated row partial ships a commented line_total example. (Cascading selects — Province → Commune narrowing — are separate: data-ac-depends on <x-admin-core::select>.)
• <x-admin-core::page-loader /> — a thin top progress bar shown during full-page navigation; drop it once in the layout. Pairs with the pre-paint sidebar-state script for a flash-free refresh.
• <x-admin-core::status :value="$object->status" /> — the soft .ac-status pill for an enum value (accepts a backed-enum instance or a string; blank renders nothing). Used in the table and show view. Semantic colours for common words: published/active → green, pending → amber, failed/cancelled → red, archived → muted; unknown values fall back to neutral.
• <x-admin-core::stat-list title="Summary" :items="[['label' => 'Refund', 'value' => '-35.00', 'suffix' => 'USD']]" /> — a label→value summary card (right-aligned tabular numbers, negatives in red, 'strong' => true for totals).
• <x-admin-core::stat-card label="Users" :count="$n" icon="bi-people" :route="route('…')" tone="1" /> — a dashboard KPI card (big number + label + icon, optionally a link; tone 1-4 picks the accent). The dashboard composes these.
• <x-admin-core::card> — a Bootstrap card with optional <x-slot:header> / <x-slot:footer>; the body is wrapped in card-body (pass :body-class="''" to drop the wrapper, e.g. a flush table). Used by the generated show/create/edit and the dashboard panels.
• <x-admin-core::form-actions submit="Create" :cancel="route('…index')" /> — the submit + cancel row at the foot of a form (pass :submit-class="config('class.button.update')" on edit). Every generated and access-module form uses it.
• <x-admin-core::alert type="warning" dismissible>…</x-admin-core::alert> — an inline contextual message with a leading icon (info/success/warning/danger; error → danger). For page-level messages; one-off flash is still handled by the layout.
• <x-admin-core::modal id="editX" title="Edit" size="lg">… <x-slot:footer>…</x-slot></x-admin-core::modal> — a reusable Bootstrap modal shell (title/body/footer slots); trigger from any data-bs-target="#editX".
• <x-admin-core::empty-state icon="bi-inbox" title="Nothing yet" message="…"><x-slot:action>…</x-slot></x-admin-core::empty-state> — a centered placeholder (icon + title + message + optional CTA) for empty lists/sections.
• <x-admin-core::skeleton :lines="3" /> / type="card" / type="table" :rows="5" :cols="4" — animated loading-skeleton placeholders to show while content loads, then swap for the real thing (shimmer is dark-mode aware).
• <x-admin-core::tabs :tabs="['profile' => 'Profile', 'security' => 'Security']"> with a <x-admin-core::tab-pane id="profile" active>…</x-admin-core::tab-pane> per id — Bootstrap content tabs for multi-section pages/forms (:pills="true" for the pill style). Distinct from filter-tabs (DataTable column search).
• <x-admin-core::avatar :src="$user->avatar_url" :name="$user->name" size="40" /> — a round photo, or a stable colour + initials circle when there's no image.
• <x-admin-core::badge tone="danger" pill>3</x-admin-core::badge> — a small count/label badge (tone → Bootstrap text-bg-*). For an enum status pill use status instead.
• Customize drawer (palette icon in the topbar): theme (light/dark/system), accent colour, density, layout (sidebar/top-nav), container (fluid/boxed) and direction (LTR/RTL) — persisted in localStorage.
• Row actions render as a kebab (⋯) menu (View / Edit / Delete). Add your own items — an "Approve" button, a "Change password" link — via the 3rd arg of actions() in the generated controller's getData(). Each item is ['label' => …, 'url' => …] plus optional icon / can (a permission that gates it) / class; they render above Edit/Delete:

Re-skin the whole thing from the --ac-* CSS tokens / SCSS variables at the top of resources/sass/app.scss.

Customising

• Stubs: php artisan vendor:publish --tag=admin-core-stubs → stubs/admin-core/ (yours win over the package's).
• DataTable partials: php artisan vendor:publish --tag=admin-core-views → resources/views/vendor/admin-core/.
• Config: edit config/admin-core.php.
• Uploads (compression + CDN): all image/file uploads go through Ngos\AdminCore\Support\Media. Set uploads.compress/max_width/quality to control WebP compression, uploads.disk to store on any filesystem (e.g. s3 + CloudFront for a CDN), and uploads.cdn_url to prepend a CDN base URL when building image URLs. All in config/admin-core.php (ADMIN_CORE_UPLOAD_DISK / ADMIN_CORE_CDN_URL).
• Base model for generated models: set generator.base_model in config/admin-core.php and every admin-core:make model extends it. Share common behaviour by use-ing traits in your base (keep the logic in traits so Role/Permission — which must extend Spatie's classes — can use them too):

Using the core directly

The web and API controllers share a common spine, so generated controllers stay thin and cross-cutting concerns have one home:

BaseService is the service-layer equivalent: it holds the model binding + the foundational query(), and find() flows through it — so a single query() override (e.g. a tenant scope) covers every list, lookup, update and delete across both the admin and the API.

For master-detail forms (a parent + repeater line items), BaseService::syncHasMany() reconciles the posted rows — update by id, create the new ones, delete the rest (null leaves the relation untouched). Pass an $attributes callback to whitelist/derive per-row columns (return null to skip a blank row):

Generated resources with a hasMany field wire this automatically.

Testing

The package ships a Pest + Orchestra Testbench suite (in-memory SQLite):

It covers the FieldSet generator (every field type, UUID, soft-deletes, uploads, m2m, factory), the Route::crud macro (registration + permission gating), the WebController flow (store/validate/update/delete/getData/bulk-delete/export), settings, soft-delete trash/restore, and the two commands end to end: admin-core:make (scaffolds valid, token-free, php -l-clean files whose migration actually runs) and admin-core:install (config/view publishing + the routes/web.php / bootstrap/app.php wiring, including idempotency). Dedicated regression guards cover the hybrid-key edit/show route links (uuid, not bigint id), enum status pills, segmented filter tabs, the consistent create/edit/show page-header, and the group-permission uuid fill. CI runs both test and analyse on PHP 8.3 + 8.4.

License

MIT