Download the PHP package softcortex/magic-installer without Composer

Laravel Envato Installer Wizard

A professional WordPress-like installer wizard for Laravel 11+ applications with built-in Envato purchase code verification. Perfect for CodeCanyon products and commercial Laravel applications.

✨ Features

• 🎨 Beautiful UI - Clean, modern interface with TailwindCSS
• 🔐 Envato Integration - Real Envato API v3 purchase code verification with dev mode
• ✅ Requirements Check - Automatic PHP version, extensions, and permissions validation
• 🗄️ Database Setup - Interactive database configuration with real-time connection testing
• 🔄 Auto Migration - Automatic database migration during installation
• 👤 Admin Creation - Secure admin account setup with smart role assignment (supports Spatie Permission)
• 🔒 Security First - Stateless forms, secure session handling, password hashing
• 🚀 One-Click Install - Complete installation in 7 steps
• 🔓 Recovery Command - Unlock installer if needed
• 🧪 Property Testing - 39,000+ assertions with property-based tests
• 🔧 Step Validation - Prevents accessing steps out of order
• 💾 File-First Storage - Works before database setup

📋 Requirements

• PHP 8.2 or higher
• Laravel 11 or 12
• Composer
• Writable storage/app directory
• MySQL/PostgreSQL/SQLite database

📦 Installation

Install the package via Composer:

Note: The installer uses file-based storage (storage/app/.installed and storage/app/installer-settings.json) and does NOT require database setup before running. This means it works immediately after composer require without any database configuration.

Publish Assets (Recommended Before Installation)

For developers distributing this as part of their product:

1. Publish the .env.example file (includes pre-configured Envato settings):

2. Edit the published .env.example in your project root and add your Envato credentials:

3. The installer will use your customized .env.example as the template when creating .env during installation.

Why publish .env.example? The installer prioritizes the project's .env.example over the package's version. This allows you to pre-configure Envato tokens and other settings for your end users.

Optional: Publish other assets

Publish the configuration file:

Optionally, publish the views for customization:

Optionally, publish the settings table migration (if you want to customize it before installation):

Note: Publishing the migration is optional. The installer automatically creates the settings table during Step 4 (Database configuration) using Laravel's Schema builder.

Or publish everything at once:

⚙️ Configuration

Storage

The installer uses file-based storage to avoid database dependency issues:

• Installation Status: storage/app/.installed
• Settings: storage/app/installer-settings.json

This approach ensures the installer works before database configuration, eliminating the chicken-and-egg problem.

1. Envato Personal Token Setup

To enable Envato purchase code verification:

1. Visit https://build.envato.com/create-token/
2. Create a token with these permissions:
   • ✅ View and search Envato sites
   • ✅ View the user's account username
3. Add to your .env file:

Development Mode

For development/testing without real Envato API calls:

Then use the test purchase code: dev-test-code-12345678-1234

Skip License Step

To completely skip license verification:

2. Middleware Setup

The installer automatically registers:

1. Custom installer middleware group (no EncryptCookies/StartSession) - Allows installation before APP_KEY exists
2. Global EnsureInstalled middleware - Redirects all routes to /install until installation completes

Key Architecture:

• Installer routes use custom middleware without session/cookie encryption
• All forms are stateless (no CSRF tokens, no old() helpers)
• Database drivers (session, cache, queue) switch to database automatically after installation

No manual middleware configuration required - works out of the box!

3. Configuration Options

Customize config/installer.php:

🚀 Usage

Installation Wizard

1. Navigate to /install in your browser
2. Follow the 7-step wizard:
   • Step 1: Welcome - Introduction and getting started
   • Step 2: App Config - Set application name, URL, timezone, locale (creates .env + APP_KEY)
   • Step 3: Requirements - PHP version, extensions, directory permissions check
   • Step 4: Database - Database configuration, connection test, runs migrations
   • Step 5: License - Purchase code verification (optional, can be disabled)
   • Step 6: Admin - Create administrator account with role assignment
   • Step 7: Finalize - Switch to database drivers, sync data, lock installer

Step Validation:

• Each step validates that previous steps are completed
• Attempting to access /install/admin before database setup redirects to /install/database
• Ensures proper installation sequence and prevents errors

Real-Time Validation

• Database Test Connection - Verify credentials before saving
• License Verification - Validate purchase code against Envato API before continuing
• Requirements Check - Live status of PHP version, extensions, and permissions

Purchase Code Format

Envato purchase codes must be in UUID format:

The installer:

• ✅ Validates against Envato API in real-time
• ✅ Stores only SHA-256 hash (never the actual code)
• ✅ Retrieves license info: item name, buyer, dates, support expiry

Unlock Installer

Re-run the installer if needed:

Force unlock without confirmation:

🎨 Customization

Views

Publish and modify views:

Views location: resources/views/vendor/installer/

Routes

Change the installer URL prefix in config/installer.php:

Styling

The installer uses TailwindCSS. Customize by:

1. Publishing views
2. Modifying Tailwind classes
3. Adding custom CSS to the layout

🔒 Security

Best Practices

• ✅ Always use HTTPS in production
• ✅ Keep Envato Personal Token secure (never commit to Git)
• ✅ Use strong admin passwords
• ✅ Run installer:unlock only when necessary

Data Storage

File-based storage:

• ✅ Installation status in storage/app/.installed
• ✅ Settings in storage/app/installer-settings.json
• ✅ SHA-256 hash of purchase code
• ✅ License metadata (item name, buyer, dates)

Never stored:

• ❌ Envato Personal Token
• ❌ Plain text purchase codes

🏗️ Architecture

Stateless Forms

The installer uses stateless forms before APP_KEY generation:

• No CSRF tokens on installer routes
• No old() helpers or $errors variables
• Controllers return views directly with error messages
• Form values preserved via explicit $credentials or $formData variables

File-First Storage

Installation state stored in files, not database:

• storage/app/.installed - Installation lock file
• storage/app/installer-settings.json - Step progress and settings
• Database sync happens in Step 7 (Finalize) to settings table

Why? Avoids chicken-and-egg problem - installer must work before database exists!

Migration Timing

Migrations run in Step 4 (Database), not Step 7:

• Creates settings table with category and changeable columns
• Creates users table before Step 6 (Admin creation)
• Uses Laravel Schema builder for database-agnostic compatibility

Smart Admin Role Assignment

Automatically detects and assigns admin role:

1. Checks for role or roles column in users table
2. Detects Spatie Permission package (HasRoles trait)
3. Creates role if missing (when create_role_if_missing=true)
4. Assigns appropriate role to admin user

🐛 Troubleshooting

🧪 Testing

Run the test suite:

Run specific test types:

📚 API Reference

LicenseService

InstallerService

📝 Changelog

See CHANGELOG.md for recent changes.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

🔐 Security

Report security vulnerabilities via our security policy.

👥 Credits

• Ouhssini
• All Contributors

📄 License

MIT License. See LICENSE.md for details.