.travis.yml

@@ -13,11 +13,6 @@ php:
   - 7.3
   - hhvm
 
-matrix:
-  include:
-    - php: 5.3
-      dist: precise
-
 install: travis_retry composer install --no-interaction --prefer-source
 
 script: vendor/bin/phpunit

README.md

@@ -9,23 +9,37 @@ dotenv](https://github.com/bkeepers/dotenv).
 
 [![Build Status](https://travis-ci.org/vlucas/phpdotenv.svg?branch=master)](https://travis-ci.org/vlucas/phpdotenv)
 
+
+UPGRADING FROM V2
+-----------------
+
+New in Version 3 is first-class support for multiline variables
+([#301](https://github.com/vlucas/phpdotenv/pull/301)) and much more
+flexibility in terms of which parts of the environment we try to read and
+modify ([#300](https://github.com/vlucas/phpdotenv/pull/300)). Consequently,
+you will need to replace any occurences of `new Dotenv(...)` with
+`Dotenv::create(...)`, since our new native constructor takes loader instance
+now, so that it can be truly customized if required. Finally, one should note
+that starting from V3, the loader will no longer be trimming values
+([#302](https://github.com/vlucas/phpdotenv/pull/302)).
+
+
 Why .env?
 ---------
 **You should never store sensitive credentials in your code**. Storing
 [configuration in the environment](http://www.12factor.net/config) is one of
 the tenets of a [twelve-factor app](http://www.12factor.net/). Anything that is
 likely to change between deployment environments – such as database credentials
-or credentials for 3rd party services – should be extracted from the
-code into environment variables.
-
-Basically, a `.env` file is an easy way to load custom configuration
-variables that your application needs without having to modify .htaccess
-files or Apache/nginx virtual hosts. This means you won't have to edit
-any files outside the project, and all the environment variables are
-always set no matter how you run your project - Apache, Nginx, CLI, and
-even PHP 5.4's built-in webserver. It's WAY easier than all the other
-ways you know of to set environment variables, and you're going to love
-it.
+or credentials for 3rd party services – should be extracted from the code into
+environment variables.
+
+Basically, a `.env` file is an easy way to load custom configuration variables
+that your application needs without having to modify .htaccess files or
+Apache/nginx virtual hosts. This means you won't have to edit any files outside
+the project, and all the environment variables are always set no matter how you
+run your project - Apache, Nginx, CLI, and even PHP 5.4's built-in webserver.
+It's WAY easier than all the other ways you know of to set environment
+variables, and you're going to love it!
 
 * NO editing virtual hosts in Apache or Nginx
 * NO adding `php_value` flags to .htaccess files
@@ -84,14 +98,14 @@ SECRET_KEY="abc123"
 You can then load `.env` in your application with:
 
 ```php
-$dotenv = new Dotenv\Dotenv(__DIR__);
+$dotenv = Dotenv\Dotenv::create(__DIR__);
 $dotenv->load();
 ```
 
 Optionally you can pass in a filename as the second parameter, if you would like to use something other than `.env`
 
 ```php
-$dotenv = new Dotenv\Dotenv(__DIR__, 'myconfig');
+$dotenv = Dotenv\Dotenv::create(__DIR__, 'myconfig');
 $dotenv->load();
 ```
 
@@ -136,10 +150,26 @@ If you want Dotenv to overwrite existing environment variables, use `overload`
 instead of `load`:
 
 ```php
-$dotenv = new Dotenv\Dotenv(__DIR__);
+$dotenv = Dotenv\Dotenv::create(__DIR__);
 $dotenv->overload();
 ```
 
+### Loader Customization
+
+Need us to not set `$_ENV` but not `$_SERVER`, or have other custom requirements? No problem! Simply pass a custom implementation of `Dotenv\Environment\FactoryInterface` to `Dotenv\Loader` on construction. In practice, you may not even need a custom implementation, since our default implementation allows you provide an array of `Dotenv\Environment\Adapter\AdapterInterface` for proxing the underlying calls to.
+
+For example, if you want us to only ever fiddle with `$_ENV` and `putenv`, then you can setup Dotenv as follows:
+
+```php
+$factory = new Dotenv\Environment\DotenvFactory([
+    new Dotenv\Environment\Adapter\EnvConstAdapter(),
+    new Dotenv\Environment\Adapter\PutenvAdapter(),
+]);
+
+$dotenv = Dotenv\Dotenv::create(__DIR__, null, $factory);
+```
+
+
 Requiring Variables to be Set
 -----------------------------
 

composer.json

@@ -11,10 +11,11 @@
         }
     ],
     "require": {
-        "php": ">=5.3.9"
+        "php": "^5.4 || ^7.0",
+        "phpoption/phpoption": "^1.5"
     },
     "require-dev": {
-        "phpunit/phpunit": "^4.8.35 || ^5.0"
+        "phpunit/phpunit": "^4.8.35 || ^5.0 || ^6.0"
     },
     "autoload": {
         "psr-4": {
@@ -23,7 +24,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "2.5-dev"
+            "dev-master": "3.0-dev"
         }
     }
 }

src/Dotenv.php

@@ -2,104 +2,121 @@
 
 namespace Dotenv;
 
+use Dotenv\Environment\DotenvFactory;
+use Dotenv\Environment\FactoryInterface;
 use Dotenv\Exception\InvalidPathException;
 
 /**
  * This is the dotenv class.
  *
  * It's responsible for loading a `.env` file in the given directory and
- * setting the environment vars.
+ * setting the environment variables.
  */
 class Dotenv
 {
     /**
-     * The file path.
+     * The loader instance.
      *
-     * @var string
+     * @var \Dotenv\Loader
      */
-    protected $filePath;
+    protected $loader;
 
     /**
-     * The loader instance.
+     * Create a new dotenv instance.
+     *
+     * @param \Dotenv\Loader $loader
      *
-     * @var \Dotenv\Loader|null
+     * @return void
      */
-    protected $loader;
+    public function __construct(Loader $loader)
+    {
+        $this->loader = $loader;
+    }
 
     /**
      * Create a new dotenv instance.
      *
-     * @param string $path
-     * @param string $file
+     * @param string|string[]                           $paths
+     * @param string|null                               $file
+     * @param \Dotenv\Environment\FactoryInterface|null $envFactory
      *
-     * @return void
+     * @return \Dotenv\Dotenv
+     */
+    public static function create($paths, $file = null, FactoryInterface $envFactory = null)
+    {
+        $loader = new Loader(
+            self::getFilePaths((array) $paths, $file ?: '.env'),
+            $envFactory ?: new DotenvFactory(),
+            true
+        );
+
+        return new self($loader);
+    }
+
+    /**
+     * Returns the full paths to the files.
+     *
+     * @param string[] $paths
+     * @param string   $file
+     *
+     * @return string
      */
-    public function __construct($path, $file = '.env')
+    private static function getFilePaths(array $paths, $file)
     {
-        $this->filePath = $this->getFilePath($path, $file);
-        $this->loader = new Loader($this->filePath, true);
+        return array_map(function ($path) use ($file) {
+            return rtrim($path, DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR.$file;
+        }, $paths);
     }
 
     /**
      * Load environment file in given directory.
      *
-     * @return array
+     * @throws \Dotenv\Exception\InvalidPathException|\Dotenv\Exception\InvalidFileException
+     *
+     * @return string[]
      */
     public function load()
     {
         return $this->loadData();
     }
 
     /**
-     * Load environment file in given directory, suppress InvalidPathException.
+     * Load environment file in given directory, silently failing if it doesn't exist.
      *
-     * @return array
+     * @throws \Dotenv\Exception\InvalidFileException
+     *
+     * @return string[]
      */
     public function safeLoad()
     {
         try {
             return $this->loadData();
         } catch (InvalidPathException $e) {
             // suppressing exception
-            return array();
+            return [];
         }
     }
 
     /**
      * Load environment file in given directory.
      *
-     * @return array
+     * @throws \Dotenv\Exception\InvalidPathException|\Dotenv\Exception\InvalidFileException
+     *
+     * @return string[]
      */
     public function overload()
     {
         return $this->loadData(true);
     }
 
-    /**
-     * Returns the full path to the file.
-     *
-     * @param string $path
-     * @param string $file
-     *
-     * @return string
-     */
-    protected function getFilePath($path, $file)
-    {
-        if (!is_string($file)) {
-            $file = '.env';
-        }
-
-        $filePath = rtrim($path, DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR.$file;
-
-        return $filePath;
-    }
-
     /**
      * Actually load the data.
      *
      * @param bool $overload
      *
-     * @return array
+     * @throws \Dotenv\Exception\InvalidPathException|\Dotenv\Exception\InvalidFileException
+     *
+     * @return string[]
      */
     protected function loadData($overload = false)
     {
@@ -121,10 +138,10 @@ public function required($variable)
     /**
      * Get the list of environment variables declared inside the 'env' file.
      *
-     * @return array
+     * @return string[]
      */
     public function getEnvironmentVariableNames()
     {
-        return $this->loader->variableNames;
+        return $this->loader->getEnvironmentVariableNames();
     }
 }

src/Environment/AbstractVariables.php

@@ -0,0 +1,84 @@
+<?php
+
+namespace Dotenv\Environment;
+
+/**
+ * This is the abstract variables implementation.
+ *
+ * Extend this as required, implementing "get", "set", and "clear".
+ */
+abstract class AbstractVariables implements VariablesInterface
+{
+    /**
+     * Are we immutable?
+     *
+     * @var bool
+     */
+    private $immutable;
+
+    /**
+     * Create a new environment variables instance.
+     *
+     * @param bool $immutable
+     *
+     * @return void
+     */
+    public function __construct($immutable)
+    {
+        $this->immutable = $immutable;
+    }
+
+    /**
+     * Determine if the environment is immutable.
+     *
+     * @return bool
+     */
+    public function isImmutable()
+    {
+        return $this->immutable;
+    }
+
+    /**
+     * Tells whether environment variable has been defined.
+     *
+     * @param string $name
+     *
+     * @return bool
+     */
+    public function has($name)
+    {
+        return !is_null($this->get($name));
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function offsetExists($offset)
+    {
+        return $this->has($offset);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function offsetGet($offset)
+    {
+        return $this->get($offset);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function offsetSet($offset, $value)
+    {
+        $this->set($offset, $value);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function offsetUnset($offset)
+    {
+        $this->clear($offset);
+    }
+}