[4.x]: Unexpected behavior when using CRAFT_DOTENV_PATH in bootstrap script

[AugustMiller]

What happened?

Description

We provide the CRAFT_DOTENV_PATH constant to help Craft find your project’s .env file. When defining this in an entry script, Craft attempts to write it as a directory.

The unified bootstrap script determines it by calling the $findConfigPath closure:

$dotenvPath = $findConfigPath('--dotenvPath', 'CRAFT_DOTENV_PATH') ?? "$rootPath/.env";

The $findConfigPath function attempts to load previous definitions of CRAFT_DOTENV_PATH (set with CLI flags, as a constant in an entry script, or as an environment variable), and discovers our value. Because a value is found, we skip the early return and proceed into $createFolder.

The !is_dir($path) check is insufficient to guard against existing files, and it attempts to use PHP’s mkdir() to create what it believes is supposed to be directory.

Steps to reproduce

1. Define CRAFT_DOTENV_PATH in your bootstrap script:

   define('CRAFT_DOTENV_PATH', CRAFT_BASE_PATH . '/.env');

You do not need to relocate your .env file—just set the constant ahead of the bootstrap script being evaluated, and it will trigger the error.

Expected behavior

Craft discovers our .env file and bootstraps normally.

Actual behavior

PHP calls mkdir() on that path and exits:

Warning: mkdir(): File exists in /var/www/html/vendor/craftcms/cms/bootstrap/bootstrap.php on line 32
Tried to create a folder at /var/www/html/.env, but could not.

Related Issues + Commits

• Feature request: ability to customize path to .env #11894
• e28fc5d

Craft CMS version

4.5.5 (But >=4.3.0 are likely affected)

PHP version

8.2.x

Operating system and version

macOS/Docker

Database type and version

MySQL

Image driver and version

No response

Installed plugins and versions

None!

[brandonkelly]

Fixed in Craft 4.5.6!