Sidecar Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require hammerstone/sidecar
   php artisan vendor:publish --provider="Hammerstone\Sidecar\SidecarServiceProvider" --tag="sidecar-config"
   

   Publish the config and migration files.

2. Configuration Edit config/sidecar.php to define your Lambda functions:

   'functions' => [
       'process-payment' => [
           'handler' => 'App\Services\PaymentProcessor',
           'memory' => 512,
           'timeout' => 30,
           'environment' => [
               'APP_ENV' => env('APP_ENV'),
           ],
       ],
   ],
   

   Run migrations:

   php artisan migrate
   

3. First Use Case Define a Lambda handler class:

   namespace App\Services;
   
   use Hammerstone\Sidecar\Contracts\LambdaHandler;
   
   class PaymentProcessor implements LambdaHandler
   {
       public function handle($event)
       {
           // Process payment logic
           return ['status' => 'success'];
       }
   }
   

   Trigger it via HTTP or CLI:

   php artisan sidecar:invoke process-payment '{"data": "test"}'
   

Implementation Patterns

Workflows

1. Local Development Use the sidecar:serve command to test Lambdas locally:

   php artisan sidecar:serve
   

   This spins up a local AWS-like environment for debugging.

2. Deployment Integration Hook into Laravel’s deploy event in AppServiceProvider:

   public function boot()
   {
       Sidecar::afterDeploy(function () {
           // Post-deploy Lambda updates (e.g., warm-up calls)
       });
   }
   

3. Event-Driven Lambdas Subscribe to Laravel events and trigger Lambdas:

   use Hammerstone\Sidecar\Facades\Sidecar;
   
   event(new PaymentProcessed($payment));
   Sidecar::invoke('process-payment', ['payment_id' => $payment->id]);
   

Integration Tips

• Shared State: Use Sidecar::sharedState() to pass data between Lambdas and your main app.
• Environment Variables: Dynamically inject variables from .env:

  'environment' => [
      'STRIPE_KEY' => env('STRIPE_KEY'),
  ],
  

• Async Invocations: Use Sidecar::invokeAsync() for fire-and-forget tasks:

  Sidecar::invokeAsync('cleanup-temp-files');
  

Gotchas and Tips

Pitfalls

1. Cold Starts Lambdas may have latency on first invocation. Mitigate with:

   • Provisioned Concurrency: Configure in sidecar.php:

     'provisioned_concurrency' => [
         'process-payment' => 2,
     ],
     

   • Warm-Up Calls: Schedule a cron job to ping Lambdas periodically.

2. Environment Mismatches Ensure APP_ENV and other env vars match between your app and Lambda. Use:

   'environment' => array_merge(
       ['APP_ENV' => env('APP_ENV')],
       config('services.aws.default', [])
   ),
   

3. Dependency Hell Lambdas share the same composer.json as your app. Use sidecar:prune to clean up unused dependencies:

   php artisan sidecar:prune
   

Debugging

• Logs: Stream logs with:

  php artisan sidecar:logs process-payment
  

• X-Ray Tracing: Enable AWS X-Ray integration in sidecar.php:

  'aws' => [
      'xray_enabled' => true,
  ],
  

• Local Debugging: Use sidecar:serve --debug to attach Xdebug.

Extension Points

1. Custom Handlers Extend LambdaHandler to add middleware:

   class AuthenticatedPaymentProcessor extends PaymentProcessor
   {
       public function handle($event)
       {
           if (!auth()->check()) {
               throw new \RuntimeException('Unauthorized');
           }
           return parent::handle($event);
       }
   }
   

2. Pre/Post Hooks Override SidecarServiceProvider to add logic before/after invocations:

   public function boot()
   {
       Sidecar::beforeInvoke(function ($name, $payload) {
           \Log::info("Invoking Lambda: {$name}");
       });
   }
   

3. Custom Storage Replace the default DynamoDB storage with RDS or another backend by binding a custom Storage contract:

   $this->app->bind(
       \Hammerstone\Sidecar\Contracts\Storage::class,
       \App\Services\CustomLambdaStorage::class
   );