Laravel Env Settings Laravel Package

Product Decisions This Supports

• Where non-secret configuration lives. This package lets you make a clean, defensible call: .env holds secrets and stock Laravel keys only; everything else (API base URLs, timeouts, queue names, model names, feature modes) moves into typed PHP classes under app/Settings, committed to git. That is a policy decision, not just a refactor — it changes what "configuration" means on the team.

• Environment expansion. Adding qa, uat, demo, or perf becomes a new factory method on a class (optionally annotated #[Environment('qa','uat')]), not a new vault path, a new .env.prod file, or a spreadsheet of per-environment variables. This directly de-risks the decision to add a pre-production tier — often the reason environments get skipped in the first place.

• Configuration drift as a budgeted bug class. env-settings:check --env=production fails the build when a value was never finished for an environment, and env-settings:show --all renders a matrix of how every environment differs. That converts "we shipped with the dev timeout" from an incident into a CI failure — a measurable reliability line item.

• Feature modes without a flag vendor. Enum-backed properties give you a small, typed, per-environment switch (e.g. mfa_mode, provider) with typo-proof values. This is enough for phased rollout and per-environment behavior, and lets you defer buying a feature-flag platform until you actually need audiences, percentage rollouts, or runtime toggles.

• Change management and audit evidence. Config changes land as pull requests with reviewers and git history, instead of as edits in a deploy-time secret store. For teams answering SOC 2 / ISO-style "who changed production config, and who approved it," this is a cheap, real control.

• Onboarding and developer support load. Gitignored per-developer overrides (app/Settings/Overrides/, gated by ENV_SETTINGS_OVERRIDE) let engineers point their machine at a sandbox without touching committed values or asking ops for a .env.

• Build vs. buy. Adoption cost is one Composer dependency, MIT-licensed, no infrastructure, no SaaS contract, no network calls at runtime. The real decision is not price — it is whether you accept a single-maintainer dependency in your config layer, or vendor/fork it and own ~a few classes of PHP.

When to Consider This Package

Adopt when most of these are true:

• Laravel application with (or about to have) three or more environments.
• Non-secret config has sprawled into .env: long URLs, comma lists, JSON blobs, magic strings duplicated across services.
• You have had, or fear, a config-drift incident; you want a build-time gate rather than a post-deploy discovery.
• The team already runs static analysis (PHPStan) and enforces types — the package leans on @phpstan-consistent-constructor and typed properties.
• You cache config in production (config:cache) or run Octane; the package resolves via app()->environment() and is cache-safe.
• Config values genuinely belong in code review, and secrets already live in a real secret manager.
• You are willing to pin the version and keep a fork path open.

Look elsewhere when:

• Secrets management is the actual pain. This package explicitly forbids secrets; it is not a vault. Reach for AWS Secrets Manager, Vault, or Doppler.
• You need runtime feature flags — targeting, percentages, experiments, kill switches without deploy. Use LaunchDarkly, Unleash, or Laravel Pennant.
• Non-engineers must edit settings at runtime (admin panel, per-tenant values, DB-backed settings). This package resolves per process environment, not per tenant or per request; use a DB-backed settings package instead.
• The app is small — one or two environments, a handful of values. Native config/*.php plus env vars is sufficient, and the extra abstraction is a net cost.
• You require vendor support, an SLA, or a large ecosystem. At 17 stars with a single maintainer, this is not a dependency to take casually into a regulated or long-lived codebase unless you can fork it.
• Values vary per tenant or per request, or you need hot-reload without a deploy — the environment-based resolution model does not fit.
• Version/PHP/Laravel constraints don't match your stack; verify before committing.

How to Pitch It (Stakeholders)

For executives (one paragraph): We currently treat .env as a general-purpose config store, which means production settings live outside code review, differ silently per environment, and are only validated after deploy. This package moves non-secret configuration into typed, version-controlled PHP classes that resolve automatically per environment, with a CLI that shows how environments differ and a CI check that fails the build when a value was never finished. Expected impact: fewer config-caused production incidents, faster onboarding of new environments (QA/UAT), and evidence of reviewed configuration changes for audits. Cost is a single MIT-licensed dependency, no new infrastructure, and roughly a sprint of engineering to migrate the highest-risk settings. The main risk is dependency maturity — it is a small, single-maintainer project — which we mitigate by piloting on one service, pinning the version, and confirming we can fork and maintain it if needed.

For engineering: This replaces scattered env() reads and ad-hoc .env keys with container-singleton settings classes resolved from APP_ENV at runtime, so it is config:cache-safe and works under Octane. It brings typed properties, enum-backed values with IDE autocomplete, #[Sensitive] masking in env-settings:show/diff, #[AllowEmpty] to suppress false positives, and env-settings:check as a CI gate. Secrets stay in .env and config() — this is explicitly not a secrets mechanism. Migration is incremental: create classes with env-settings:make, register them in config/env-settings.php, and convert config by blast radius, starting with the values that have caused incidents. The codebase surface is small enough to vendor if upstream goes quiet.

Recommendation: run a scoped pilot on one Laravel service with 3+ environments; success criteria are zero config-drift incidents in a quarter, env-settings:check wired into CI on the deploy branch, and one new environment added without a new secret store. Keep the real feature-flag and secrets decisions separate.