Download the PHP package hpwebdeveloper/laravel-env-settings without Composer

Laravel Env Settings

A typed configuration layer for non-secret values that differ between environments.

_{by Hamed Panjeh}

🚀 See how this package works in practice — try the live demo

A real Laravel application with worked examples: settings classes, per-environment values, local overrides, and the Artisan commands in action. The fastest way to understand the package before installing it.

💡 Why this exists — the problem it solves, and whether it's for you

Fifteen reasons, each one a before and an after: what belongs in .env, types instead of strings, staying correct at runtime, working with other people, and where this fits alongside other packages. Tick the ones you recognise — it reads as a diagnosis rather than a feature list.

Contents

• AI Assistants
• Requirements
• Installation
• Quick Start
  • 1. Generate
  • 2. Register
  • 3. Use it anywhere
• How resolution works
• Features
  • Fixed-value properties (enums)
  • Declaring environments on the class
  • Masking sensitive output
  • Local developer overrides
  • Composing settings into a root object
• Artisan Commands
  • env-settings:make
  • env-settings:check
  • env-settings:show
  • --all: every environment at once
  • env-settings:diff
• Full documentation
• Changelog
• Contributing
• Security
• Credits
• License

Most of a typical .env holds no secrets at all — API URLs, model names, timeouts, queue names, feature modes. Those belong in version control, where they are typed, reviewable in pull requests, and visible to your whole team. This package keeps .env for secrets and the stock Laravel keys, and puts everything your application adds on top into app/Settings.

AI Assistants

A published agent skill teaches Claude Code, Cursor, Codex and others how to work with this package — and the rule that matters most: secrets never go in a settings class. It is listed at skills.laravel.cloud:

The skill stands alone, so your agent can learn the package before it is installed. The same guidance also ships bundled, so php artisan boost:install offers it once the package is in your project.

Requirements

Every combination above is covered by the CI test matrix. The only runtime dependency is illuminate/support.

Installation

[!TIP] 📘 Follow the step-by-step setup guide on the demo → The same installation walked through in a real application, with the generated files shown at each step.

Quick Start

1. Generate

That writes app/Settings/AuthSettings.php with the structure in place and // TODO placeholders. Fill them in:

development() and production() are required. staging() and testing() fall back to development() — override them only when the values genuinely differ.

Property types: string, int, float, bool, array, or any enum.

A value that is the same everywhere goes in the signature, not in every factory. Give it a constructor default and write it once:

Generate that shape directly with --shared. PHP requires parameters with defaults to come last, so they collect at the end of the constructor.

2. Register

A settings class stays inert until it is listed in config/env-settings.php:

env-settings:make appends this line for you when the config has been published; if it can't, it prints exactly what to add. Each registered class becomes a container singleton, resolved once per request.

3. Use it anywhere

That's it. The correct environment is resolved automatically.

[!TIP] ▶️ Try it yourself in the browser → Switch environments and watch the resolved values change, without installing anything.

How resolution works

For the current APP_ENV, the package picks a factory in this order:

1. A method marked #[Environment] for that APP_ENV
2. The environment_map config (local → development, prod → production, …), then the raw APP_ENV value as a method name
3. fallback_environment (default: development)

It reads app()->environment() and config() — never env() — so it is fully compatible with php artisan config:cache.

[!TIP] 🔎 See this resolution happening live on the demo → The demo prints the current APP_ENV, the method it maps to, and the resulting instance.

Features

Each of these is covered in depth in the full guide.

Fixed-value properties (enums)

When a property only ever holds one of a few values, type it as an enum. A typo becomes a parse error, and the valid set is documented by the type:

Reading it gives you the case itself, so calling code branches exhaustively instead of comparing strings:

The enum defines which values are possible; the factories choose which one each environment uses. toArray() unwraps enums (backed → value, pure → case name), so JSON output keeps working. → details

Declaring environments on the class

environment_map lives in the application's config, so the same class can resolve differently in two applications. Mark the factory instead and the answer sits beside the code:

APP_ENV=demo, qa or uat now resolve with no config edit. → details

Masking sensitive output

Mark a property #[Sensitive] and both env-settings:show and env-settings:diff print ******** instead of its value:

Masking affects display only — toArray() still returns real values, and diff still flags the property with * when it differs. This is a safety net, not permission to store secrets here. → details

Local developer overrides

Individual developers can override values without touching committed code: set ENV_SETTINGS_OVERRIDE=true, add app/Settings/Overrides/AuthSettings.php extending the base class, and gitignore the directory. When overrides are off or the file is missing, the base class is used as normal. → details

Composing settings into a root object

A root class whose properties are other settings classes gives the whole configuration tree one entry point:

Register only the root. toArray() expands nested settings recursively, which makes a debug endpoint or health-check payload a one-liner. → details

Artisan Commands

env-settings:make

--shared takes name=value pairs. Each named property gets the value as a constructor default and is left out of the factories entirely, so it is written once instead of once per environment. Scalars only — an array or enum default cannot be expressed as one comma-separated argument, so those are refused rather than mangled into a class that will not parse.

A generated class only autoloads if its namespace matches where the file was written, so the namespace is resolved in this order: --namespace if given, otherwise derived from --path when that directory sits under the application root, otherwise config('env-settings.class_namespace'). A path outside the application root has no PSR-4 mapping to read, so it falls back to the default and warns — pass --namespace in that case. → full table

env-settings:check

Reports settings left at their generated placeholder, so a factory nobody finished cannot reach production:

Run it in CI, on the branch that deploys. It exits non-zero when anything is incomplete, which makes it a gate rather than a report:

It is a static check — it resolves your classes, touches no network and needs no production credentials — so it belongs in the build, alongside your tests, not in a deploy hook where a failure is already too late.

What counts as incomplete. A value equal to its generated placeholder ('', 0, 0.0, false, [], null) when another environment supplies a real one — the shape of a class where one factory was filled in and another forgotten. A value that is empty in every environment is deliberate and never reported. Any string containing TODO is always reported.

Mark a property #[AllowEmpty] when its empty value is intentional:

env-settings:show

--all: every environment at once

A settings class states every environment in one file — but show prints only the current one and diff only ever two, so four environments took six diff runs to compare. --all puts them in one table:

An unmarked row does not vary by environment, so it may not need to be a setting at all — that trailing count is the one thing this view tells you that no other command can.

Values are compared before masking, so a #[Sensitive] property is still marked * when it differs without being revealed.

env-settings:diff

Full documentation

📖 GUIDE.md — the complete reference, including:

• Testing settings classes
• Composing a wider tree and exporting it
• Configuring the override location (and why config:cache makes relative paths matter)
• The full environment_map and where generated classes live
• A worked AI/LLM example
• FAQ — how this differs from spatie/laravel-settings, and whether it violates 12-Factor

Changelog

See Releases for recent changes.

Contributing

Issues and pull requests are welcome on GitHub.

Security

Please review our security policy on how to report security vulnerabilities.

Credits

• Hamed Panjeh

License

The MIT License (MIT). See LICENSE for details.