Axeadmin Laravel Laravel Package

Getting Started

1. Install the package into an existing Laravel app:

   composer require kphcdr/axeadmin-laravel
   

   Because this package targets "existing projects," keep it in require (not require-dev) and pin a compatible Laravel version in composer.json before running.

2. Publish and migrate. Immediately look at what the package ships by running:

   php artisan vendor:publish --provider="Kphcdr\\AxeAdmin\\AxeAdminServiceProvider"
   php artisan migrate
   

   The published config/axeadmin.php (or similarly named file) and its migration set are the first two places to read — they define the admin tables (users, menus, roles/permissions, and possibly resource registrations) and the route prefix/auth guard.

3. Read the source, not just the README. With ~50 stars and a Chinese-language description, English docs are thin. Open the package's src/ directory and inspect:

   • The ServiceProvider (what it loads, publishes, and registers)
   • The route file(s) (prefix, middleware, auth guard)
   • The controllers (to see the CRUD/base patterns it expects you to extend)

4. First use case. The intended win is scaffolding a working admin for an existing Eloquent model — a menu page, list/detail views, and CRUD wiring — without rebuilding auth/layout. Start by wiring one simple model (e.g. Post) end-to-end, confirm list + create + edit + delete work through the admin UI, then replicate.

5. Log in. Check the config for the admin route prefix (commonly /admin) and how the initial admin user is seeded (a seeder, an artisan command, or a default credential in the README). Change any default password before exposing the app.

Implementation Patterns

• Extend, don't fork. Typical usage is registering your own resources via the package's base controller/manager class (often something like AxeAdmin::resource() or an AdminController you subclass) rather than editing vendor files. Keep all customizations in app/Admin/ or your own controllers so composer update stays safe.

• Model-to-admin mapping. Wire existing models as admin resources by declaring: the model class, the list columns, the editable form fields, and validation rules. This is the core daily workflow — one resource definition per model, kept alongside the model (or in a dedicated admin namespace).

• Route + middleware composition. Integrate by nesting admin routes under your existing web middleware group but with the package's admin guard/prefix. If you already have an admin guard in config/auth.php, point the package at it; otherwise create one so admin sessions don't collide with end-user sessions.

• Menu/permission wiring as configuration. Treat menu entries and role/permission assignments as data (seeded or config-driven) so new admin screens appear in the sidebar automatically when a resource is registered. This keeps onboarding new CRUD screens to a single file change.

• Blade/layout integration. If the package renders Blade layouts, publish its views and override only the pieces you need (header, menu, branding) via a view namespace override, rather than editing the vendor view directory.

• CI/local parity. Add the publish + migrate steps to your setup script. Since it touches existing projects, run it locally against a real copy of the project schema first; treat the admin migration like any other migration and review it before pushing.

Gotchas and Tips

• Documentation is primarily Chinese. Budget time for translating README/code comments. Prefer reading the actual source over the README when they disagree — the source is the source of truth.

• Version/lock sensitivity. At ~50 stars this is a small-maintenance package. Pin the exact version and check the package's supported Laravel/PHP constraints against your app before composer require. Test upgrades in a branch; the risk of an abandoned or stale tag is real.

• Route and asset conflicts. Publishing views/assets can overwrite public/ files or collide with your app's existing /admin routes. Run php artisan route:list before and after install to diff routes, and verify no duplicate prefix.

• Auth guard collisions. If your app already has web auth, the admin package's default guard can cause "logged in but unauthorized" loops. Explicitly set the guard in the config and confirm the auth middleware in the package's route group references it.

• Migrations against existing data. Admin tables are additive, but if the package expects a users table you may need to seed an admin record manually. After publish/migrate, check config/app.php auto-discovery, clear caches (php artisan config:clear route:clear view:clear) — stale route/cache files are the usual cause of "route not found" after install.

• Debugging extension points. When something fails to render, check in this order: (1) service provider loaded (auto-discovery enabled or manual registration), (2) config file published and cached correctly, (3) views published and namespace resolves, (4) permissions/roles seeded for the logged-in admin. Use php artisan tinker to inspect the admin user's roles/permissions.

• Keep customization out of vendor/. Because the package is small and likely slow to patch, implement overrides through published config, published views, and your own subclasses — never edit files under vendor/kphcdr. That way future composer update (or an eventual fork) is painless.

• Consider exit strategy. Given the limited ecosystem around it, keep the admin as a thin shell over your real domain logic (services/actions), so if the package is unmaintained you can replace the presentation layer without rewriting business rules.