Ssm Parameters Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. A Laravel developer should treat it as a reference implementation or only use it inside a Symfony service that sits next to a Laravel app. If you are working in Laravel, start with aws/aws-sdk-php and a small config loader instead of installing this bundle directly.

Minimal steps if you are in a Symfony project:

1. composer require supportbook/ssm-parameters-bundle
2. Register the bundle in config/bundles.php
3. Configure AWS region, credentials, and the SSM parameter path prefix in config/packages/*.yaml
4. Fetch a simple parameter such as /myapp/dev/database/password and inject it into a service or parameter bag.

Look first at:

• The README for the exact configuration key names
• The bundle extension class and service definitions to see how parameters are resolved
• Any console commands or cache warmers shipped with the bundle

First useful use case: remove database credentials and third-party API keys from .env files and load them from AWS Systems Manager Parameter Store at deploy or container boot time.

For Laravel, the equivalent first step is a custom service provider or bootstrap file that calls SsmClient::getParameter() and merges the result into config(). Do not assume Symfony bundle auto-discovery works in Laravel.

Implementation Patterns

Use hierarchical parameter names that mirror environments:

• /myapp/prod/db/host
• /myapp/prod/db/password
• /myapp/staging/db/password

Load parameters once during application boot, then expose them through the framework's config system. In Symfony this is typically done through the bundle's parameter resolution; in Laravel use a service provider, a cached config file, or a deployment step that writes resolved values into environment variables.

Common workflows:

• Deployment-time resolution: fetch SSM parameters in CI/CD and write them to .env or a generated config file. This avoids runtime AWS calls and keeps local development simple.
• Runtime resolution with caching: fetch on first boot and cache in Laravel's config cache or a local file. Clear the cache on deploy.
• Path-based bulk loading: use GetParametersByPath for a prefix such as /myapp/prod/ and map the leaf names to config keys.
• SecureString integration: store secrets as SecureString and let IAM/KMS handle decryption.
• Local fallback: if APP_ENV=local, read from .env; in production, read from SSM. Keep the same config keys in both paths.

Laravel integration pattern:

// app/Providers/SecretsServiceProvider.php
use Aws\Ssm\SsmClient;

public function boot()
{
    if (app()->environment('local')) {
        return;
    }

    $ssm = new SsmClient([
        'region' => config('services.aws.region'),
        'version' => 'latest',
    ]);

    $result = $ssm->getParametersByPath([
        'Path' => '/myapp/' . app()->environment() . '/',
        'WithDecryption' => true,
        'Recursive' => true,
    ]);

    foreach ($result['Parameters'] as $parameter) {
        $key = str_replace('/', '.', trim($parameter['Name'], '/'));
        config([$key => $parameter['Value']]);
    }
}

Keep the SSM path convention stable across services. A parameter named /myapp/prod/db/password should always map to database.connections.mysql.password or another explicit key, not depend on implicit string replacement.

Gotchas and Tips

• Framework mismatch: this is a Symfony bundle. In Laravel you will not get service provider auto-discovery, facades, or Laravel-specific config loading. Expect to wrap or reimplement the core behavior.
• IAM permissions: the runtime role needs ssm:GetParameter, ssm:GetParameters, ssm:GetParametersByPath, and kms:Decrypt for SecureString parameters.
• Region and credentials: misconfigured region or missing credentials often surface as vague AWS SDK errors. Verify with aws ssm get-parameter --name ... --with-decryption.
• Latency and cold starts: runtime SSM calls add latency. Cache resolved values at deploy time or in the framework config cache. Avoid fetching the same parameter repeatedly per request.
• Parameter size limits: standard parameters are limited to 4 KB and advanced parameters to 8 KB. Do not store large JSON blobs or certificates unless you have checked the limits.
• Leading slashes and path prefixes: SSM parameter names are case-sensitive and hierarchical. A missing leading slash or a trailing slash in the prefix will produce empty results.
• Local development: do not require AWS access for every developer. Provide a local .env fallback and fail only in non-local environments when parameters are missing.
• Cache clearing: if you cache SSM values, remember to clear that cache on deploy. Stale secrets are a common source of confusing auth failures.
• Debugging: enable AWS SDK logging temporarily, check CloudTrail for AccessDenied or ParameterNotFound, and use aws ssm describe-parameters to confirm names. In Symfony, check the container compilation and bundle config; in Laravel, check that your service provider runs early enough.
• Vendor risk: this package has zero stars and zero dependents. Treat it as a small internal utility. Read the source before relying on it, and be prepared to fork or replace it with a short AWS SDK wrapper.
• Extension points: if you do use the Symfony bundle, look for custom parameter providers, service decorators, or configurable clients so you can inject your own SsmClient and cache layer. In Laravel, the equivalent extension point is your own service provider and a small SsmConfigRepository class.