Download the PHP package code-distortion/fluent-dotenv without Composer

FluentDotEnv

code-distortion/fluent-dotenv is a wrapper with a fluent interface for new and old versions of vlucas/phpdotenv and symfony/dotenv, providing a common interface to easily read values from .env files.

Table of Contents

• Introduction
• Overview
• Installation
• Usage
  • Reading values from .env files
  • Filtering
  • Validation
  • Casting values
  • Calling order
  • Populating $_ENV and $_SERVER superglobals
  • Putenv() and getenv()
  • Picking vlucas/phpdotenv or symfony/dotenv
• Testing This Package
• Changelog
  • SemVer
• Treeware
• Contributing
  • Code of Conduct
  • Security
• Credits
• License

Introduction

.env files are an important tool as they allow for customisation of projects between environments.

The motivation behind this package is to provide a way to interact with the different versions of vlucas/phpdotenv or symfony/dotenv with a single interface.

This has been helpful for me when building packages that need to support a wide range of other packages.

First released in 2013, vlucas/phpdotenv by Vance Lucas and Graham Campbell is the most used PHP solution for loading values from .env files. Please have a look at their page for a more detailed description of what .env files are and why they're used.

symfony/dotenv was first released in 2017 as an alternative that's a part of Symfony framework family.

Overview

This package provides a new fluent interface for vlucas/phpdotenv and symfony/dotenv, and adds new features, including the ability to:

• Perform validation - make sure values are not empty, are integers, booleans, are limited to a specific set of values, match a regex or validate via a callback,
• Specify values to explicitly pick or ignore,
• Specify values that are required,
• Type casting to boolean or integer,
• Populate $_ENV and $_SERVER values if you like, choosing whether to override values that already exist or not.

Installation

Install the package via composer:

You must also include either vlucas/phpdotenv or symfony/dotenv in your project:

FluentDotEnv will automatically detect which of these dotenv packages are installed and use it. You can also choose explicitly if you like.

Usage

Reading values from .env files

NOTE: Over time, vlucas/phpdotenv and symfony/dotenv have improved the way they interpret values from .env files (e.g. multi-line variables). The underlying version of these package/s you use will determine how the .env values are interpreted.

Filtering

If you only want to load specific keys, you can specify them. Other values from your .env file will be ignored:

Conversely, particular keys can be ignored:

Validation

Validation can be applied to the values in an .env file. A CodeDistortion\FluentDotEnv\Exceptions\ValidationException exception will be thrown when a value fails validation:

Casting values

Values retrieved using get(…) or all(…) are returned as strings.

castBoolean(…) and castInteger(…) are available for convenience to retrieve values as booleans or integers (null will be returned when the values aren't "booleans" or integers).

Calling order

It doesn't matter which order you call the methods above in, they can be called before or after loading values from .env files. e.g.

NOTE: When you call populateEnv() or populateServer() after load() has been called, the $_ENV and $_SERVER arrays respectively will be updated straight away.

Populating $_ENV and $_SERVER superglobals

By default, the $_ENV and $_SERVER superglobals are not changed when loading .env values.

However, you can choose to populate them by calling populateEnv(…) and populateServer(…) respectively. e.g.

Putenv() and getenv()

The putenv(…) and getenv(…) functions are not thread-safe, which may cause issues in a multi-threaded environment. For this reason this functionality is not included in this package. You can read discussion about this here and here.

NOTE: If you're using symfony/dotenv, you may want to consider using version 5.1.0 or higher…

symfony/dotenv added an option to turn off the use of putenv() in version 5.1.0. FluentDotEnv uses this to make sure the environment variables don't get changed. However, in earlier versions putenv() is used without a way to turn it off.

FluentDotEnv hides this away, leaving your environment variables the same as they were before loading. But, it means that environment variables are changed temporarily during the ->load() process.

Picking vlucas/phpdotenv or symfony/dotenv

You need to include either vlucas/phpdotenv or symfony/dotenv in your project:

FluentDotEnv will try to use vlucas/phpdotenv first, then symfony/dotenv.

If you have both installed and want to be particular about which one is used, you can call useVlucasPhpDotEnv() or useSymfonyDotEnv() before calling load(). e.g.

If neither are found, a CodeDistortion\FluentDotEnv\Exceptions\DependencyException will be thrown.

Testing This Package

• Clone this package: git clone https://github.com/code-distortion/fluent-dotenv.git .
• Run composer install to install dependencies
• Run the tests: composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

SemVer

This library uses SemVer 2.0.0 versioning. This means that changes to X indicate a breaking change: 0.0.X, 0.X.y, X.y.z. When this library changes to version 1.0.0, 2.0.0 and so forth, it doesn't indicate that it's necessarily a notable release, it simply indicates that the changes were breaking.

Treeware

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Contributing

Please see CONTRIBUTING for details.

Code of Conduct

Please see CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Tim Chandler

License

The MIT License (MIT). Please see License File for more information.