Vapor Core Laravel Package

Getting Started

Minimal Steps

1. Installation: Add the package to your composer.json:

   composer require laravel/vapor-core
   

   Ensure your Laravel app is v10+ (preferably v13 for full Symfony 8 support).

2. Environment Setup: Set VAPOR_ENV in your .env:

   VAPOR_ENV=production
   

   This overrides APP_ENV in serverless contexts.

3. First Use Case: Check if your app is running on Vapor:

   use Illuminate\Support\Facades\App;
   
   if (App::runningOnVapor()) {
       // Vapor-specific logic (e.g., optimized caching, SQS queues)
   }
   

4. Verify Runtime: Test Lambda event handling by triggering a route or queue job. The package auto-configures request parsing (API Gateway, SQS, etc.).

Implementation Patterns

Core Workflows

1. Request Handling

• API Gateway: Automatically parses APIGatewayProxyRequest into Laravel’s $request object.

  // Access API Gateway metadata (e.g., request ID)
  $requestId = request()->header('X-Amzn-Trace-Id');
  

• SQS Events: Use Vapor::event() to inspect incoming SQS messages:

  use Laravel\Vapor\Vapor;
  
  $event = Vapor::event();
  if ($event->isSqs()) {
      $body = $event->body(); // Decoded SQS payload
  }
  

2. Environment Awareness

• Dynamic Environment Detection:

  if (App::runningInConsole() && App::runningOnVapor()) {
      // Run Vapor-specific Artisan commands (e.g., `vapor:deploy`)
  }
  

• Environment-Specific Config: Use config('vapor.*.key') for Vapor-only settings (e.g., SQS queue names).

3. Job Queues

• SQS Integration: Dispatch jobs to Vapor-managed SQS queues:

  dispatch(new ProcessPayment)->onVaporQueue('payments');
  

• Job Scoping: Reset scoped bindings before job execution (handled automatically by v2.37.2+).

4. CLI Commands

• Dynamic Handlers: Extend CLI support with custom handlers:

  use Laravel\Vapor\Console\DynamicCliHandler;
  
  DynamicCliHandler::macro('custom', function ($input, $output) {
      // Custom CLI logic
  });
  

5. Logging & Debugging

• Lambda Context: Access AWS Lambda metadata:

  use Laravel\Vapor\Vapor;
  
  $context = Vapor::context();
  $functionName = $context->functionName; // e.g., "app-1234567890"
  

• Conditional Logging: Wrap logs to avoid noise in serverless:

  if (App::runningOnVapor()) {
      Log::debug('Vapor-specific debug info');
  }
  

Integration Tips

With AWS Services

• RDS/ElastiCache: Use config('database.connections.mysql.serverless') for Vapor’s serverless database proxies.
• S3-Compatible Storage: Configure filesystems.disks.s3 with driver: 's3' and endpoint: 'https://s3.amazonaws.com' (or your S3-compatible endpoint).

With Octane

• Streamed Responses: Ensure v2.32.2+ for Octane compatibility:

  use Laravel\Octane\Facades\Octane;
  
  Octane::streaming(function () {
      // Streamed response logic
  });
  

With Laravel Queues

• Queue Workers: Use vapor:queue to run workers in Vapor:

  php artisan vapor:queue --queue=high
  

• Queue Events: Listen for Vapor\Events\JobProcessed:

  event(new Vapor\Events\JobProcessed($job));
  

Custom Events

• Lambda Events: Handle custom Lambda events (e.g., from EventBridge):

  if (Vapor::event()->isLambda()) {
      $detail = Vapor::event()->detail(); // Custom event data
  }
  

Gotchas and Tips

Pitfalls

1. Environment Confusion:

   • Issue: APP_ENV may not reflect Vapor’s environment if VAPOR_ENV is misconfigured.
   • Fix: Always use App::runningOnVapor() to check context:

     if (App::runningOnVapor() && App::environment('staging')) {
         // Vapor staging logic
     }
     

2. PDO "Server Gone Away" Errors:

   • Issue: MySQL connections may drop during long-running Lambda executions (fixed in v2.43.3).
   • Fix: Use DB::reconnect() or configure wait_timeout in your RDS proxy.

3. Multipart Form Data:

   • Issue: Multidimensional arrays in file uploads may not parse correctly (fixed in v2.37.9).
   • Fix: Ensure v2.37.9+ or manually parse $request->all().

4. Octane + Vapor:

   • Issue: Cookies may not persist in Octane on Vapor (fixed in v2.37.8).
   • Fix: Upgrade to v2.37.8+ or use session()->put() explicitly.

5. S3-Compatible Storage:

   • Issue: MinIO or other S3-compatible storage may fail with AWS-specific assumptions.
   • Fix: Use v2.38.0+ and configure endpoint explicitly:

     'disks' => [
         's3' => [
             'driver' => 's3',
             'endpoint' => env('S3_ENDPOINT', 'https://s3.amazonaws.com'),
         ],
     ],
     

6. Cold Starts:

   • Issue: Long initialization in boot() can delay cold starts.
   • Fix: Defer non-critical boot logic:

     if (!App::runningOnVapor()) {
         // Heavy boot logic (e.g., caching)
     }
     

Debugging Tips

1. Lambda Context:

   • Dump the execution context for debugging:

     dd(Vapor::context()->toArray());
     

   • Check functionName, invokedFunctionArn, and awsRequestId.

2. Event Inspection:

   • Log raw events for SQS/Lambda:

     Log::debug('Raw event:', Vapor::event()->raw());
     

3. Environment Detection:

   • Verify environment detection:

     dd([
         'runningOnVapor' => App::runningOnVapor(),
         'environment' => App::environment(),
         'vaporEnv' => env('VAPOR_ENV'),
     ]);
     

4. Queue Jobs:

   • Check job processing with:

     php artisan vapor:queue:work --queue=critical --timeout=30
     

Extension Points

1. Custom Event Handlers:

   • Extend Laravel\Vapor\Events\VaporEvent to handle custom Lambda/SQS events:

     class CustomEvent extends VaporEvent
     {
         public function isCustom(): bool
         {
             return $this->raw['detail-type'] === 'custom.event';
         }
     }
     

2. Dynamic CLI Handlers:

   • Register custom CLI handlers:

     DynamicCliHandler::extend('custom:command', function ($input, $output) {
         $output->writeln('Running custom command on Vapor!');
     });
     

3. Service Provider Overrides:

   • Override the VaporServiceProvider for custom logic:

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

4. Request Parsing:

   • Extend request parsing for custom Lambda event formats:

     use Laravel\Vapor\Http\RequestParser;
     
     RequestParser::macro('custom', function ($request) {
         // Custom parsing logic
     });
     

Configuration Quirks

1. VAPOR_ENV Override:

   • The package respects VAPOR_ENV over APP_ENV in serverless contexts. Set it in your Vapor environment variables:

     VAPOR_ENV=staging
     

2. Queue Configuration:

   • Vapor queues default to vapor-<queue-name>. Override in config/queue.php:

     'connections' => [
         'vapor' => [
             'driver' => 'sqs',
             'queue' => env('SQS_QUEUE', 'vapor-default'),