Installer Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer global require laravel/installer
   

   Ensure ~/.composer/vendor/bin is in your PATH.

2. First Use Case: Create a new Laravel project in a directory:

   laravel new project-name
   

   This clones the Laravel repository, installs dependencies, and sets up the project structure.

3. Key Flags:

   • --preset=api: Generate an API-focused project.
   • --stack=jetstream: Use Jetstream scaffolding.
   • --database=sqlite: Specify a database (auto-runs migrations).
   • --no-interaction: Skip prompts (useful for CI/CD).

4. Where to Look First:

   • Official Laravel Docs for version-specific guidance.
   • laravel --help for CLI options.
   • GitHub Issues for troubleshooting.

Implementation Patterns

Workflows

1. Local Development Setup:

   laravel new my-app --preset=api --database=mysql
   cd my-app
   cp .env.example .env
   composer install
   php artisan key:generate
   

   • Use --preset to tailor the project (e.g., api, jetstream, fortify).
   • Combine with --stack for frontend frameworks (e.g., --stack=inertia).

2. CI/CD Integration:

   laravel new my-app --no-interaction --preset=api --database=postgres
   

   • Use --no-interaction to avoid prompts in automated pipelines.
   • Cache Composer dependencies for faster builds.

3. Custom Starter Kits:

   laravel new my-app --kit=git@github.com:user/custom-kit.git
   

   • Leverage --kit to use custom templates (e.g., monorepos, legacy setups).

4. Database Handling:

   laravel new my-app --database=sqlite --force
   

   • Auto-generates a SQLite database file and runs migrations.
   • For MySQL/PostgreSQL, prompts for credentials (or use --database=mysql --force with pre-configured .env).

5. Environment-Specific Flags:

   • Windows: Use --no-boost to skip Laravel Boost installation if not needed.
   • Linux/macOS: Prefer valet/herd for local development (installer auto-detects and suggests).

Integration Tips

• Composer Scripts: Extend the installer’s behavior by adding custom scripts to composer.json:

  "scripts": {
    "post-install-cmd": [
      "@php artisan key:generate",
      "@php artisan config:clear"
    ]
  }
  

• Post-Install Hooks: Use the --hook flag (v5.28.0+) to run custom scripts after installation:

  laravel new my-app --hook="composer require my/package"
  

• Template Customization: Override default templates by placing custom files in ~/.laravel/templates/.

Gotchas and Tips

Pitfalls

1. Path Permissions:

   • On Linux/macOS, ensure the target directory is writable:

     chmod -R 755 /path/to/project
     

   • Windows may require running the command prompt as Administrator.

2. Database Auto-Migration:

   • The --database flag auto-runs migrations, which may fail if:
     • The database server isn’t running (e.g., MySQL/PostgreSQL not started).
     • .env isn’t properly configured (e.g., DB_PASSWORD missing).
   • Fix: Use --force to skip migration prompts or manually run php artisan migrate.

3. Interactive Prompts in CI:

   • Flags like --database=mysql may still prompt for credentials if .env is incomplete.
   • Solution: Pre-populate .env or use --no-interaction with a pre-configured setup.

4. Laravel Boost Conflicts:

   • The --no-boost flag is required if you’re not using Laravel Boost or have version conflicts.
   • Boost may fail silently on Windows if Node.js isn’t in PATH.

5. Custom Kit Issues:

   • Git-based kits (--kit=git@...) require SSH keys or HTTPS credentials.
   • Debug: Use --verbose to see clone errors.

6. Composer Cache:

   • Clear Composer cache if installations hang:

     composer clear-cache
     

Debugging

• Verbose Output:

  laravel new my-app --verbose
  

  Reveals hidden steps (e.g., Git clone URLs, Composer commands).

• Dry Run: Simulate installation without changes:

  laravel new my-app --dry-run
  

• Log Files: Check ~/.laravel/logs/ for installer errors (created on failure).

Configuration Quirks

1. Default Presets:

   • The installer defaults to the latest Laravel version. To pin a version:

     laravel new my-app --dev
     

     (Uses laravel/framework dev-main branch.)

2. Environment Detection:

   • The installer auto-detects valet/herd but may misidentify paths on custom installations.
   • Fix: Manually set VALET_HOME or HERD_HOME environment variables.

3. Node.js/Package Manager:

   • Supports npm, yarn, pnpm, and bun. Specify with --npm:

     laravel new my-app --npm=yarn
     

   • Gotcha: bun may require explicit installation (--npm=bun).

4. PHP Version:

   • The installer uses the system PHP binary. To specify a version:

     update-alternatives --set php /path/to/php8.2
     

   • Debug: Use php -v to confirm the active version.

Extension Points

1. Custom Templates: Override default templates by copying files from vendor/laravel/installer/src/Stubs/ to ~/.laravel/templates/.

2. Post-Install Scripts: Use the --hook flag (v5.28.0+) to run custom commands:

   laravel new my-app --hook="php artisan package:discover"
   

3. Database Drivers: Extend supported drivers by modifying the Database class in the installer’s source or using --database=custom with manual setup.

4. Starter Kit Registry: Add custom kits to the registry by extending the StarterKit class or using the --kit flag with a Git repo.

5. CI/CD Optimizations: Cache Composer dependencies and Laravel Boost for faster builds:

   composer install --optimize-autoloader --no-dev