Ssm Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require async-aws/ssm
   

   Ensure aws/aws-sdk-php is also installed (dependency).

2. Basic Usage Initialize the SSM client in a Laravel service provider or config file:

   use AsyncAws\Ssm\SsmClient;
   
   $client = new SsmClient([
       'region' => 'us-east-1',
       'version' => 'latest',
       'credentials' => [
           'key'    => env('AWS_ACCESS_KEY_ID'),
           'secret' => env('AWS_SECRET_ACCESS_KEY'),
       ],
   ]);
   

3. First Use Case: Fetching a Parameter

   $parameter = $client->getParameter([
       'Name' => '/myapp/db/username',
   ]);
   $value = $parameter->getParameter()->getValue();
   

Where to Look First

• Documentation: AsyncAws SSM Docs (if available).
• Source Code: Focus on AsyncAws\Ssm\SsmClient and its methods (e.g., getParameter, putParameter).
• Laravel Integration: Check if the package supports Laravel’s config or env helpers (e.g., via a facade or service binding).

Implementation Patterns

Workflows

1. Parameter Retrieval Use getParameter for read-only access to SSM parameters (e.g., secrets, configs):

   $client->getParameter(['Name' => '/app/settings/timeout']);
   

2. Secure String Handling For encrypted parameters (e.g., secrets), use getParameters with WithDecryption:

   $response = $client->getParameters([
       'Names' => ['/secrets/db/password'],
       'WithDecryption' => true,
   ]);
   

3. Bulk Operations Fetch multiple parameters efficiently:

   $response = $client->getParameters([
       'Names' => ['/param1', '/param2'],
       'WithDecryption' => true,
   ]);
   

4. Caching Layer Cache SSM responses in Laravel’s cache (e.g., Redis) to reduce AWS API calls:

   $cacheKey = 'ssm_param_' . md5('/myapp/version');
   $value = Cache::remember($cacheKey, now()->addHours(1), function () use ($client) {
       return $client->getParameter(['Name' => '/myapp/version'])->getParameter()->getValue();
   });
   

Integration Tips

• Laravel Facade: Bind the client to Laravel’s IoC container for easy access:

  // In a service provider
  $this->app->singleton(SsmClient::class, function ($app) {
      return new SsmClient([
          'region' => config('aws.region'),
          'credentials' => $app['aws']->credentials(),
      ]);
  });
  

  Then inject SsmClient into controllers/services.

• Environment Variables: Use SSM to replace .env secrets during deployment:

  // In a deployment script
  $envVars = $client->getParameters(['Names' => ['/env/APP_KEY', '/env/DB_PASSWORD']]);
  foreach ($envVars->getParameters() as $param) {
      putenv($param->getName() . '=' . $param->getValue());
  }
  

• Event-Driven Updates: Listen for SSM parameter changes (via AWS EventBridge) and trigger Laravel events or jobs to update cached values.

Gotchas and Tips

Pitfalls

1. Permissions Ensure the IAM role/user has ssm:GetParameter (and ssm:GetParameters for bulk) permissions. Missing permissions cause AccessDeniedException.

2. Parameter Store vs. Secrets Manager

   • SSM Parameter Store is not a secrets manager by default. Use WithDecryption for encrypted strings or migrate to AWS Secrets Manager for sensitive data.

3. Caching Headers SSM parameters may not support Cache-Control headers. Rely on Laravel’s cache or a custom TTL system.

4. Async Limitations The package is async-aws-compatible but may not support all Laravel sync workflows out of the box. Test async/await patterns if using async features.

5. Parameter Names SSM paths are case-sensitive and must start with /. Invalid names throw InvalidParameterException.

Debugging

• Enable AWS SDK Debugging:

  $client = new SsmClient([...]);
  $client->getHandler()->setDebug(true); // Logs raw API calls
  

• Check for Throttling: SSM has rate limits (e.g., 100 requests/second). Use exponential backoff for retries:

  use AsyncAws\Core\Exception\ThrottlingException;
  try {
      $client->getParameter([...]);
  } catch (ThrottlingException $e) {
      sleep(1); // Simple backoff; use a library like Guzzle’s retry middleware for production.
      retry();
  }
  

Tips

1. Parameter Versioning Use getParameterHistory to audit changes:

   $history = $client->getParameterHistory(['Name' => '/app/version']);
   

2. Tagging Parameters Tag parameters for organizational purposes (e.g., Environment=production):

   $client->addTagsToResource([
       'ResourceType' => 'parameter',
       'ResourceId' => '/app/settings',
       'Tags' => ['Environment' => 'production'],
   ]);
   

3. Laravel Config Integration Dynamically load SSM parameters into Laravel’s config:

   // In a config service provider
   config(['app.version' => $client->getParameter(['Name' => '/app/version'])->getParameter()->getValue()]);
   

4. Error Handling Catch specific exceptions for graceful degradation:

   use AsyncAws\Ssm\Exception\ParameterNotFoundException;
   try {
       $client->getParameter(['Name' => '/nonexistent']);
   } catch (ParameterNotFoundException $e) {
       Log::warning('SSM parameter not found', ['parameter' => '/nonexistent']);
       return config('app.fallback_value');
   }
   

5. Local Development Use the aws-sdk-php localstack plugin or mock the client for testing:

   // Mock example (using Mockery)
   $mock = Mockery::mock(SsmClient::class);
   $mock->shouldReceive('getParameter')
        ->once()
        ->andReturn((new GetParameterResponse())->withParameter(new Parameter('/test', 'value')));