Laravel Installer Laravel Package

Getting Started

1. Install the package — composer require froiden/laravel-installer. Laravel auto-discovers Froiden\LaravelInstaller\Providers\LaravelInstallerServiceProvider via extra.laravel in the package composer.json; if you're on a Laravel version without package discovery, register it manually in config/app.php.
2. Publish config and views — php artisan vendor:publish --provider="Froiden\LaravelInstaller\Providers\LaravelInstallerServiceProvider". This gives you config/installer.php and the Blade views you'll override.
3. Look first at config/installer.php — it's the control surface for the whole flow: the PHP/extension requirements list, writable-directory permission checks, route prefix and middleware, the post-install redirect target, and app/branding name. Almost every "how do I change X" question is answered here.
4. Register the guard middleware — the package ships a middleware that redirects uninstalled apps to the installer. Add it to app/Http/Kernel.php (or bootstrap/app.php on Laravel 11+) so GET / sends a fresh deployment to /install instead of a stack trace.
5. First use case — shipping a distributable Laravel product (SaaS script, CRM, ERP) to users who have no SSH/Composer access. They hit /install, walk through requirements → permissions → database credentials → migrate/seed → done, and land on your login screen. Your job is to make that path boring and safe.

Implementation Patterns

• The canonical wizard flow is requirements → permissions → environment → database → finish. Each step is a controller action plus a Blade view; the intermediate state lives in the session, and the environment step writes your .env keys (DB host, name, user, password, app URL).
• Environment step — treat it as a form-to-.env mapper. Keep an .env.example in the repo that mirrors exactly the keys the installer writes, and validate the inputs before they hit the file writer (see gotchas).
• Database step — the package calls Artisan::call('migrate') and optionally db:seed. If your product has required seeders or a demo-data toggle, wire that into the view and controller rather than telling users to run Artisan later.
• License / purchase-code step — commercial Froiden products typically insert a verification step here. If you're selling the app, extend the flow with your own controller action and view that validates against your license API before allowing the final step.
• Completion handshake — after success, write the "installed" marker (file or config flag), clear cached config/routes/views, and redirect to installer.redirect_to (usually /login or /admin).
• Middleware gating — use the shipped middleware to redirect to /install when the marker is absent. Once installed, either disable the routes entirely or add an "already installed" guard so re-running the wizard is impossible.
• Customization strategy — publish views and override them; extend config/installer.php with your own requirements entries (e.g. bcmath, intl); add a custom requirement class or closure rather than editing vendor code.
• Integration with onboarding — pair the installer with a post-install "welcome" screen and a default admin account created during seeding, so the first login is immediate.

Gotchas and Tips

• .env write permissions — the PHP-FPM user must own (or be group-writable on) .env. A passing permissions step followed by a silent failure usually means the web user differs from the CLI user who created the file.
• Never leave /install open after success. The environment step can overwrite DB credentials; anyone hitting it post-install can brick or hijack the app. Gate on the installed marker and consider removing the package from production builds.
• Cache staleness after env writes — the installer writes .env but Laravel may still serve cached config. Run config:clear, route:clear, and cache:clear at the end of the flow, or the app boots with the old connection.
• .env quoting — values containing spaces, #, or = need quoting. The package's writer does not always sanitize; validate DB names/passwords and reject characters that would corrupt the file.
• APP_KEY — if the installer doesn't generate one for you, sessions and encrypted cookies will fail with a cryptic error. Generate the key as part of the completion step.
• Shared-host restrictions — exec/proc_open are often disabled, so any shell-based migrate call fails silently. Prefer Artisan::call('migrate') from PHP.
• Version skew — check the package composer.json constraints against your Laravel version. On Laravel 11+ middleware registration moved to bootstrap/app.php, and older installer versions assume Kernel.php.
• Debugging blank screens — a failed migration during the wizard often renders an empty page rather than an exception. Tail storage/logs/laravel.log while stepping through, and check storage/framework/ is writable.
• Wrong redirect_to — the most common support ticket is landing on a 404 after "Installation complete." Verify the path resolves to an actual route in your app.
• Extension points to prefer — published views, config/installer.php, the middleware, and custom requirement classes. Avoid editing vendor/froiden/laravel-installer directly; you lose the changes on the next composer update.