Refactoring (#387)

Author: GrahamCampbell

README.md

@@ -10,6 +10,21 @@ 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 V3
+-----------------
+
+Version 4 seems some refactoring, and support for escaping dollars in values
+(https://github.com/vlucas/phpdotenv/pull/380). It is no longer possible to
+change immutability on the fly, and the `Loader` no longer is responsible for
+tracking immutability. It is now the responsibility of "repositories" to track
+this. One must explicitly decide if they want (im)mutability when constructing
+an instance of `Dotenv\Dotenv`.
+
+For more details, please see the
+[release notes](https://github.com/vlucas/phpdotenv/releases/tag/v4.0.0) and
+the [upgrading guide](UPGRADING.md).
+
+
 UPGRADING FROM V2
 -----------------
 
@@ -100,14 +115,14 @@ SECRET_KEY="abc123"
 You can then load `.env` in your application with:
 
 ```php
-$dotenv = Dotenv\Dotenv::create(__DIR__);
+$dotenv = Dotenv\Dotenv::createImmutable(__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 = Dotenv\Dotenv::create(__DIR__, 'myconfig');
+$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, 'myconfig');
 $dotenv->load();
 ```
 
@@ -143,34 +158,42 @@ CACHE_DIR="${BASE_DIR}/cache"
 TMP_DIR="${BASE_DIR}/tmp"
 ```
 
-### Immutability
+### Immutability and Repository Customization
 
-By default, Dotenv will NOT overwrite existing environment variables that are
-already set in the environment.
-
-If you want Dotenv to overwrite existing environment variables, use `overload`
-instead of `load`:
+Immutability refers to if Dotenv is allowed to overwrite existing environment
+variables. If you want Dotenv to overwrite existing environment variables,
+use `createMutable` instead of `createImmutable`:
 
 ```php
-$dotenv = Dotenv\Dotenv::create(__DIR__);
-$dotenv->overload();
+$dotenv = Dotenv\Dotenv::createMutable(__DIR__);
+$dotenv->load();
 ```
 
-### 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:
+Behind the scenes, this is instructing the "repository" to allow immutability
+or not. By default, the repository is configured to allow overwriting existing
+values by default, which is relevent if one is calling the "create" method
+using the `RepositoryBuilder` to construct a more custom repository:
 
 ```php
-$factory = new Dotenv\Environment\DotenvFactory([
-    new Dotenv\Environment\Adapter\EnvConstAdapter(),
-    new Dotenv\Environment\Adapter\PutenvAdapter(),
-]);
-
-$dotenv = Dotenv\Dotenv::create(__DIR__, null, $factory);
+$repository = Dotenv\Repository\RepositoryBuilder::create()
+    ->withReaders([
+        new Dotenv\Repository\Adapter\EnvConstAdapter(),
+    ])
+    ->withWriters([
+        new Dotenv\Repository\Adapter\EnvConstAdapter(),
+        new Dotenv\Repository\Adapter\PutenvAdapter(),
+    ])
+    ->immutable()
+    ->get();
+
+$dotenv = Dotenv\Dotenv::create($repository, __DIR__);
+$dotenv->load();
 ```
 
+The above example will write loaded values to `$_ENV` and `putenv`, but when
+interpolating environment variables, we'll only read from `$_ENV`. Moreover, it
+will never replace any variables already set before loading the file.
+
 
 Requiring Variables to be Set
 -----------------------------
@@ -305,11 +328,11 @@ PHP dotenv is licensed under [The BSD 3-Clause License](LICENSE).
 ---
 
 <div align="center">
-	<b>
-		<a href="https://tidelift.com/subscription/pkg/packagist-vlucas-phpdotenv?utm_source=packagist-vlucas-phpdotenv&utm_medium=referral&utm_campaign=readme">Get professional support for PHP dotenv with a Tidelift subscription</a>
-	</b>
-	<br>
-	<sub>
-		Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
-	</sub>
+    <b>
+        <a href="https://tidelift.com/subscription/pkg/packagist-vlucas-phpdotenv?utm_source=packagist-vlucas-phpdotenv&utm_medium=referral&utm_campaign=readme">Get professional support for PHP dotenv with a Tidelift subscription</a>
+    </b>
+    <br>
+    <sub>
+        Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
+    </sub>
 </div>

UPGRADING.md

@@ -1,5 +1,69 @@
 # Upgrading Guide
 
+## V3 to V4
+
+V4 has again changed the way you initialize the `Dotenv` class. If you want immutable loading of environment variables, then replace `Dotenv::create` with `Dotenv::createImmutable`, and if you want mutable loading, replace `Dotenv::create` with `Dotenv::createMmutable` and `->overload()` with `->load()`. The `overload` method has been removed in faviour of specifying mutability at object construction.
+
+The behaviour when parsing single quoted strings has now changed, to mimic the behaviour of bash. It is no longer possible to escape characters in single quoted strings, and everything is treated literally. As soon as the first single quote character is read, after the initial one, then the variable is treated as ending immediately at that point. When parsing unquoted or double quoted strings, it is now possible to escape dollar signs, to forcefully avoid variable interpolation. Escaping dollars is not mandated, in the sense that if a dollar is present, and not following by variable interpolation sytnax, this is allowed, and the dollar will be treated as a literal dollar. Finally, interpolation of variables is now performed right to left, instead of left to right, so it is possible to nest interpolations to allow using the value of a variable as the name of another for further interpolation.
+
+The `getEnvironmentVariableNames` method is no longer available. This is because calls to `load()` (since v3.0.0) return an associative array of what was loaded, so `$dotenv->getEnvironmentVariableNames()` can be replaced with `array_keys($dotenv->load())`.
+
+There have been various internal refactorings. Appart from what has already been mentioned, the only other changes likely to affect developers is:
+
+1. The `Dotenv\Environment` namespace has been moved to `Dotenv\Repository`, the `Dotenv\Environment\Adapter\AdapterInterface` interface has been replaced by `Dotenv\Repository\Adapter\ReaderInterface` and `Dotenv\Repository\Adapter\WriterInterface`.
+2. The `Dotenv\Environment\DotenvFactory` has been (roughly) replaced by `Dotenv\Environment\RepositoryBuilder`, and `Dotenv\Environment\FactoryInterface` has been deleted.
+3. `Dotenv\Environment\AbstractVariables` has been replaced by `Dotenv\Repository\AbstractRepository`, `Dotenv\Environment\DotenvVariables` has been replaced by `Dotenv\Repository\AdapterRepository`, and `Dotenv\Environment\VariablesInterface` has been replaced by `Dotenv\Repository\RepositoryInterface`.
+4. The `Dotenv\Loader` class has been moved to `Dotenv\Loader\Loader`, and now has a different public interface. It no longer expects any parameters at construction, and implements only the new interface `Dotenv\Loader\LoaderInterface`. Its reponsibility has changed to purely taking raw env file content, and handing it off to the parser, dealing with variable interpolation, and sending off instructions to the repository to set variables. No longer can it be used as a way to read the environment by callers, and nor does it track immutability.
+5. The `Dotenv\Parser` and `Dotenv\Lines` classes have moved to `Dotenv\Loader\Parser` and `Dotenv\Loader\Lines`, respectively. `Dotenv\Loader\Parser::parse` now return has either `null` or `Dotenv\Loader\Value` objects as values, instead of `string`s. This is to support the new variable interpolation and dollar escaping features.
+6. The `Dotenv\Validator` constructor has changed from `__construct(array $variables, Loader $loader, $required = true)` to `__construct(RepositoryInterface $repository, array $variables, $required = true)`.
+
+The example at the bottom of the below upgrading guide, in V4 now looks like:
+
+```php
+<?php
+
+use Dotenv\Dotenv;
+use Dotenv\Repository\Adapter\EnvConstAdapter;
+use Dotenv\Repository\Adapter\ServerConstAdapter;
+use Dotenv\Repository\RepositoryBuilder;
+
+$adapters = [
+	new EnvConstAdapter(),
+	new ServerConstAdapter(),
+];
+
+$repository = RepositoryBuilder::create()
+    ->withReaders($adapters)
+    ->withWriters($adapters)
+    ->immutable()
+    ->get();
+
+Dotenv::create($repository, $path, null)->load();
+```
+
+Since v3.2.0, it was easily possible to read a file and process variable interpolations, without actually "loading" the variables. This is still possible in v4.0.0. Example code that does this is as follows:
+
+```php
+<?php
+
+use Dotenv\Repository\Adapter\ArrayAdapter;
+use Dotenv\Repository\RepositoryBuilder;
+use Dotenv\Loader\Loader;
+
+$adapters = [new ArrayAdapter()];
+
+$repository = RepositoryBuilder::create()
+    ->withReaders($adapters)
+    ->withWriters($adapters)
+    ->get();
+
+$variables = (new Loader())->load($repository, $content);
+```
+
+Notice, that compared to v3, the loader no longer expects file paths in the constructor. Reading of the files is now managed by the `Dotenv\Dotenv` class. The loader is geuinely just loading the content into the repository.
+
+Finally, we note that the minimum supported version of PHP has increased to 5.5.9, up from 5.4.0 in V3 and 5.3.9 in V2.
+
 ## V2 to V3
 
 V3 has changed the way you initialize the `Dotenv` class. Consequently, you will need to replace any occurrences of new Dotenv(...) with Dotenv::create(...), since our new native constructor takes a `Loader` instance now.
@@ -24,17 +88,19 @@ Value parsing has been modified in the following ways:
 
 In double quoted strings, double quotes and backslashes need escaping with a backslash, and in single quoted strings, single quote and backslashes need escaping with a backslash. In v2.5.2, forgetting an escape can lead to odd results due to the regex running out of stack, but this was fixed in 2.6 and 3.3, with 2.6 allowing you to continue after an unescaped backslash, but 3.3 not.
 
-Finally, it's possible to use phpdotenv V3 in a threaded environment, instructing it to not call any functions that are not tread-safe:
+It's possible to use phpdotenv V3 in a threaded environment, instructing it to not call any functions that are not tread-safe:
 
 ```php
 <?php
 
+use Dotenv\Dotenv;
 use Dotenv\Environment\Adapter\EnvConstAdapter;
 use Dotenv\Environment\Adapter\ServerConstAdapter;
 use Dotenv\Environment\DotenvFactory;
-use Dotenv\Dotenv;
 
 $factory = new DotenvFactory([new EnvConstAdapter(), new ServerConstAdapter()]);
 
 Dotenv::create($path, null, $factory)->load();
 ```
+
+Finally, we note that the minimum supported version of PHP has increased from 5.3.9 to 5.4.0.