Installer Module Laravel Package

Getting Started

This package is almost never the thing you composer require directly. It arrives transitively when you install the Streams Platform skeleton (anomaly/streams-platform and the streams-platform application template). Confirm it's there with composer show anomaly/installer-module, then check composer.json for "type": "streams-addon" — the platform's addon loader registers it automatically, so you generally won't find a providers entry in config/app.php that you need to touch.

Look first at three places:

1. The service provider — src/InstallerModuleServiceProvider.php (or InstallerModuleServiceProvider under a namespaced module folder). This tells you which routes, config, and commands the module registers.
2. Config — config/installer.php (or resources/config/installer.php depending on the publish layout). This usually controls the step list, whether the installer is enabled, and where the "installed" flag is written.
3. The install state marker — a flag file under storage/app/ or a .env/config value. Knowing this file is the single most useful thing: it's what the middleware checks to decide whether to redirect you back into the wizard.

Your first real use case: stand up a fresh Streams Platform app and walk the browser wizard at the installer route (commonly /installer or /admin/installer). If you're containerizing, the more relevant first use case is the opposite — disabling the wizard entirely and reproducing its steps from an Artisan/CI script.

Implementation Patterns

Interactive bootstrap (normal path). Run the app, get redirected to the installer, step through environment checks → database credentials → admin user → completion. Let the module write .env and the install flag. Then run php artisan migrate --seed if the wizard doesn't already do it.

Scripted/CI install (the pattern worth investing in). The wizard is a UI over the same operations you can drive yourself. For Docker entrypoints and test fixtures, bypass it:

• Pre-stage a complete .env and create the install flag file before the app boots, so the middleware never engages.
• Run migrations and the platform seeders directly.
• Create the admin user via a model factory or a small post-install Artisan command.

Keep this in a committed install.sh / deploy script rather than clicking through the wizard per environment — it's the only way to get reproducible builds, and it's why most teams never touch this module after initial setup.

Guard middleware. The installer registers middleware that redirects uninstalled apps into the wizard. If you're writing your own app-level middleware, register it after this one, and never let it run in production behind a flag — the check is typically cheap and file-based, but it will short-circuit every request until the flag exists.

Custom install steps. If Streams' step-based installer is in play, the extension point is to add your own step class and register it in the installer config's step array, then drop its view into the module's resources/views. Useful for collecting app-specific settings (mailer, default site name, feature flags) during onboarding instead of a "now edit .env" README. Treat this as a light abstraction: a step is basically a form + a run()/handle() method, so keep DB writes in a separate service you can also call from your scripted installer.

Post-install hooks. Fire your seeders/domain bootstrap from an event or a command invoked at the end of the wizard, and call the same command from install.sh. That keeps the interactive and automated paths honest with each other.

Gotchas and Tips

• Permissions, permissions, permissions. The wizard writes .env, storage/, and possibly bootstrap/cache/. PHP-FPM users need write access; classic failure is a half-written .env and a "not installed" loop.
• The installed flag is sticky. If a failed wizard run creates the flag early, the app treats itself as installed and refuses to re-enter the installer. Delete the flag (and clear config) to retry.
• Config and route caching. php artisan config:cache before install will bake stale values — including the install state if it's config-backed. Always config:clear/route:clear when debugging installer behavior.
• Database assumptions. Connection tests in the wizard don't cover everything (charset, strict mode, pre-existing tables). If migrations fail post-wizard, the module's job is already done; debug from the migration output, not the installer.
• APP_KEY. The wizard generates it, but if it writes .env without a key or with an empty key, encrypted sessions/cookies break silently later. Check .env immediately after install.
• URL detection behind proxies and subdirectories. Redirects back to /installer are computed from the request; behind nginx or a subdirectory mount, configure trusted proxies or the wizard will bounce you to the wrong host.
• Small ecosystem, thin docs. With a handful of stars and no dependents, expect to read source rather than find answers. The module is small enough that the provider + config + views is the entire mental model — read all three before you customize anything.
• Don't fork for one tweak. Extension points (config steps, events, post-install commands) cover most needs; forking to change a validation message makes upgrades of the Streams Platform painful.
• Production hardening. Ensure the installer route is unreachable once deployed — even with the flag set, an exposed wizard is an attack surface; block it at the web-server level as belt-and-braces.