Spark Installer Laravel Package

Getting Started

Minimal Steps to Begin

1. Install the Package Clone the repository and run:

   git clone https://github.com/laravel/spark-installer.git
   cd spark-installer
   composer install
   

   Add the cloned directory to your system PATH to use the spark CLI globally.

2. Register Your License Purchase a Spark license from Laravel Spark and register it:

   spark register YOUR_API_TOKEN
   

   Verify registration with:

   spark whoami
   

3. Create Your First Project Scaffold a new Spark project:

   spark new my-spark-app
   cd my-spark-app
   

   Run migrations and start the dev server:

   php artisan migrate
   php artisan serve
   

First Use Case: Quick Starter for SaaS

Use spark new to bootstrap a SaaS project with pre-configured:

• Billing (Stripe integration)
• Team management
• User subscriptions
• Admin dashboard
• Frontend (Vue.js by default)

Implementation Patterns

Workflow: Project Creation & Customization

1. Generate a Project

   spark new my-app --team  # Includes team features
   spark new my-app --stripe # Enables Stripe billing
   

   Flags like --team, --stripe, and --vue customize the scaffold.

2. Post-Creation Setup

   • Environment Configuration: Edit .env for app URL, billing keys, and mail settings.
   • Database: Run migrations and seeders:

     php artisan migrate --seed
     

   • Frontend: Build assets (if using Vue):

     npm install && npm run dev
     

3. Team Development

   • Share the spark CLI across a team by storing it in a shared directory (e.g., /usr/local/spark).
   • Use spark new with consistent flags to maintain uniformity.

4. Integration with Existing Laravel Apps

   • Copy Spark’s config/spark.php and resources/views/vendor/spark into your project.
   • Manually merge Spark’s migrations (database/migrations) if needed.
   • Use Spark’s service providers (SparkServiceProvider) as a reference for features like billing or teams.

Key Integration Tips

• API Tokens: Store the Spark API token in .env (SPARK_LICENSE) for automated deployments.
• Customization: Override Spark’s views in resources/views/vendor/spark without modifying the original files.
• Testing: Use Spark’s built-in test helpers (e.g., createTeam(), createSubscription()) in PHPUnit tests.

Gotchas and Tips

Pitfalls

1. License Registration

   • Error: spark new fails with License not registered. Fix: Run spark register again or check your API token from Spark’s dashboard.
   • Tip: Register the license on a machine with internet access, then copy the spark binary to offline machines.

2. Outdated Dependencies

   • Spark Installer is last updated in 2020. Ensure your Laravel version (LTS 6.x/7.x/8.x) is compatible.
   • Workaround: Manually update dependencies in composer.json if needed (e.g., laravel/framework to ^8.0).

3. Frontend Conflicts

   • Issue: Vue/NPM build fails due to version mismatches. Fix: Delete node_modules and package-lock.json, then run npm install with --force if necessary.

4. Database Migrations

   • Gotcha: Spark’s migrations assume a mysql database. For PostgreSQL/SQLite, edit config/database.php before running migrate.
   • Tip: Use php artisan spark:install to re-run Spark’s setup if migrations are skipped.

5. Custom Domains

   • Spark defaults to localhost. For production, update:
     • .env (APP_URL=https://yourdomain.com)
     • config/spark.php (domain and secure settings).

Debugging

• Verbose Output: Use spark new --verbose to debug project generation.
• Logs: Check storage/logs/laravel.log for Spark-related errors.
• Artisan Commands: Spark adds custom commands like:
  • spark:install (re-run setup)
  • spark:publish (publish assets/views)
  • spark:team:create (create a test team).

Extension Points

1. Customize the Installer

   • Fork the repository and modify src/NewProjectCommand.php to add your own project templates.
   • Example: Add a --custom-flag to include a custom module.

2. Post-Install Hooks

   • Override Spark’s app/Providers/SparkServiceProvider to extend functionality (e.g., add custom billing logic).
   • Use service provider boot methods to run logic after Spark initializes.

3. CI/CD Integration

   • Cache the spark CLI in Docker or CI pipelines to avoid re-downloading.
   • Example GitHub Actions step:

     - name: Install Spark
       run: |
         git clone https://github.com/laravel/spark-installer.git
         cd spark-installer && composer install
         sudo mv spark /usr/local/bin/
     

4. Local Development Tricks

   • Symlink Spark: For rapid iteration, symlink the Spark Installer to a global location:

     ln -s /path/to/spark-installer/spark /usr/local/bin/spark
     

   • Docker: Use the installer in a Docker container by mounting the cloned repo into the container.