Conduit Env Manager Laravel Package

Getting Started

conduit-env-manager (v2.0.0) is a Conduit component that wraps .env file manipulation in four Artisan-style commands, so you stop hand-editing .env files and stop writing bespoke shell one-liners in deploy scripts.

Install — pick one path:

# If you're already using the Conduit component system
conduit components install env-manager

# Otherwise, plain Composer
composer require jordanpartridge/conduit-env-manager

Verify and look around first:

conduit list | grep env:          # confirm the four commands are registered
conduit env:get --all             # read-only smoke test, safe on any project

First real use case — a fresh clone or a new machine where .env doesn't exist yet:

conduit env:init
conduit env:get --all

env:init seeds .env from your template, which means your .env.example is now a load-bearing artifact rather than documentation. Treat keeping it current as part of your definition of done on any PR that adds a config key.

Start read-only (env:get), then move to env:set once you trust the output format. Every mutation should be preceded by env:backup until the workflow is proven in your environment.

Implementation Patterns

Onboarding / bootstrap. Replace the "copy .env.example to .env and ping someone for the values" ritual with env:init plus a short list of env:set calls for the local-only values:

conduit env:init
conduit env:set APP_NAME "My App"
conduit env:set APP_URL "http://localhost:8000"

Wrap this in a composer setup script or a Makefile target so new developers run one command.

Backup-then-mutate as the default discipline. The backup command is the most valuable of the four and the easiest to forget. Build the habit into the command itself:

conduit env:backup --name pre-deploy
conduit env:set DB_PASSWORD "$NEW_PASSWORD"

Named backups (--name pre-deploy) are far more useful than timestamps alone when you need to find the right restore point three weeks later — name them after the reason, not the date.

CI/CD provisioning. The --no-interaction, --json, and consistent exit codes make this the primary integration surface:

set -e
conduit env:init --no-interaction
conduit env:set APP_ENV production --no-interaction
conduit env:set APP_DEBUG false --no-interaction

Always pass --no-interaction. Without it, a prompt in a build container is a hung job, not an error.

Preflight checks and health scripts. env:get --all --json lets you assert required keys exist before a deploy or before booting a worker:

conduit env:get --all --json | jq -e '.APP_KEY and .DB_HOST' > /dev/null

Combine with set -e and let the exit code fail the pipeline. This is a much cheaper failure than a half-booted app.

Deploy hooks. In Envoy, Deployer, or a GitHub Actions step, run the backup before the release mutates anything and keep the artifact alongside your release directory:

conduit env:backup --name "release-$RELEASE_ID"

Bulk operations. Use --all for anything that needs the whole picture (auditing, diffing two environments, generating a report). Reserve single-key env:set calls for actual changes — bulk writes are harder to review and harder to roll back mentally.

Rotation workflow. For secret rotation, the sequence is: backup with a meaningful name → set the new value → php artisan config:clear → restart queue workers → verify with env:get. The package handles step one through three; the cache/worker steps are on you.

Gotchas and Tips

v2.0.0 is a complete rewrite — audit before upgrading. Command names, signatures, and behaviour all changed from the v1.x stub. Before bumping, grep your repo for anything that shells out to the old commands:

grep -rn "env:" composer.json Makefile .github/ deploy/ scripts/ 2>/dev/null

Also check composer.json scripts, Envoy tasks, Dockerfiles, and any custom Artisan commands that wrapped v1.

Masked values are a feature, not a bug to work around. env:get auto-hides anything matching PASSWORD, SECRET, KEY, TOKEN. If you find yourself needing the raw value in a script, you almost certainly want to read it from the runtime environment ($_ENV/getenv()) rather than scraping it back out of .env — that keeps the secret off stdout and out of CI logs. Don't build a workflow that depends on unmasking.

env:set writes files, not config. Laravel's config cache is a separate concern. After changing values that affect runtime behaviour, you still need php artisan config:clear (and a queue restart for long-running workers). Forgetting this produces the classic "I changed the password and it's still using the old one" bug hunt.

Shell quoting will bite you before the package does. Values with spaces, #, $, or quotes need care at the shell layer:

conduit env:set APP_NAME "My App"          # quote for the shell
conduit env:set APP_NAME '"My App"'        # quote for the .env file, if you need literal quotes

Use single quotes when the value contains $ or backticks, otherwise the shell interpolates before the package ever sees it.

Backups are files on disk — treat them as artifacts, not source. Decide early where they land and act accordingly: gitignore them, add retention/pruning to your deploy job, and never commit one. A directory of stale .env backups containing real credentials is a security problem, not just clutter.

.env is a single, unversioned file — there is no locking. Don't run parallel env:set calls against the same project (matrix CI jobs sharing a workspace, concurrent deploy hooks). Serialise those steps.

env:init on an existing project deserves a dry run. Initialisation from a template is safe on a missing file; against an existing .env you need to know whether it merges, skips, or overwrites before running it in anything but a throwaway environment. Test it once locally on a disposable checkout and note the behaviour in your runbook.

Validation covers names, not values. The package validates variable names — it won't tell you that APP_DEBUG=maybe is nonsense. Keep a php artisan config:show or a boot smoke test after scripted changes.

File permissions in containers. If CI runs as a different user than the one owning .env, writes will fail. The comprehensive error handling will surface it, but the fix is a chown/chmod in your image build, not a retry.

Exit codes are for scripting — actually use them. Every wrapper script should be set -e (or explicitly check $?) so a failed env:set halts the deploy rather than leaving .env half-written.