Laravel Env Keys Checker Laravel Package

Getting Started

• Install with composer require msamgan/laravel-env-keys-checker --dev. This is a development/CI guardrail, not a runtime dependency, so keep it out of production require.
• Confirm the service provider is auto-discovered (Laravel package discovery handles this); no manual registration should be needed unless you have discovery disabled.
• Publish the config if you need to customise paths or exclusions: php artisan vendor:publish --tag="env-keys-checker-config".
• Look first at the generated config/env-keys-checker.php — it is the single place that defines which files are compared and which keys are ignored. Everything else is convention.
• First use case: run the checker command against a repo where .env and .env.example have drifted, and use the reported diff to either add missing keys to .env.example or remove stale ones. This is the fastest way to understand the package's output format before wiring it into CI.

v2.0.0 note: the major version bump is driven by Laravel 13 compatibility. Treat the Laravel/PHP version constraints in composer.json as the thing to verify — a major bump here almost certainly means older Laravel (and possibly PHP) versions are no longer supported. Check the constraints before upgrading an app that is not yet on the latest Laravel line.

Implementation Patterns

Local pre-commit / manual check. Run the checker command as part of your normal dev loop after adding a new config value. The package is cheap to run and catches the common failure of adding env('FOO') usage without documenting FOO in .env.example.

CI gate. The highest-value pattern is a dedicated CI step that fails the build when keys drift. Put it in the same job as your test suite but as a separate step so the failure reason is unambiguous:

- run: composer install --no-interaction --prefer-dist
- run: php artisan env:keys:check

Pin the major version (^2.0) in composer.json so a future major bump does not silently land in CI via composer update.

Pair it with config-cache / fresh-install checks. A pattern that works well is running the checker once on a clean checkout (where .env is generated from .env.example) — that validates .env.example is actually sufficient to boot the app, which is a stronger guarantee than a diff of two files.

Composer script hook. Add a composer check script that chains the checker with Pint/PHPStan so contributors run it without remembering the command:

"scripts": {
    "check": ["@php artisan env:keys:check", "pint --test", "phpstan analyse"]
}

Multi-environment awareness. Keep the default .env / .env.example comparison for the main check, and use the config's path/exclusion options for repos that also ship .env.testing or .env.ci. Do not try to make one invocation cover every environment — separate invocations with separate config overrides are more readable.

Exclusion discipline. When a key legitimately differs (secrets, local-only overrides, keys injected by the host platform), add it to the exclusion list with a comment explaining why. Treat the exclusion list as technical debt: review it each time you bump the package.

Gotchas and Tips

• The v2 upgrade is the main risk right now. Because the release is essentially a Laravel 13 compatibility shift wrapped in a major version bump, the failure mode is a composer update that resolves fine locally but drops support for a Laravel version another service in your monorepo is still on. Read the composer.json constraints after upgrading rather than trusting the changelog summary.
• .env is usually gitignored. In CI there is often no .env at all, so the checker can fail for the wrong reason. Either generate .env from .env.example as a CI step, or scope the check to the environment where both files exist. This is the number-one source of confusing failures.
• Quoted, empty, and commented values. Keys commented out in .env.example may or may not be treated as present depending on the implementation. If you rely on commented placeholders as documentation, verify the checker's behaviour on your own files before gating CI on it.
• Ordering and whitespace noise. A naive line diff produces false positives on reordered keys or stray whitespace. If output looks wrong, inspect the raw files for CRLF line endings (common on Windows checkouts) — normalise .gitattributes before blaming the package.
• Extension points are thin by design. There is no plugin system; the config file (paths + exclusions) is the whole surface area. If you need bespoke rules (e.g. "keys used in config/*.php must be documented"), write a small custom command that wraps or complements this one rather than forking the package.
• Debugging a false negative. If the checker passes but the app breaks on a fresh install, the check is comparing the wrong pair of files (e.g. a stale local .env rather than a freshly generated one). Re-run in a clean checkout to confirm.
• Keep it in require-dev. Adding it to production require bloats your deploy artifacts and, on platforms that run composer install --no-dev, means it silently disappears from the environment where you most want consistency guarantees.
• Version pinning vs. churn. This package releases frequently with dependency bumps. ^2.0 is appropriate; * is not. If your CI is sensitive to surprise breakage, composer.lock plus scheduled, reviewed updates is the safer posture than auto-merging Dependabot PRs for a tool that gates your build.