Core Laravel Package

Getting Started

• Install and pin to the right version line. composer require adminarchitect/core then confirm composer show adminarchitect/core. v2.4.0 is the first release in the 2.x line with Laravel 10 support, so require ^2.4 explicitly if you're on L10 — floating constraints resolved against older lockfiles will happily pull v2.3.0 and fail on framework incompatibilities. L10 means PHP 8.1+ on your side too.
• Publish before you configure. php artisan vendor:publish --provider="AdminArchitect\Core\AdminServiceProvider" and then run the install command (php artisan admin:install) to create the admin user, migrations and assets. Read the published files before editing them — most day-to-day behaviour is driven from them, not from code.
• Look at these three places first, in order:
  1. config/administrator.php — the registry: title, auth guard, registered models, menu ordering, view overrides. This is the file you'll touch most.
  2. app/Admin/Resources/ — one class per model; the columns() / fields() / filters() / actions() methods are the real API surface.
  3. routes/ and php artisan route:list | grep admin — confirms the mount path and middleware stack before you go hunting for a 404.
• First use case: scaffold a single model end to end rather than building the whole panel. php artisan admin:scaffold User (or hand-write one resource class), log in at /admin, and confirm list → create → edit → delete works. Once one resource round-trips, the rest is repetition; if scaffolding a single model misbehaves, the problem is installation/config, not your resource code.
• Treat it as an internal back-office tool. It's strongest for CRUD over existing Eloquent models; don't try to model complex multi-step workflows as a resource before you've shipped a plain one.

Implementation Patterns

• One resource class per model, registered in config. The resource class is declarative: columns() defines the index table, fields() the create/edit form, filters() the search bar, actions() the row and bulk operations. Keep these methods pure declarations — no queries, no side effects.
• Centralise with a base resource. Extend a project-local App\Admin\Resources\Resource that sets shared defaults (eager loads, date formatting, permission checks) so per-model classes stay short and diffable.
• Push domain logic into services, not resources. Custom actions (approve, refund, resend invite) should be thin wrappers that call an existing application service or job. This keeps the admin reusable for a future API/CLI entry point and makes the behaviour unit-testable without HTTP.
• Override the query for eager loading. Override the resource's query/index data source to add with([...]) and withCount([...]) — list pages over related data are the single largest source of N+1 problems in admin panels, and closures in columns() that touch relations will fire per row otherwise.
• Relations: belongsTo as a select, belongsToMany as a multi-select, hasMany as a nested/embedded resource. For nested resources, verify the route parameter names line up with your foreign keys before assuming the package is broken.
• Rendering escape hatches: use closures or custom column types for computed values (status badges, links, formatted money) rather than duplicating Blade partials per model. For anything more involved, publish the views and override per-resource via the config/view mapping instead of editing vendor files.
• Authorization: set the guard in config and implement policy/gate checks per action. Two layers — route middleware for "can access the panel at all", resource-level checks for per-model permissions — because a single global check leaks between models with different sensitivity.
• Local/dev workflow: seed with factories so the index tables have realistic pagination and filter data. A panel tested only against three rows hides pagination, sorting and filter bugs entirely.
• Upgrade procedure: composer update adminarchitect/core, then diff your published config/views against the new vendor copies before republishing. Re-publish assets after the update (stale compiled JS/CSS is the most common "the update did nothing" cause).

Gotchas and Tips

• Laravel 10 support does not mean PHP 8.2-clean. L10 raises the floor to PHP 8.1, so previously-silenced deprecations (dynamic property creation, ${var} string interpolation) will now surface in logs. If your error log gets noisy right after upgrading, check whether it's your resource classes or the package internals before filing anything.
• Helper-facade dependencies. Packages of this generation often lean on laravelcollective/html (Form::, HTML::) for form building. That package is effectively unmaintained — verify Composer actually resolves it on your L10 install, and be prepared to swap heavily used macros for Blade components if it doesn't.
• Never --force the publish step on a live app. It silently overwrites your customised config and views. Publish to a temp path (--path=) and diff, or copy the vendor file and merge by hand.
• Config strings are resolved as class names. "Class not found" errors from the panel are almost always a typo'd or namespaced-wrong model/resource entry in administrator.php, not a missing file. Check the config entry, then php artisan route:list.
• Caches lie. After editing a resource class or the config, clear config and view caches (php artisan config:clear && php artisan view:clear, plus any package-specific cache command you find in the service provider). Stale menus and unchanged columns after an edit are cache, not a bug — verify it once so you stop debugging it repeatedly.
• $fillable gates your form silently. Fields declared in fields() but absent from the model's $fillable are dropped without an error, producing "the form saves but the field is empty". Audit resource fields against $fillable when adding new ones.
• Validation rules: on update, unique rules need the record ID ignored, and sometimes/nullable must match the field's actual optionality — otherwise edit forms fail for records created before a field existed.
• File uploads need php artisan storage:link, an explicitly configured disk, and matching visibility settings; failures are quiet (field renders, nothing persists) rather than loud.
• Column types / doctrine: if you use column-modifying migrations alongside the package's tables, older Laravel versions require doctrine/dbal. Confirm it's installed rather than guessing at a migration failure.
• Debugging order that actually works: (1) is the route registered? (2) is the model resolvable from config? (3) is the resource class autoloaded (composer dump-autoload)? (4) are caches clear? (5) is it a policy denial rendering as a blank page? That sequence resolves the large majority of "the admin is broken" reports.
• Extension point to prefer: custom column/field/action classes and per-resource view overrides. Avoid patching vendor files or subclassing deep internals — v2.x patch releases have historically changed internals without ceremony, and a Laravel 10 support bump is exactly the kind of release that touches request/response plumbing underneath you.