Secrets Loader Laravel Package

Product Decisions This Supports

• Security & Compliance: Enables AWS SSM Parameter Store integration for encrypted, versioned, and auditable secrets management, aligning with SOC2, GDPR, or HIPAA requirements. Eliminates hardcoded secrets or .env files in serverless deployments.
• Serverless PHP Adoption: Justifies choosing Bref over alternatives (e.g., AWS SAM, custom Lambda layers) for PHP serverless apps by providing native SSM support. Reduces friction for teams migrating from traditional PHP to serverless.
• Cost Efficiency: Avoids reinventing SSM secret loading, reducing DevOps overhead. Lightweight (~500 LOC) with no runtime bloat (installed separately).
• Multi-Environment Workflows: Centralizes secrets in SSM with environment-specific paths (e.g., /dev/, /prod/), enabling dynamic configurations without redeploying. Supports feature flags or A/B testing.
• Roadmap for Laravel on AWS: Bridges Laravel’s environment-based config with AWS SSM, enabling seamless deployments. Future-proofs for Laravel’s serverless adoption.
• Build vs. Buy: Buy—this package is production-ready (MIT license, active maintenance, PHP 8.0+ support) and avoids technical debt. Only custom-build if SSM requirements are highly bespoke (e.g., cross-account access or custom decryption).

When to Consider This Package

Adopt if:

• Your PHP app runs on AWS Lambda via Bref and needs AWS SSM Parameter Store integration.
• You manage sensitive environment variables (API keys, DB credentials) and want to avoid hardcoding or .env files in serverless deployments.
• Your team prioritizes security compliance (e.g., secrets rotation, audit logs) without manual IAM setup.
• You’re using Bref 1.0+ and PHP 8.0+ (supports up to 8.5).
• You need low-latency secret loading (async-aws/ssm v2.x support) without blocking Lambda cold starts.
• You’re using Laravel and want to centralize secrets management in SSM while maintaining compatibility with Laravel’s env() and config() helpers.

Look elsewhere if:

• You’re not using Bref: This package is Bref-specific. For other runtimes (EC2, ECS, or non-AWS), use AWS SDK directly or tools like aws-ssm-get-parameter.
• You need non-SSM secrets: For Vault, KMS, or other backends, evaluate alternatives like vlucas/phpdotenv + custom loaders or AWS Secrets Manager.
• Your secrets are static and non-sensitive: Plain environment variables or .env files suffice.
• You require advanced SSM features: Encrypted parameters, secure strings, or cross-account access may need custom IAM roles or SDK configurations not handled here.
• You’re on PHP <8.0: Use an older version or migrate to supported PHP.
• You need local development support: The package is Lambda-only; local Laravel dev environments will require a fallback (e.g., .env.local).

How to Pitch It (Stakeholders)

For Executives: "This package lets us securely manage secrets in AWS SSM Parameter Store—like a digital vault for API keys, passwords, and configs—without manual setup. It’s a turnkey solution for our Bref-based PHP serverless apps, reducing security risks and DevOps overhead. Since it’s maintained by the Bref team and MIT-licensed, we avoid vendor lock-in while gaining compliance-ready secret management. It also simplifies multi-environment deployments (dev/staging/prod) by centralizing secrets in SSM. Estimated cost: $0 (open-source); ROI: fewer leaks, easier audits, and faster deployments."

For Engineering: *"We’re adding bref/secrets-loader to replace hardcoded env vars with SSM-backed secrets in our Bref/Laravel stack. Here’s why:

• Zero code changes: Just prefix env vars in serverless.yml (e.g., DB_PASSWORD=bref-ssm:/app/db/password).
• No cold-start penalty: Async SSM fetching (v2.x) avoids blocking Lambda initialization.
• Laravel-friendly: Works alongside .env files by overriding values at runtime (e.g., APP_KEY from SSM).
• Future-proof: Supports PHP 8.0–8.5 and aligns with Bref’s roadmap.
• Security: Secrets stay encrypted in SSM; IAM roles handle access automatically. Action: Add composer require bref/secrets-loader and update serverless.yml. DevOps will configure SSM IAM permissions. For local dev, we’ll add a fallback to .env.local."*

For Security/Compliance: *"This replaces insecure secret storage (e.g., Git, .env files) with AWS SSM Parameter Store, which offers:

• Encryption at rest (KMS-backed).
• Versioning and audit logs (who accessed what, when).
• Automatic rotation (integrates with AWS Secrets Manager if needed). Risk: Minimal—package is auditable (MIT license) and uses AWS SDK under the hood. We’ll scope IAM roles to least privilege and monitor access via CloudTrail. For Laravel, we’ll clear config cache post-deployment to ensure SSM values take effect."*

For DevOps: *"This package automates SSM secret loading for Bref Lambdas, reducing manual steps:

• No more hardcoded secrets: Replace serverless.yml values with bref-ssm: prefixes.
• IAM simplified: Single policy for SSM access (no custom SDK layers).
• CI/CD friendly: Secrets can be managed via Terraform or AWS Console without redeploying. Action: Update Lambda execution roles to include SSM permissions and test in staging. For local dev, we’ll document a fallback process."*