Laravel Env Security Laravel Package

Getting Started

Install and publish

composer require stechstudio/laravel-env-security
php artisan vendor:publish --provider="STS\EnvSecurity\EnvSecurityServiceProvider"

This gives you config/env-security.php — that file is the first thing to read, since it controls the key source, cipher, and the plaintext/encrypted filenames.

Set a key (not in the repo). Put it in your shell profile, your CI secret store, or your server's environment as ENV_SECURITY_KEY (or supply it at runtime with --key=). This key is separate from APP_KEY — mixing them up is the most common first-run mistake.

First use case — commit an encrypted .env:

php artisan env:encrypt          # writes the encrypted file (e.g. .env.encrypted)
git add .env.encrypted && git commit -m "Add encrypted env"
php artisan env:decrypt          # restores .env from it on a fresh clone

Make sure .env stays in .gitignore and only the encrypted artefact is tracked. The workflow you're buying is: small team, no secrets manager, config lives in git but isn't readable.

Implementation Patterns

Per-developer loop. Each dev keeps their own plaintext .env locally; the encrypted file is the shared source of truth. On clone: set ENV_SECURITY_KEY, run env:decrypt, run artisan migrate. Document this in the README next to the setup steps, because a failed decrypt looks like an app misconfiguration.

Deploy pipeline ordering. Decrypt before config:cache, or the cached config will be built from a stale/missing .env:

php artisan env:decrypt --key="$ENV_SECURITY_KEY"
php artisan config:cache
php artisan route:cache

Prefer --key="$SECRET" in CI over writing the key into a file on disk — but only if your CI masks it (see gotchas).

One encrypted file per environment. .env.encrypted on main, a separate stage/production file elsewhere (different filename via config, or per-branch). Keeping a single file that everyone decrypts means every dev holds production credentials locally — don't do that.

Pulling the key from a vault. Since the key is resolved through config, you can set it at boot in a service provider's register() (or a config override) to fetch from SSM/Secrets Manager/Vault instead of an env var. That keeps the artisan commands' ergonomics without hardcoding ENV_SECURITY_KEY on the box.

Key rotation. Re-encrypt with the new key, commit, roll the key out to CI and servers in the same window, then revoke the old one. Ciphertext diffs are whole-file rewrites, so expect a noisy commit — that's normal, not corruption.

Gotchas and Tips

• 3.0 is a compatibility bump, not a feature release. The only change is Laravel 13.x support. Practically: if you're on Laravel 13 you need ^3.0; if you're on Laravel 10/11, stay on ^2.4 — 3.0 may have dropped those constraints. Nothing in your application code should need to change; treat it as a composer update + full test-suite run, and check the PHP minimum as well.
• The encrypted file is only as strong as the key. --key="$SECRET" in a script run with -v, or an un-masked CI variable, leaks everything in one log line. Mask the secret and avoid echoing the command.
• env:decrypt overwrites .env. On a machine that already has a working local .env, this silently replaces it with the committed environment's values. Back up or use a separate checkout.
• CRLF will corrupt payloads. If Windows contributors check out the encrypted file with core.autocrlf=true, decryption fails with a useless error. Add a .gitattributes entry forcing LF for the encrypted file.
• Wrong key vs. wrong cipher look identical. If decrypt fails, verify (a) it's ENV_SECURITY_KEY, not APP_KEY, (b) the cipher in config matches what it was encrypted with, (c) the key encoding (raw vs. base64) hasn't changed between environments.
• Stale config cache is the classic post-deploy bug. After rotating the encrypted file, config:cache must re-run; otherwise the app keeps booting with the old values and you'll debug the wrong layer.
• This is not a secrets manager. It's a convenience for keeping env config in git with a shared key. Once you have per-service credentials, audit requirements, or more than a handful of people with the key, move to Vault/SSM/SOPS — the package won't scale past that.
• Extension points: the published config is the seam — override filenames, cipher, and key resolution there rather than forking. For non-standard key storage, bind your own resolver in a service provider instead of committing a key file.