Env Sync Laravel Laravel Package

Getting Started

This is a thin Laravel adapter around dragon-code/env-sync: the core package knows how to diff and reconcile .env files, and this package wires that into a service provider so you can drive it from Artisan (and potentially a facade) instead of a standalone binary.

Release 2.5.0 added Laravel 11 support, so the adapter is now viable on current apps — but the project is still archived with zero dependents, so treat the first ten minutes as reconnaissance rather than following a tutorial:

1. composer require dragon-code/env-sync-laravel — on Laravel 11 you want ^2.5. Check composer.json on GitHub first; with an archived package pin an explicit constraint rather than a ^ that could drag in a newer core env-sync.
2. Laravel package auto-discovery should register the service provider. If your app has discovery disabled, add the provider manually in config/app.php (Laravel 11: bootstrap/providers.php).
3. Run php artisan list | grep -i env to discover the exact command signature the adapter registers. Don't trust blog posts for this — the README and the command class in src/ are your source of truth.
4. Publish any config with php artisan vendor:publish --provider="DragonCode\..." (check the provider's boot() for the tag). Most likely this exposes the source/target filenames (.env.example → .env).
5. First use case: fresh clone where .env.example has keys your .env is missing. Copy the example, run the sync command, and confirm the missing keys are appended without your local values being clobbered. That single workflow is 90% of the package's value.

Look at, in order: the README, src/ServiceProvider.php (what's bound and registered), the command class (flags, dry-run support, exit codes), then the core env-sync source for parsing behavior. Also skim the 2.5.0 diff (PR #27) — "Laravel 11 support" usually means a widened illuminate/support constraint and possibly a provider registration tweak, not a rewrite.

Implementation Patterns

Onboarding automation. The canonical pattern is: .env.example is the committed contract, .env is local state. A new developer copies the example, and the sync command backfills keys that other developers added to their .env but forgot to mirror into the example. Wrap it in a Composer script so it's one command:

"scripts": {
  "post-install-cmd": ["@php artisan env:sync --ansi"]
}

Guard this — if the command errors in CI it shouldn't break composer install for everyone.

Deploy-time env generation. In a container build, run the sync against .env.example to materialize a complete .env, then let your secret manager overwrite the sensitive values. The adapter's value here is that you don't hand-maintain the key list in your Dockerfile — the example file is the schema.

CI drift check. The highest-leverage pattern for teams: run the sync in "check" mode (dry-run, if the command supports a --check / --dry-run flag — verify in the command class) and fail the pipeline when .env.example and your code's expected keys diverge. This catches the classic bug where config('services.foo.key') returns null in production because the key was added to .env but never documented in the example.

Example-first workflow. Establish the convention: adding a config key means (a) add to .env.example, (b) add the default to the config/*.php file, (c) reference via config(), never env() outside config files. Run sync to propagate to local .env. This is the only workflow where the package pays rent — without the convention, sync just shuffles lines.

Normalization for diffs. If the core supports sorting, use it to keep .env and .env.example in identical key order. Alphabetical, diff-friendly files mean code review of .env.example changes is actually readable and merge conflicts drop.

Pair with config:cache hygiene. Any script that mutates .env must run php artisan config:clear afterward (and config:cache in the deploy path), otherwise you'll debug a stale config for twenty minutes. On Laravel 11 this is doubly relevant — the default skeleton caches config aggressively in optimized deploys.

Programmatic use. If the adapter binds the core class into the container, you can inject it into your own Artisan command or a php artisan app:setup bootstrap command instead of shelling out. That's the cleaner extension point for custom setups (multiple env files, per-tenant configs).

Gotchas and Tips

• Archived is still the headline. 2.5.0 is a compatibility patch, not a revival — no security-fix promise, no Laravel 12 commitment, no maintainer on the hook. Read the core package's code before trusting it in a deploy pipeline; it's small, so an afternoon's audit is realistic. If it breaks, the fallback is either forking the adapter (it's likely a few dozen lines) or calling the core env-sync package directly without the Laravel sugar.
• Pin to ^2.5 on Laravel 11. Earlier 2.x lines predate the widened framework constraint and may resolve oddly or be blocked by dependency conflicts. If you're on Laravel 10 and stable, there is no reason to chase this bump.
• Direction matters for secrets. Sync should flow .env.example → .env (filling placeholders), never the reverse. If you ever find the command copying real values into .env.example, stop — that's a credential leak into git. Verify directionality on a throwaway repo before wiring it into anything automated.
• Empty placeholders get "filled" with something. Check whether a missing key is added as KEY= or with a default. On a fresh clone, an empty APP_KEY= will still break boot; you need php artisan key:generate in the same script.
• Parsing edge cases. Values containing #, spaces, =, quotes, or multiline content are where naive env parsers mangle files. Test with a value like PASSWORD="p@ss=word#1" before trusting it on a real project.
• Don't run it as a side effect in production boot. A service provider that syncs on every request is a disaster waiting to happen. Ensure the sync is command-driven only; check boot() for anything doing file I/O unconditionally — worth re-reading after the 2.5.0 provider change.
• Pin and lock. With zero dependents and no maintainer, add an explicit version in composer.json and commit composer.lock. Avoid ^ ranges that could pull a new core version.
• Exit codes. For CI use you need non-zero on drift. If the command returns 0 regardless, wrap it: capture output, grep for the "out of sync" marker, and exit 1 yourself.
• Extension points to reach for: the published config (target filenames, base path), and overriding the command via a subclass registered in your own provider. Both are cheaper than patching vendor code.
• Escape hatch. If anything smells wrong, dragon-code/env-sync standalone plus a five-line Composer script achieves the same result without the adapter layer — and one fewer archived dependency in your tree.