Installer Laravel Package

Getting Started

The installer is a scaffolding tool, not a runtime dependency — you touch it once per project (or once per environment rebuild), then it disappears from your day-to-day work. Treat it like laravel new with a CMS overlay.

Minimal path:

1. Read the README first — at 11 stars and a single 2022 release, the README is the documentation. Confirm the exact command signature (trov:install, install:trov, or a standalone vendor/bin/trov binary) before wiring anything into scripts.
2. Install into a fresh Laravel skeleton matching the installer's supported version range (see Gotchas — likely Laravel 9 given the release date).
3. Run the install command in an empty project with a configured .env (database, app URL, mail).
4. Verify end state: migrations applied, admin user seeded, storage linked, assets published.

First real use case: standing up a working TrovCMS admin panel locally in under five minutes so you can evaluate whether the CMS fits before committing to it. Everything else (content modelling, theming, custom modules) happens after the installer has done its job.

Implementation Patterns

Fresh-project bootstrap (local dev). Run the installer immediately after composer create-project and before touching any application code. This gives you a clean baseline commit — git add -A && git commit -m "post-install baseline" — so you can diff against it later when you need to know which files the installer generated vs. which you wrote.

Environment promotion. If the installer supports non-interactive flags (--no-interaction, --force, --seed), wrap it in a shell script used by both local setup and CI. Keep secrets out of the installer invocation — feed them via .env or environment variables, never as CLI arguments that end up in shell history or process listings.

Idempotent re-runs for CI. CI pipelines are where installers break. Prefer one of two approaches:

• Run the installer once against a seeded SQLite/MySQL fixture and cache the resulting schema dump (php artisan schema:dump), then load that dump in CI instead of re-running the installer.
• Or run the installer against a scratch DB on every build and assert the migrations table ends in an expected state.

Integration with an existing app. If you're adding TrovCMS to an existing Laravel project rather than greenfield, treat the installer as inspiration rather than a black box: read what it publishes and migrates, then cherry-pick. Blindly running an installer into a populated app is the fastest way to lose a Saturday to a migration collision.

Composition over the installer. Once installed, the real day-to-day workflow is artisan commands, config files, and published assets — not the installer. Build your own thin wrapper commands (app:setup-admin, app:seed-demo) so future team members don't need to re-run the original installer to get a working environment.

Gotchas and Tips

Stale package, pinned ecosystem. Last release was August 2022. That's roughly Laravel 9 territory. Expect PHP 8.0/8.1 constraints and be prepared for composer require to conflict with newer Laravel or PHP 8.3+. If you hit a wall, fork it, bump constraints in composer.json, and run the test suite — installers are usually thin enough to patch.

Order of operations. Almost every installer failure traces to the environment not being ready: .env missing, APP_KEY unset, database not created, no write permission on storage/ and bootstrap/cache/. Before re-running, run php artisan about and php artisan config:clear to confirm the app boots at all.

Permission and ownership. Publishing assets and writing to storage/ as the wrong user produces files root will later refuse to touch. If you run the installer inside Docker, either run it as the host UID or chown -R afterward — otherwise php artisan serve and file-based caches will fail with opaque errors.

Idempotency is not guaranteed. Most installers assume a virgin app. Re-running after a partial failure can duplicate seed data, re-publish assets over your edits, or fail on "table already exists." If a run fails mid-way, the safest recovery is a fresh checkout and a clean database — not a retry. Keep a snapshot (VM, Docker volume, or DB dump) before the first run.

Debugging. Run with maximum verbosity and no interaction to see exactly which step fails:

php artisan trov:install -vvv --no-interaction

Laravel's exception handler will still swallow the stack trace in some installer flows; if the error is opaque, wrap the invocation in try/catch in a php artisan tinker session or add a temporary Log::debug() around the failing publish/migrate call.

Extension point: the command class itself. Installer commands are typically a handful of services resolved from the container — publishing, migrating, seeding. If you need to change behaviour (custom admin credentials, extra seed data, skipping a publish step), the cleanest route is a subclass of the installer command registered in your app's Console/Kernel, overriding the relevant method. That keeps you upgrade-safe if you later pull a patched fork.

Verify you actually need it. If TrovCMS publishes most of its config and assets via standard Laravel package mechanics, you may get further by manually requiring the core package, running php artisan vendor:publish, and writing your own migrate/db:seed steps. The installer's real value is the ordering — if you're comfortable with that ordering, you don't strictly need the tool.