Added more detailed upgrading docs (#340)

Author: GrahamCampbell

.gitattributes

@@ -7,3 +7,4 @@
 /.travis.yml export-ignore
 /phpunit.xml.dist export-ignore
 /README.md export-ignore
+/UPGRADING.md export-ignore

README.md

@@ -18,16 +18,16 @@ New in Version 3 is first-class support for multiline variables
 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 occurrences 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
-the loader will no longer be trimming values
+`Dotenv::create(...)`, since our new native constructor takes a `Loader`
+instance now, so that it can be truly customized if required. Finally, one
+should note that the loader will no longer be trimming values
 ([#302](https://github.com/vlucas/phpdotenv/pull/302)), moreover
 `Loader::load()` and its callers now return an associative array of the
 variables loaded with their values, rather than an array of raw lines from the
 environment file ([#306](https://github.com/vlucas/phpdotenv/pull/306)).
 
 For more details, please see the
-[release notes](https://github.com/vlucas/phpdotenv/releases/tag/v3.0.0).
+[release notes](https://github.com/vlucas/phpdotenv/releases/tag/v3.0.0) and the [upgrading guide](UPGRADING.md).
 
 
 Why .env?

UPGRADING.md

@@ -0,0 +1,40 @@
+# Upgrading Guide
+
+## 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.
+
+`Loader::load()` and its callers now return an associative array of the variables loaded with their values.
+
+Value parsing has been modified in the following ways:
+
+1. For unquoted strings, as soon as there's a hash, it's treated as a comment start.
+2. We're being stricter about invalid escape sequences within quoted strings.
+3. We're no longer trimming the parsed values of quoted strings.
+4. Multiline quoted values are now permitted, and will be parsed by V3.
+
+| input value | V2.5.2 | V2.6.1 | V3.3.1 |
+|-|-|-|-|
+| `foo#bar` | `foo#bar` | `foo#bar` | `foo` |
+| `foo # bar` | `foo` | `foo` | `foo` |
+| `"iiiiviiiixiiiiviiii\n"` | silent failure | `iiiviiiixiiiiviiii\n` | fails with invalid escape sequence exception |
+| `"iiiiviiiixiiiiviiii\\n"` | `iiiiviiiixiiiiviiii\n` | `iiiiviiiixiiiiviiii\n` | `iiiiviiiixiiiiviiii\n` |
+| `"foo\"bar"` | `foo"bar` | `foo"bar` | `foo"bar` |
+| `"  foo "` | `foo` with whitespace trimmed | `foo` with whitespace trimmed | `foo` with 2 spaces in front and one after |
+
+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:
+
+```php
+<?php
+
+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();
+```