Admin Laravel Package

Getting Started

SleepingOwl Admin is a Laravel 4-era, config-driven CRUD interface builder. First-day setup is deliberately minimal, but you must anchor yourself in two files before touching anything else.

1. Install with Composer (this package predates modern Laravel/Composer constraints, so pin an exact commit rather than a branch alias):

   composer require sleeping-owl/admin:dev-master
   

2. Register the provider in app/config/app.php → providers: 'SleepingOwl\Admin\AdminServiceProvider'.
3. Publish config and assets (Laravel 4 syntax):

   php artisan config:publish sleeping-owl/admin
   php artisan asset:publish sleeping-owl/admin
   

4. Open the published config — app/config/packages/sleeping-owl/admin/config.php. This is the single most important file: it controls the admin title, menu, authentication gate, and the list of registered models. Read it top to bottom before writing any code.
5. Register your first model in that config's models list (e.g., App\Models\Post) and add the model's admin configuration (columns, form fields, validation rules). Start with an auto-generated form to see what the package infers from your schema, then refine.
6. Visit /admin — routes and menu entries are registered automatically from the config.

First use case: point it at one simple model (a Post or Category with a handful of scalar columns), let it auto-build the form, and confirm list/create/edit/delete work end-to-end. That single loop validates install, auth, routing, and asset publishing all at once.

Implementation Patterns

• Schema-first scaffolding: rely on the auto-form inference to get a working CRUD in minutes, then lock the form down field-by-field. This is the fastest path to a usable back office.
• Per-model config as a contract: keep columns, form fields, validation rules, and display formatting together in the model's admin config. Treat it as the single source of truth for that resource's UI.
• Relationship handling: use belongsTo/hasMany relations for select dropdowns and related columns. Always eager-load (with) the relationships referenced in list columns to avoid N+1 storms on index pages.
• Validation in the model config: rules map onto Laravel's Validator, so you get server-side enforcement for free. Mirror field names exactly, and use dot-notation for array/nested inputs.
• Menu-driven navigation: assemble the menu in the config file and order entries there — don't hard-code links in views. It keeps access and ordering in one place.
• Custom actions: extend the generated controller (or add a dedicated controller) for bulk actions, exports, or workflow buttons. Register custom field types / column renderers through the service provider when the built-ins don't fit.
• View overrides: publish the package views and edit the Blade templates for branding and layout tweaks. Prefer overriding views and custom column classes over forking the package.
• Auth gate: wire an authentication callback in the config so every admin route is protected; layer per-model restrictions on top if you have role separation.

Gotchas and Tips

• Legacy is the headline gotcha. Last release was November 2014 and it targets Laravel 4.x. It is not viable for new builds — use it only to maintain inherited admin panels. Modern Composer 2 and PHP 8 will fight the constraints; you'll likely need --no-plugins or manual installs.
• Assets are the #1 "blank page" cause. If CSS/JS don't load, the admin renders unstyled. Re-run asset:publish after any package update and verify the public path.
• Auto-forms leak schema. created_at, updated_at, soft-delete columns, and foreign keys can appear as editable fields the first time. Explicitly exclude them.
• Mass assignment bites silently. Fields not in the model's $fillable (or blocked by $guarded) won't save even though the form accepts them. Check the model before debugging the package.
• Field names must match everywhere. Form field keys, validation rules, and column definitions are stringly-typed. A typo in one place produces a silent no-op, not an error.
• Config caching: Laravel's config cache and the publish step can mask edits. Clear the cache after config changes; re-publishing overwrites your customizations, so keep a copy.
• No semver. Pin exact commits/tags in composer.json; a "latest" pull can change behavior without warning.
• Route collisions: the package registers its own /admin routes. Namespace or prefix them if your app already owns those URLs.
• Debugging order: config registered? provider booted? assets published? auth callback firing? In that order — most failures are install/config, not code.
• Extension points: custom column/field classes and service-provider bindings are the intended seams. Reach for those before patching vendor code, since upgrades are already painful.