Installer Laravel Package

Getting Started

• Require the package in a fresh or near-fresh Laravel app: composer require leanadmin/installer. It's a scaffold package, not a runtime dependency — treat it as a dev/setup tool you run once per environment.
• Run the installer with the package's Artisan command (confirm the exact signature with php artisan list | grep lean — the whole point of the package is a single command). One run should publish config/views/assets, register the service provider and routes, run migrations, and seed a default admin user.
• Look first at three things, in this order:
  1. The published config file (config/lean*.php) — this is where route prefix, middleware/guard, and token settings live. Everything you'll tune day-to-day is here.
  2. The seeded admin user — the installer prints credentials or writes them somewhere; capture them immediately and change the password.
  3. The service provider / routes file it registers — this is where the admin panel is wired in, and where you'll add your own middleware.
• First use case: scaffold a new Laravel app, run the installer, log into the admin panel at the configured prefix (typically /admin), change the seeded password, and commit the published config plus the generated composer.json diff. That gives you a reproducible baseline.
• As of v0.2.0, the token generated for the seeded admin now carries the project name in its default name. If you issue tokens from the admin panel, generate one right after install and inspect the stored name so your logs, UI lists, and tests reflect the new format.

composer require leanadmin/installer
php artisan lean:install   # verify signature via `php artisan list`
php artisan migrate

Implementation Patterns

• Fresh-project bootstrap. Add the install command to your project's own setup script (make setup, a Composer post-create-project-cmd hook, or an onboarding README step). The installer is designed for exactly this — do the boring publishing/migrating/seeding once and move on.
• Ephemeral dev/CI environments. In Docker entrypoints or CI jobs, chain php artisan migrate --force (or let the installer do it) then run your seeders. Keep the installer out of production deploys — run it once, commit the published artifacts, and let normal migrations take over from there.
• Customize after publishing, never in vendor/. Publish once, then edit the published config/views/routes. If you find yourself editing the package's stubs, you've lost the upgrade path. For heavier changes, override the published service provider bindings rather than forking.
• Config-first customization. Route prefix, middleware stack, admin guard, and token naming all belong in the published config. Changing them there keeps upgrades painless; string-patching routes or middleware in Kernel.php doesn't.
• Token naming (v0.2.0+). The seeded admin token now includes the project name. In multi-app or multi-tenant setups this is genuinely useful — staging vs. prod tokens are distinguishable at a glance in the token list. Reserve the default project-prefixed name for user-initiated tokens and pass explicit names ('ci-deploy', 'mobile-ios') when you need deterministic identification.
• Scoping beats naming. Attach abilities/scopes at token creation and enforce them via middleware or policies. Don't write authorization logic that keys off the token name — names are labels, abilities are the security boundary.
• Rotation/revocation UI. Ship a "list tokens / revoke token" screen in your admin panel so users self-serve. Match on token ID, not name.
• Testing. Use the package's acting-as helper or actingAs($admin) for authenticated requests. Add an explicit assertion on the seeded admin's default token name so the v0.2.0 behavior is pinned in tests rather than assumed.

Gotchas and Tips

• Not reliably idempotent. Re-running the install command can fail on existing migrations, overwrite published files, or duplicate the seeded admin. On second runs, use --force only when you intend to republish, and guard the install step in setup scripts (e.g., "run only if config/lean*.php is absent").
• Seeded credentials are a liability. Never commit the generated admin password, and force a password change on first login. If the installer prints credentials to the console, they'll also land in CI logs — rotate or disable seeding in automated environments.
• Snapshots and fixtures will break on v0.2.0. Any assertion on an exact default token name (JSON snapshots, assertDatabaseHas(['name' => 'cli']), seeded fixtures) needs updating. This is the single most likely upgrade breakage.
• Treat token names as display-only. Don't parse the project name back out — app.name is environment-specific and overridable. If you need provenance, store it in a dedicated column or token metadata.
• Check the token name column length. Project name + separator + base name can overflow a tight custom migration. Verify the schema before rolling out to long app names.
• Config cache bites. After changing the app name, route prefix, or any naming config, run php artisan config:clear (or config:cache). Stale cached config is the usual reason new settings don't appear.
• Laravel version compatibility checks. The installer validates the target Laravel version. If it bails, check your laravel/framework constraint before assuming a package bug — upgrade Laravel first.
• Asset publishing needs a force flag to refresh. If published views/assets look stale after a package update, republish with --force and diff before committing.
• Route collisions. If your app already exposes an admin route or guard with the same name/prefix, the installer's registration will clash. Rename the prefix in config before running install in an existing app.
• Debugging order when login fails post-install: (1) confirm the service provider and admin guard/middleware are registered, (2) confirm the admin row actually exists in the users table, (3) confirm the seeded password wasn't mangled by a custom user model. A valid-looking setup that fails almost always means a guard or registration mismatch, not a token/naming issue.
• Never log plaintext tokens. The name is safe to log; the plaintext token is returned once at creation and shouldn't be re-fetched. Same rule applies to the installer's seeded credentials.
• Extension point: override token naming, route prefix, and middleware in the published config — or subclass the token model/service — rather than string-mangling at every createToken() call site. One override beats a dozen drifted arguments.