feat: customizable .env directory path

[totoprayogo1916]

Description
This PR restores the ability to set a custom .env file path, which was no longer possible after #8604 due to hardcoded handling in Boot.php.

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide

[michalsn]

Branch 4.7 was out of sync. Please rebase when you get a chance.

[totoprayogo1916]

Branch 4.7 was out of sync. Please rebase when you get a chance.

rebased

[michalsn]

While changing the .env file path was possible, it was more complicated.

I hope this option won't be abused to store the file in insecure places. Because, before we could be quite sure, it would be changed only by people who know what they're doing. However, from the other side, this is not the first voice from the community to make things easier in this area, so I suppose this is acceptable.

Let's see what others will say. We will need a changelog entry for this. I didn't see a dedicated page for Config\Paths in the user guide, so I think that should be sufficient.

[paulbalandan]

I think we should add a guard where the .env can be placed. I'm thinking it should not be outside ROOTPATH.

[totoprayogo1916]

I think we should add a guard where the .env can be placed. I'm thinking it should not be outside ROOTPATH.

How to do it?

[michalsn]

I'm thinking it should not be outside ROOTPATH.

What do you mean by that exactly?

From what I understand it, ROOTPATH is always one level above the app/ folder. In fact, when serving the application from a subfolder (like http://app.test/myapp), placing the .env file above ROOTPATH seems valid, since it keeps the file outside the web-accessible area.

I would be concerned about the .env file being placed below ROOTPATH, such as inside the myapp/ or myapp/public/ directory.

[paulbalandan]

Isn't the web-accessible path the PUBLICPATH?

In the following file structure:

|-- system/
|-- subA/
|   |--- app/
|   |--- public/
|   |__ .env
|
|__ subB/
    |-- app/
    |-- public/
    |__ .env

isn't the paths accessible subA/public/ and subB/public/? Then, I guess I misspoke earlier. Should the .env be placed anywhere other than PUBLICPATH?

[neznaika0]

I don't see any documentation updates or changelogs. If it looks unsafe, it's worth adding information about the consequences.
Also, not all dependencies have been updated. Example:

CodeIgniter4/system/Commands/Utilities/Environment.php

Line 134 in 4bf608d

private function writeNewEnvironmentToEnvFile(string $newEnv): bool

[michalsn]

@paulbalandan What I meant is that in an ideal setup, the domain points directly to the public/ folder - so everything above that (like .env) stays outside the web root and is safe.

But when serving the app from a subfolder (e.g. http://app.test/subA), the entire subA/ folder becomes web-accessible. In that case, if there's an .htaccess misconfiguration (or none at all), files like .env located in ROOTPATH or anywhere below it can be exposed.

From that perspective, everything from ROOTPATH downward is potentially unsafe unless explicitly protected.

[michalsn]

The proper documentation should be enough to warn users about the risks. I was looking at the user guide, and I believe this would be a good place for this: https://github.com/codeigniter4/CodeIgniter4/blob/develop/user_guide_src/source/general/managing_apps.rst

We can add a section dedicated to .env at the bottom.

Changing the Location of the .env File
======================================

If necessary, you can change the location of the ``.env`` file by adjusting the ``$envDirectory``
property in ``app/Config/Paths.php``.

By default, the framework loads environment settings from a ``.env`` file located one level above
the ``app/`` directory (in the ``ROOTPATH``). This is a safe location when your domain is correctly
pointed to the ``public/`` directory, as recommended.

In practice, however, some applications are served from a subdirectory (e.g., ``http://example.com/myapp``)
rather than from the main domain. In such cases, placing the ``.env`` file within the ``ROOTPATH`` may expose
sensitive configuration if ``.htaccess`` or other protections are misconfigured.

To avoid this risk in such setups, it is recommended to ensure the ``.env`` file is located outside any
web-accessible directories.

.. warning::

   If you change the location of the ``.env`` file, make absolutely sure it is not publicly accessible.
   Exposure of this file could lead to compromised credentials and access to critical services, such as your
   database, mail server, or third-party APIs.

[michalsn]

LGTM - we would need a changelog entry here: https://github.com/codeigniter4/CodeIgniter4/blob/4.7/user_guide_src/source/changelogs/v4.7.0.rst#enhancements

[paulbalandan]

Some grammatical improvements with help from Github Copilot.

[michalsn]

@totoprayogo1916 You can rebase one more time, to resolve Rector issues.

[michalsn]

@totoprayogo1916 Sorry, I missed that, but we still need a changelog entry here: https://github.com/codeigniter4/CodeIgniter4/blob/4.7/user_guide_src/source/changelogs/v4.7.0.rst (preferably under the "Changes" section).

Maybe something similar to this:

- **Paths:** Added support for changing the location of the ``.env`` file via the ``Paths::$envDirectory`` property.

[michalsn]

Thank you @totoprayogo1916