README

A production-ready, web-based step-by-step installer for Laravel applications designed for shared hosting and VPS environments. No CLI required—everything runs from the browser.

Features

✅ Web-based wizard – No SSH/CLI access needed (perfect for shared hosting)
✅ Server requirements check – Validates PHP version and required extensions
✅ Database configuration – Test connection, write to .env directly
✅ Auto-migration – Run migrations on finalization
✅ Auto key generation – Generate application key automatically
✅ Clean & simple UI – Responsive design works on any device
✅ Publishable assets – Customize styling and config per project
✅ Laravel 11/12+ compatible – Works with current and future Laravel versions
✅ No external dependencies – Uses only Laravel core facades

Installation

1. Require the package via Composer

composer require nazmulcreator/laravel-web-installer

2. Publish assets & config (optional, but recommended)

php artisan vendor:publish --tag=installer-config
php artisan vendor:publish --tag=installer-assets

This allows you to customize the installer configuration and styling per project.

Usage

Quick Start

After installation, navigate to your application URL:

https://your-domain.com/install

The installer will guide you through:

Welcome screen – Introduction to the wizard
Requirements check – Verify PHP version and extensions
Database setup – Enter MySQL credentials and test connection
Finalization – Run migrations, generate key, clear cache

Step-by-Step Walkthrough

Step 1: Welcome

User reads intro information
Clicks "Start Installation" to proceed

Step 2: Server Requirements

Displays PHP version and extension status
Shows checkmarks (✔) for present extensions
Shows crosses (✖) for missing extensions
Disables "Next" button if PHP < 8.2

Step 3: Database Configuration

User enters MySQL host, port, database, username, password
System validates connection
Credentials are written to .env file automatically
If connection fails, error message appears with retry option

Step 4: Installation Complete

Migrations run automatically
Application key is generated
Cache is cleared
User sees success page

Configuration

The installer uses a configuration file at config/installer.php:

return [
    'steps' => [
        'welcome',
        'requirements',
        'database',
        'finish',
    ],
    'temp_connection' => 'installer',
];

Customization Options

Change the route prefix – Rename installer URL:

// In config/installer.php or via environment:
'route_prefix' => 'setup',  // Now accessible at /setup

Add custom steps – Extend the controller and add routes:
1. Create a new controller method
2. Add a route in routes/web.php
3. Add the step name to config/installer.php

Customize styling – Edit the published CSS:

php artisan vendor:publish --tag=installer-assets --force
# Edit: public/vendor/laravel-web-installer/installer.css

Customize views – Publish and edit Blade templates:

# Manually copy views from vendor to resources/views/vendor/installer
# Then customize as needed

Security Considerations

After Installation

Important: Remove or disable the installer after successful setup:

Option 1: Change the route prefix

Edit config/installer.php:

'route_prefix' => 'very-secret-path-12345',

Option 2: Remove the package entirely

composer remove nazmulcreator/laravel-web-installer

Option 3: Disable via middleware

Add authentication or IP whitelist middleware to installer routes.

Environment Protection

The .env file is written directly (not committed to version control)
Database credentials are only stored in .env (not in database)
Session-based progress tracking (volatile on shared hosting)
CSRF token protection on all forms

File Structure

laravel-web-installer/
├── composer.json
├── src/
│  ├── LaravelWebInstallerServiceProvider.php
│  ├── Http/
│  │  ├── Controllers/
│  │  │  ├── InstallController.php
│  │  │  └── FinalizeController.php
│  │  └── Requests/
│  │     └── DatabaseSetupRequest.php
│  ├── Models/
│  │  └── Installation.php
│  └── Resources/
│     ├── views/
│     │  ├── layout.blade.php
│     │  ├── welcome.blade.php
│     │  ├── requirements.blade.php
│     │  ├── database.blade.php
│     │  └── finish.blade.php
│     └── assets/
│        └── installer.css
├── routes/
│  └── web.php
├── config/
│  └── installer.php
└── tests/
   └── Feature/InstallTest.php

API Reference

Routes

Route	Method	Name	Description
`/install`	GET	`installer.welcome`	Welcome page
`/install/requirements`	GET	`installer.requirements`	Requirements check
`/install/database`	GET	`installer.database`	Database form
`/install/database`	POST	`installer.database.post`	Process DB credentials
`/install/finish`	POST	`installer.finish`	Finalize installation

Controllers

InstallController

showWelcome() – Display welcome view
showRequirements() – Verify PHP/extensions and display results
showDatabase() – Show database setup form
processDatabase(DatabaseSetupRequest $request) – Validate and save DB credentials

FinalizeController

__invoke(Request $request) – Run migrations, key generation, cache clear

Form Request

DatabaseSetupRequest

Validates:

host – Required string
port – Required numeric
database – Required string
username – Required string
password – Nullable string

Testing

Run the feature tests:

php artisan test tests/Feature/InstallTest.php

Test Coverage

installer_shows_welcome_page() – Verifies welcome route returns 200
it_validates_database_form() – Verifies form validation works

Troubleshooting

"Database not configured yet" error

Ensure you completed the database setup step
Check session is enabled (web middleware)
Verify cookies are allowed in browser

".env file not found" error

Ensure .env.example exists in project root
Or manually create an empty .env file

"Connection failed" on database step

Verify MySQL credentials are correct
Check MySQL service is running
Ensure host/port are accessible from server
Verify username has necessary permissions

Requirements page says extensions missing

Install missing PHP extensions via your hosting control panel
Or contact your hosting provider
Restart PHP-FPM/Apache after installation

How It Works

No CLI Required

Instead of using Artisan commands via CLI:

# Traditional (requires SSH)
php artisan migrate
php artisan key:generate
php artisan cache:clear

The installer runs Artisan directly from PHP:

Artisan::call('migrate', ['--force' => true]);
Artisan::call('key:generate', ['--force' => true]);
Artisan::call('cache:clear');

.env File Writing

The installer modifies .env directly without CLI:

// Reads current .env
$content = file_get_contents($envPath);

// Updates or appends values
foreach ($values as $key => $val) {
    $pattern = "/^{$key}=.*$/m";
    if (preg_match($pattern, $content)) {
        $content = preg_replace($pattern, "{$key}={$val}", $content);
    } else {
        $content .= PHP_EOL . "{$key}={$val}";
    }
}

// Writes updated .env
file_put_contents($envPath, $content);

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Submit a pull request

License

MIT License. See LICENSE file for details.

Support

For issues, questions, or suggestions:

Open an issue on GitHub
Check existing documentation above
Review the source code comments

Author

Nazmul Hossain

Email: you@example.com

Enjoy hassle-free Laravel deployments on shared hosting! 🚀

nazmulcreator / laravel-web-installer

Maintainers

Package info

Statistics

Security