Move env config to root .env and make app_local.php optional

[Chrishow2]

Summary

Moves environment configuration from config/.env to a root .env file, while keeping the stock CakePHP override layer optional.

• Root .env.example → .env (created on install); loaded by config/bootstrap.php
• config/app.php reads infrastructure values via env() (database, salt, app URLs, etc.)
• Installer writes SECURITY_SALT to .env instead of app_local.php
• app_local.php is no longer generated on install; developers can still copy config/app_local.example.php when they want PHP-level local overrides

Why

• Familiar layout — Root .env is what most PHP projects, Docker Compose setups, and deployment tools expect. config/.env is easy to overlook and differs from other ecosystems contributors already use.
• Clear separation — .env holds infrastructure/deployment variables; app_local.php remains the optional CakePHP layer for application tuning (debug defaults, datasource tweaks).
• Less config overlap — When install auto-created app_local.php with hardcoded datasource values, it could override or duplicate what app.php reads from the environment. Making app_local.php opt-in keeps .env → app.php as the default path.

Backwards compatibility / migration

Existing apps can move config/.env to .env and delete the old file. app_local.php continues to work if present. No change to bootstrap’s optional app_local load.

Verified

• Fresh install creates .env and replaces __SALT__
• App boots with .env only (no app_local.php)
• Manual copy of app_local.example.php → app_local.php still overrides config
• CI passes on the branch

[jamisonbryant]

While I'm a big fan of Tenet III of the 12-Factor pattern, this is a pretty big change to a file that hasn't changed in a major way since 2019. I don't think this can be part of v5, it might have to wait for v6.

There are other repos that would need a similar update:

• https://github.com/cakephp/app-api
• https://github.com/cakephp/app-tailwind
• https://github.com/cakephp/docs

Not to mention the countless tutorials and Docker images that reference the current location of the file.

What is the core problem you're trying to solve? If it's simply having environment variables defined and available in the root of your projects, direnv might be a solution worth looking into.

[dereuromark]

Maybe make this PR for 6.x
And we do a more mimimal adjustment for 5.x/5.next

[Chrishow2]

Thanks both, that makes sense.

@jamisonbryant For me it's the mismatch between Cake's skeleton (config/.env) and what most tooling expects at the project root (Docker Compose, CI env injection, and the convention most PHP devs know from other frameworks).

Agree the path change is too big for 5.x, and I hadn't fully accounted for the knock-on updates in app-api, app-tailwind, docs, and existing tutorials/Docker images. For 6.x I'm happy to include a migration note and help with the sibling repos if that's useful.

@dereuromark For 5.next, I could do a minimal slice separately (docs and .env.example clarity, or whatever you have in mind) while keeping the root move for 6.x.

Happy to retarget this PR or open a fresh one for 6.x, whichever you prefer.