Lumen Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer create-project laravel/lumen your-project-name
   

   • Use ^9.x for Lumen 9.x (latest stable) or ^8.x for older projects.
   • Ensure PHP ≥ 8.0 (Lumen 9.x) or ≥ 7.4 (Lumen 8.x).

2. First Use Case:

   • Navigate to routes/web.php and define a simple route:

     $app->get('/', 'App\Http\Controllers\ExampleController@index');
     

   • Create a controller:

     php artisan make:controller ExampleController
     

   • Run the built-in server:

     php -S localhost:8000 -t public
     

   • Visit http://localhost:8000 to verify.

3. Key Files to Explore:

   • bootstrap/app.php: Entry point for bootstrapping.
   • config/app.php: Core configuration (providers, aliases).
   • routes/: All route definitions (web.php, api.php).
   • app/Providers/: Service providers (e.g., AppServiceProvider.php).

Implementation Patterns

Core Workflows

1. Routing:

   • Use Route::get(), Route::post(), etc., or $app->get() for Lumen’s syntax.
   • Group routes with middleware:

     $app->group(['middleware' => 'auth'], function () {
         $app->get('/dashboard', 'DashboardController@index');
     });
     

   • API versioning:

     $app->group(['prefix' => 'api/v1'], function () {
         $app->post('/users', 'UserController@store');
     });
     

2. Dependency Injection:

   • Bind interfaces to implementations in AppServiceProvider:

     $this->app->bind(
         App\Contracts\UserRepository::class,
         App\Repositories\UserRepository::class
     );
     

   • Resolve dependencies in controllers:

     public function __construct(App\Contracts\UserRepository $users) {
         $this->users = $users;
     }
     

3. Middleware:

   • Register middleware in bootstrap/app.php:

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

   • Create custom middleware:

     php artisan make:middleware CheckRole
     

4. Database:

   • Use Eloquent models (same as Laravel):

     $user = App\Models\User::find(1);
     

   • Configure .env for database connections:

     DB_CONNECTION=mysql
     DB_HOST=127.0.0.1
     DB_PORT=3306
     

5. Validation:

   • Use Laravel’s validator:

     $validator = Validator::make($request->all(), [
         'email' => 'required|email',
     ]);
     

6. Testing:

   • Write HTTP tests in tests/Feature:

     public function test_example_route()
     {
         $response = $this->get('/');
         $response->assertStatus(200);
     }
     

   • Run tests:

     phpunit
     

Integration Tips

• Laravel Packages: Most Laravel packages work with Lumen (e.g., laravel/sanctum, spatie/laravel-permission).
  • Install via Composer and register providers in bootstrap/app.php.
• Queue Workers: Use php artisan queue:work (configure QUEUE_CONNECTION in .env).
• Caching: Leverage Cache::put() or Cache::remember() with drivers like Redis or file.
• Events/Listeners: Define events in app/Events and listeners in app/Listeners.

Gotchas and Tips

Pitfalls

1. Middleware Differences:

   • Lumen’s VerifyCsrfToken middleware is not auto-registered (unlike Laravel).
   • Add it manually in bootstrap/app.php:

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

2. Service Provider Booting:

   • Lumen does not auto-discover providers in config/app.php like Laravel.
   • Manually register providers in bootstrap/app.php:

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

3. Route Caching:

   • Lumen does not support php artisan route:cache (use php artisan route:list instead).
   • For performance, manually optimize routes or use a reverse proxy (e.g., Nginx).

4. Session Handling:

   • Sessions require explicit middleware (web middleware group).
   • Ensure SESSION_DRIVER=file (or another driver) is set in .env.

5. Blade Templates:

   • Lumen does not include Blade by default (it’s a micro-framework).
   • Install manually:

     composer require illuminate/view
     

   • Register the service provider in bootstrap/app.php:

     $app->register(\Illuminate\View\ViewServiceProvider::class);
     

6. File Structure:

   • Lumen lacks resources/views by default. Create it manually if using Blade.

Debugging

• Error Pages:
  • Lumen uses bootstrap/app.php for error handling. Customize by modifying:

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

• Logging:
  • Use Log::error(), Log::info(), etc. (requires illuminate/log).
  • Configure APP_LOG in .env (e.g., APP_LOG=single).

Extension Points

1. Custom Commands:

   • Create commands in app/Console/Commands and register in bootstrap/app.php:

     $app->command('custom:command', \App\Console\Commands\CustomCommand::class);
     

   • Run with:

     php artisan custom:command
     

2. API Resources:

   • Use php artisan make:resource (requires illuminate/http).
   • Transform responses:

     return new UserResource($user);
     

3. Testing Helpers:

   • Extend Lumen\Testing\TestCase for custom assertions.
   • Example:

     public function assertJsonContains($key, $value)
     {
         $this->seeJson($key, $value);
     }
     

4. Performance:

   • Disable unnecessary features (e.g., debug mode in production):

     $app->configure('app');
     

   • Use APP_DEBUG=false in .env for production.

Config Quirks

• Environment Variables:
  • Lumen uses .env like Laravel, but ensure variables are loaded in bootstrap/app.php:

    $app->configure('app');
    

• CORS:
  • Install fruitcake/laravel-cors for CORS support (not built-in).
  • Register middleware in bootstrap/app.php:

    $app->middleware([
        \Fruitcake\Cors\HandleCors::class,
    ]);