Laravel Secrets Loader Laravel Package

Getting Started

• Install with composer require eznix86/laravel-secrets-loader. Laravel auto-discovery registers the service provider; v0.3.1 adds an explicit test for composer-autoloader registration, so no manual provider entry is needed on standard Laravel versions.
• Publish the config file: php artisan vendor:publish --tag=secrets-loader-config. This is the first place to look—it defines adapters, secret mappings, and cache behaviour.
• Add adapter credentials to .env (e.g. AWS/GCP/Vault credentials) and set the default adapter in config/secrets-loader.php.
• First use case: map a secret such as database.connections.mysql.password to a remote secret path (e.g. prod/db/password). On boot the package fetches the value and injects it into config, keeping secrets out of source control.

Implementation Patterns

• Adapter-based loading: Each backend implements an adapter with a read method. Configure one or more adapters and map secret keys to Laravel config keys. Use the default adapter for most cases and named adapters for cross-cloud or migration scenarios.
• Config mapping workflow: Define mappings in config/secrets-loader.php as config.key => secret.path. The package loads them before the application uses config, so config('database.connections.mysql.password') resolves to the remote value.
• Environment-aware mappings: Use separate mapping arrays per environment (local, staging, production) and select via APP_ENV. Locally, skip remote loading or use a local adapter to avoid cloud calls.
• Caching for performance: Enable the package’s cache layer so secrets are fetched once per TTL instead of on every request. Pair this with Laravel’s cache store and clear it on secret rotation.
• Custom adapters: Implement the adapter contract for unsupported backends (e.g. 1Password, Doppler) and register the class in the config. This is the main extension point.
• Testing: Swap the adapter for a fake or mock in tests so feature tests do not require cloud credentials. Bind a stub implementation in the container or use an in-memory adapter.
• CI/CD integration: Provide adapter credentials as CI environment variables and run php artisan config:cache after secrets are loaded. This keeps deployment pipelines free of hard-coded secrets.

Gotchas and Tips

• Provider boot order: Secrets must be loaded before any provider that reads config in its register or boot method. If another package reads a secret-backed config value too early, it will see null. Register the secrets loader early or use a bootstrap step.
• Config caching: php artisan config:cache will bake resolved secrets into the cached config. Rotating a secret then requires php artisan config:clear (or a cache key change). For frequently rotated secrets, avoid caching the resolved values or use the package’s cache with a short TTL.
• v0.3.1 null-coalescing assignment: The adapter read method now uses ??= so an already-set config value is preserved. This is useful for local overrides but can mask a failed secret fetch. Check logs if a expected remote value is not applied.
• Missing secret behaviour: Decide whether a missing secret should throw, log, or fall back. The ??= change means an existing default will win silently—verify your mappings and adapter responses during debugging.
• Permissions: Adapter credentials need read access to the exact secret paths. IAM/Vault policies are a common source of “secret not found” errors; test with the cloud CLI first.
• Autoloader registration: v0.3.1’s test covers composer autoload registration, but if you disable package discovery (dont-discover), you must manually register the service provider.
• Debugging: Inspect config('secrets-loader') and the resolved config keys. Add temporary logging around the adapter or use php artisan tinker to call the loader manually. Avoid logging secret values.
• Secret formats: Some adapters return JSON blobs. Use the package’s key-path support or a small accessor to extract a single field rather than mapping the entire JSON string into config.