> ## Documentation Index
> Fetch the complete documentation index at: https://docs.n3wmedia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Configuration

> Use a standard .env file for local credentials and keep sensitive settings out of committed framework files and release packages.

# Environment Configuration

FrankPHP adopts a standard `.env`-based configuration approach for credentials and environment-specific settings.

This is architecturally important for two reasons.

First, it improves security by keeping sensitive values out of general configuration files that are more likely to be copied, reused, or accidentally distributed. Second, it makes FrankPHP feel more familiar to developers coming from other modern PHP frameworks.

That does **not** mean FrankPHP needs to become dependency-heavy or over-engineered. The goal is still the same: explicit, readable configuration with no unnecessary complexity.

***

## Why use a `.env` file?

A `.env` file gives you one place to keep environment-specific values such as:

* database host
* database name
* database username
* database password
* mail credentials
* app environment flags
* timezone overrides

These values often differ between:

* local development
* staging
* production
* customer-specific installations

Keeping them separate from the framework’s general configuration makes it easier to move between environments without editing core configuration files each time.

***

## The security advantage

The biggest practical advantage is simple: **sensitive credentials are less likely to be exposed accidentally.**

Without a dedicated `.env` approach, there is a tendency to place secrets directly in `app/Config/config.php` or other framework files. That works, but it increases the chance that credentials are:

* copied into a release package
* committed into source history
* shared during support/debugging
* left in files that are reused as templates

Using a `.env` file reduces that risk.

<Warning>
  A `.env` file still needs to be treated carefully. It is a safer place for secrets, but it is not something that should be shipped to customers inside a release package unless you explicitly intend it.
</Warning>

***

## Why this aligns FrankPHP with other PHP frameworks

Most major PHP frameworks now separate environment-specific secrets from framework configuration.

That is not just a convention for convention’s sake. It solves a real operational problem: credentials and runtime settings change by environment, while framework code should remain stable.

Moving FrankPHP toward a standard `.env` pattern makes the framework more familiar to developers coming from the broader PHP ecosystem, while still preserving the FrankPHP philosophy of explicit code and minimal moving parts.

***

## Recommended file setup

A practical setup looks like this:

```text theme={null}
/yourproject
  /framework
    ...                 ← the framework itself, replaced wholesale on update
  /app
    /.env               ← local or server-specific secrets
    /env.example        ← safe template shipped with the framework
    /Config
      config.php        ← reads values from env
    /public
      index.php
```

### `.env`

Contains real credentials and environment-specific values.

Example:

```dotenv theme={null}
DB_HOST=localhost
DB_NAME=your_db_name
DB_USER=your_db_user
DB_PASS=your_db_password
APP_TIMEZONE=Europe/London
APP_NAME=My App
```

### `env.example`

Contains the same keys but with placeholder values.

This file **can** be distributed in the customer package because it acts as the setup template.

Example:

```dotenv theme={null}
DB_HOST=localhost
DB_NAME=your_db_name
DB_USER=your_db_user
DB_PASS=your_db_password
APP_TIMEZONE=Europe/London
APP_NAME=My App
```

<Note>
  The real `.env` file should normally stay local to the server or development machine. The `env.example` file is what you ship.
</Note>

***

## How FrankPHP uses it

The exact implementation stays simple.

FrankPHP does not need a third-party environment package to get the core benefit. A small internal loader is used:

1. read the `.env` file if it exists
2. parse `KEY=value` lines
3. place the values into `$_ENV` or a simple lookup array
4. let `app/Config/config.php` read from those values

That keeps the approach aligned with the framework’s design principles.

***

## What changes in practice

Instead of hardcoding credentials in `app/Config/config.php` as in the 1.0 release, that file becomes a normal configuration layer that reads from environment values.

Conceptually, the responsibility changes like this:

* `.env` holds secrets and environment-specific values
* `app/Config/config.php` maps those values into the framework configuration array
* the framework continues to read configuration in the usual way

This keeps FrankPHP explicit while improving separation of concerns.

***

## Release packaging reminder

Your release process needs to account for `.env`.

### Do not include

* `.env`

### Safe to include

* `env.example`

This is one of the reasons the release build process should be scripted. A build script can exclude `.env` automatically rather than relying on you to remember to delete it before creating a release package. The [Version Management feature](/features/version-management) enables exactly this sort of scripting to support release packaging without complexity.

***

## How to use this in practice

If your framework has been updated to support `.env`, the normal workflow becomes:

## Step 1: Copy the example file

Create a real `.env` based on the shipped template.

```bash theme={null}
cp app/env.example app/.env
```

## Step 2: Fill in the real credentials

Edit `app/.env` and add the correct values for the current environment.

## Step 3: Leave `app/Config/config.php` as framework configuration

Avoid editing it repeatedly just to swap credentials between environments.

## Step 4: Keep `.env` out of release packages

When publishing a GitHub Release, ship `env.example` but exclude `.env`.

***

## Conclusion

The move to `.env` is not about adding complexity. It is about keeping sensitive values in the right place and making FrankPHP easier to work with across local, staging, and production environments.

Done properly, it gives you:

* better separation of secrets from framework code
* safer release packaging
* cleaner configuration management
* a setup process that feels familiar to PHP developers

All while keeping the FrankPHP approach intact: explicit, dependency-light, and easy to reason about.