Installer Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer global require laravel/installer
   

   Ensure ~/.composer/vendor/bin is in your PATH (or use ./vendor/bin/laravel if installed locally).

2. First Use Case: Create a new Laravel project with a single command:

   laravel new project-name
   

   This scaffolds a fresh Laravel app with all dependencies, .env, and default config.

3. Where to Look First:

   • Official Docs: Laravel Installation Guide (covers CLI flags, custom paths, and troubleshooting).
   • Source Code: Focus on InstallerCommand.php for CLI logic and Installer.php for core installation workflows.

Implementation Patterns

Usage Patterns

1. Project Creation:

   • Basic: laravel new project-name (creates in current directory).
   • Custom Path: laravel new /custom/path/project-name.
   • Preset: Use --preset=api, --preset=jetstream, or --preset=fortify to scaffold with preconfigured stacks (e.g., API-only, Jetstream auth).

     laravel new project-name --preset=jetstream
     

2. Dependency Management:

   • The installer runs composer install under the hood. Override dependencies by editing composer.json post-install or use --dev/--no-dev flags to control environment-specific packages.

3. Environment Setup:

   • Generates .env with default values. Customize via:
     • --env=production (sets APP_ENV=production).
     • Manually editing .env after installation.

4. Integration with CI/CD:

   • Use the installer in scripts (e.g., Dockerfiles, deployment pipelines) to ensure consistent environments:

     # Example in a Dockerfile
     RUN laravel new /var/www/project --preset=api --env=production
     

5. Local Development Workflow:

   • Combine with valet/laragon for local servers:

     laravel new ~/Sites/project-name && cd project-name && valet link
     

Workflows

1. Team Onboarding:

   • Standardize project setup with a shared README snippet:

     # Install project
     git clone repo-url
     cd project
     laravel new . --preset=jetstream  # Reinstall with preset
     npm install && npm run dev
     

2. Template Projects:

   • Clone a base project, then reinstall with the installer to reset dependencies/config:

     git clone --bare base-project.git new-project && cd new-project
     git push -u origin master
     laravel new . --preset=api  # Overwrite with new preset
     

3. Custom Presets:

   • Extend the installer by creating a custom preset (see Gotchas for extension points).

Gotchas and Tips

Pitfalls

1. Global Install Path:

   • If laravel command isn’t found, ensure ~/.composer/vendor/bin is in PATH or use the full path:

     ~/.composer/vendor/bin/laravel new project-name
     

2. Permission Issues:

   • Avoid running as root. Use sudo only if necessary (e.g., for system-wide Composer installs):

     sudo chown -R $USER ~/.composer
     

3. Preset Conflicts:

   • Mixing presets (e.g., --preset=api --preset=jetstream) may cause config clashes. Stick to one preset per install.

4. Composer Cache:

   • Clear Composer cache if downloads fail:

     composer clear-cache
     

5. Network Restrictions:

   • Corporate proxies may block GitHub/Composer. Configure via:

     composer config -g http-proxy http://proxy.example.com:8080
     

Debugging

1. Verbose Output:

   • Enable debug mode for detailed logs:

     laravel new project-name --verbose
     

2. Dry Runs:

   • Simulate installation without changes:

     laravel new project-name --dry-run
     

3. Manual Fallback:

   • If the installer fails, manually run:

     composer create-project laravel/laravel project-name
     

Config Quirks

1. .env Overrides:

   • The installer generates .env but doesn’t validate values. Always check critical settings (e.g., APP_KEY, DB_*).

2. Custom Composer Auth:

   • For private repositories, ensure auth.json is configured:

     composer config -g http-basic.example.com username password
     

3. PHP Version Mismatches:

   • The installer uses the system PHP. Specify a version via:

     # Using PHP 8.1 (via PHP-Brew or similar)
     PHP_BIN_PATH=/usr/local/php-8.1/bin/php laravel new project-name
     

Extension Points

1. Custom Presets:

   • Extend the installer by creating a custom preset package. Example structure:

     /path/to/preset/
     ├── composer.json       # Define preset as a Composer package
     ├── src/Preset.php      # Extend \Laravel\Installer\Preset
     └── README.md           # Documentation
     

   • Register the preset in composer.json:

     {
       "extra": {
         "laravel": {
           "presets": {
             "custom-preset": "vendor/path/to/preset"
           }
         }
       }
     }
     

   • Use it via:

     laravel new project-name --preset=custom-preset
     

2. Post-Install Hooks:

   • Override the installer’s behavior by publishing its templates:

     composer create-project laravel/installer && cd installer
     php artisan vendor:publish --tag=installer-templates
     

   • Modify resources/views/installer/ to customize scaffolding.

3. Integration with Laravel Sail:

   • Combine with Sail for Docker-based development:

     laravel new project-name --preset=sail