PHP dotenv 3.0 Released

Published on January 7th, 2019 by Paul Redmond

PHP dotenv released version 3.0 last week, with some “important improvements made to the library since the 2.x release.” At the same time, the package was able to maintain much of the same API from PHP dotenv 2.0.

Here are the new features as found in the v3.0.0 release notes:

More flexibility in terms of which parts of the environment we try to read and modify (#300)
First-class support for multiline variables (#301)
No more trimming of values. you get them exactly as is now (#302)
Accept a list of paths to try in order looking for the dotenv file, rather than a single path (#307)
Stronger validation of variable names to avoid silent failures or obscure errors (#311)

First, the way you’ll typically construct a PHP dotenv instance changes to a static constructor in v3. Here’s a snippet of the upcoming Laravel 5.8 code that initializes PHP dotenv:

Dotenv::create($app->environmentPath(), $app->environmentFile())->safeLoad();

If you have advanced needs, you can do some Loader customization with a custom implementation of the new Dotenv\Environment\FactoryInterface. If you want to learn more, I’d suggest you check out the latest readme and PR #300 for further details.

Next, multi-line support means that it’s now possible to define a variable that spans multiple lines:

MY_VARIABLE="value1
value2"

More interestingly, multi-line support and lack of trimming means that certificates, SSH keys, et al. will be consumed “as-is” without the need for pseudo newline characters.

Because v3 doesn’t trim strings anymore, you’ll want to review your projects that use PHP dotenv for any variables that might be affected by this change, including Laravel applications.

When will Laravel start using PHP dotenv 3.x?

Laravel 5.7 will stick with v2, and an upgrade to v3.0 is slated for Laravel 5.8’s release later this year.

Check out the release notes for full details on the code changes, upgrading, and what’s new.

A special thanks to Graham Campbell for leading the efforts on this release and incorporating v3 into Laravel, along with everyone else that contributed!