Laravel Env Diff Laravel Package

Getting Started

• Install as a dev dependency so it never ships to production:

  composer require --dev romanzipp/laravel-env-diff
  

• On Laravel 5.5+ the service provider is auto-discovered. On older skeletons, register the provider from the package README in config/app.php.
• Publish the config on first install (2.0 changed and expanded it):

  php artisan vendor:publish --provider="RomanZipp\LaravelEnvDiff\EnvDiffServiceProvider"
  

• Confirm the command and its options in the version you installed:

  php artisan list | grep -i env
  php artisan env:diff --help
  

  The command is env:diff. In 2.0 use --values to print variable values in addition to key presence.
• First use case: after cloning a repo or pulling a branch that added variables, run php artisan env:diff and copy anything missing from .env.example into your local .env. Make it the first step in onboarding and your post-merge routine.

Implementation Patterns

• Configure the file set explicitly. In 2.0 the config uses a files array rather than additional_files, and the first file is compared against the second:

  // config/env-diff.php
  'files' => [
      '.env',
      '.env.example',
  ],
  'path' => base_path(),
  'show_values' => false,
  

  Verify the default path for your layout before assuming root-level .env files are found.
• Post-pull local check. Add a shell alias or Make target:

  alias envdiff='php artisan env:diff'
  

  Run it after git pull/composer update whenever .env.example changes. Treat .env.example as the source of truth and copy missing keys across.
• PR review guardrail. When a PR touches config, require that .env.example is updated. Reviewers run the diff locally or in CI to catch keys referenced in config/*.php that were never documented.
• CI gate. Wire the command into a job that has both files checked out (usually .env.example plus a generated .env). Confirm the exit-code behavior first; if differences do not return non-zero, capture output and fail explicitly:

  php artisan env:diff | tee env-diff.txt
  test ! -s env-diff.txt
  

• Deployment checklist. Before promoting a release, diff the incoming .env.example against the target environment's .env. This surfaces new keys that must be set in the deploy platform (Forge, Vapor, Kubernetes secrets) before the app boots.
• Alternate file pairs. Use the files array to compare non-default pairs in multi-environment setups:

  'files' => ['.env.staging', '.env.example'],
  

  Keep separate configs or wrap the command in a small script if you need several comparisons.
• Composer script hook. For teams that frequently forget, add to composer.json:

  "scripts": { "post-update-cmd": ["@php artisan env:diff"] }
  

  Keep it non-blocking locally; developers can skip with --no-scripts.
• Documentation sync. Use the diff output as a checklist when writing release notes or upgrade guides — "new env vars: X, Y, Z."

Gotchas and Tips

• 2.0 is a breaking config change. If upgrading from 1.0, additional_files is gone. Republish or edit the config to use files, add the new path key, and decide on show_values. Clear cached config after editing (php artisan config:clear); stale cached config can hide the new keys.
• Maintenance risk. The package has historically been lightly maintained. 2.0 adds Laravel 7 and PHP 7.4 support, but check composer.json constraints before installing on Laravel 9/10/11; you may need --ignore-platform-reqs, a fork, or to vendor the small command class manually.
• Pin the version and install with --dev. Do not let a stale package block a framework upgrade.
• path default may surprise you. The shipped default is app_path(), which is not the application root. If your .env files live at the project root, set path to base_path() and clear config cache before relying on the diff.
• Key presence only by default. The diff tells you which variables exist in one file but not the other; it does not validate values, types, or that required keys are non-empty. Use --values/show_values only when you need value visibility.
• Never enable value output in shared contexts. --values and show_values => true can leak secrets into CI logs, PR comments, or terminal scrollback. Keep show_values false in committed config and pass --values manually only in trusted local sessions.
• Noise from formatting. Comment lines, quoting differences, export prefixes, whitespace, and ordering can produce misleading diffs. Normalize files or filter output before failing CI.
• File availability. .env is gitignored, so the comparison only works where both files exist. In CI, generate .env from .env.example or provide a fixture before running the command.
• Exit codes. Confirm whether differences return non-zero. If not, don't assume && chaining will block a deploy — parse output explicitly.
• Extension points are minimal. There is no plugin surface worth relying on. For custom rules (per-environment required keys, ignored keys), wrap the command in a small custom Artisan command or shell script rather than patching the vendor package.