Lumen Installer Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer create-project --prefer-dist laravel/lumen-installer project-name
   

   • This creates a fresh Lumen project with preconfigured boilerplate (routes, middleware, and basic structure).

2. First Use Case:

   • Navigate to project-name and run:

     php -S localhost:8000 -t public
     

   • Access http://localhost:8000 to verify the default Lumen "Hello World" response.

3. Where to Look First:

   • bootstrap/app.php: Entry point for the application (similar to Laravel’s index.php).
   • routes/web.php: Default routes (e.g., / and /api).
   • app/Http/Middleware/: Predefined middleware (e.g., VerifyCsrfToken).
   • config/: Default Lumen configurations (e.g., app.php, database.php).

Implementation Patterns

Core Workflows

1. Scaffolding a New Project:

   • Use the installer to generate a project with:
     • Predefined routes (e.g., RESTful API endpoints).
     • Middleware stack (e.g., CORS, CSRF).
     • Basic service provider structure.
   • Customize by overriding default files (e.g., routes/web.php, app/Providers/AppServiceProvider.php).

2. Integrating with Laravel Ecosystem:

   • Service Providers: Register providers in bootstrap/app.php:

     $app->register(App\Providers\AppServiceProvider::class);
     

   • Middleware: Attach middleware to routes or globally:

     $app->routeMiddleware([
         'auth' => App\Http\Middleware\Authenticate::class,
     ]);
     

   • Database: Configure config/database.php and use Eloquent models (Lumen supports Laravel’s ORM).

3. API Development:

   • Leverage Lumen’s lightweight routing for API endpoints:

     $router->get('/users', 'UserController@index');
     

   • Use DTOs (Data Transfer Objects) or API resources for responses:

     return new UserResource(User::all());
     

4. Testing:

   • Use Lumen’s built-in testing helpers (e.g., Http::get(), Http::post()) or PHPUnit.
   • Example test:

     $response = $this->get('/');
     $response->assertStatus(200);
     

5. Environment Configuration:

   • Use .env files for environment-specific settings (e.g., database connections, API keys).
   • Load configurations in bootstrap/app.php:

     $app->withFacades();
     $app->withEloquent();
     

Integration Tips

• Laravel Packages: Most Laravel packages (e.g., laravel/scout, spatie/laravel-permission) work with Lumen with minor adjustments (e.g., service provider registration).
• Artisan Commands: Extend Lumen’s CLI with custom commands:

  $app->command('custom:command', CustomCommand::class);
  

• Queue Workers: Use Lumen’s queue system (configured in config/queue.php) with php artisan queue:work.

Gotchas and Tips

Pitfalls

1. Middleware Differences:

   • Lumen’s middleware stack is lighter than Laravel’s. Some Laravel middleware (e.g., ShareErrorsFromSession) may not work out-of-the-box.
   • Fix: Manually register required middleware in bootstrap/app.php.

2. Service Container:

   • Lumen’s container is a subset of Laravel’s. Some Laravel-specific container features (e.g., app()->makeWith()) may not be available.
   • Tip: Use dependency injection via constructor binding:

     public function __construct(UserRepository $users) { ... }
     

3. Routing Conflicts:

   • Lumen’s router is optimized for APIs. Web routes (e.g., Blade templates) require additional setup (e.g., laravel/lumen-framework v7+ supports views).
   • Tip: Use Route::view() for simple web routes:

     $router->get('/', function () {
         return view('welcome');
     });
     

4. Database Migrations:

   • Lumen supports migrations, but the migrate Artisan command is not included by default.
   • Fix: Install laravel/framework (if needed) or use raw PDO queries.

5. Caching:

   • Lumen’s caching is basic. For advanced caching (e.g., Redis), install predis/predis and configure config/cache.php.

Debugging

• Error Handling:
  • Lumen’s default error handler is minimal. For detailed errors, use:

    $app->error(function ($request, $exception) {
        return response()->json([
            'error' => $exception->getMessage(),
        ], 500);
    });
    

• Logging:
  • Configure config/app.php to use Monolog:

    'log' => 'single',
    

  • View logs in storage/logs/lumen.log.

Configuration Quirks

1. Environment Files:

   • Lumen loads .env files from the project root. Ensure .env.example is included for deployment.
   • Tip: Use php artisan config:clear to reload configurations after changes.

2. Service Provider Order:

   • Providers registered later may override earlier ones. Explicitly bind services in AppServiceProvider:

     public function boot() {
         $this->app->bind('customService', function () { ... });
     }
     

3. Routing Groups:

   • Lumen’s Route::group() supports middleware and namespace:

     $router->group(['middleware' => 'auth'], function () {
         $router->get('/profile', 'UserController@profile');
     });
     

Extension Points

1. Custom Installer Templates:

   • Fork the installer repository to modify default templates (e.g., add a README.md stub or custom .gitignore).

2. Post-Install Hooks:

   • Extend the installer by adding post-install commands (e.g., composer post-install-cmd in composer.json):

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

3. Lumen Framework Updates:

   • The installer uses laravel/lumen-framework. Pin the version in composer.json to avoid breaking changes:

     "require": {
         "laravel/lumen-framework": "6.*"
     }