Replaced whitelists by allow lists

Author: GrahamCampbell

README.md

@@ -178,11 +178,11 @@ interpolating environment variables, we'll only read from `$_ENV`. Moreover, it
 will never replace any variables already set before loading the file.
 
 By means of another example, one can also specify a set of variables to be
-whitelisted. That is, only the variables in the whitelist will be loaded:
+allow listed. That is, only the variables in the allow list will be loaded:
 
 ```php
 $repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters()
-    ->whitelist(['FOO', 'BAR'])
+    ->allowList(['FOO', 'BAR'])
     ->make();
 
 $dotenv = Dotenv\Dotenv::create($repository, __DIR__);

UPGRADING.md

@@ -15,7 +15,7 @@ Release notes for 5.0.0 are available [here](https://github.com/vlucas/phpdotenv
 3. Scalar typehints have been added to the public interface.
 4. The parser now returns a result type instead of raising an exception. This change is strictly internal, and most users won't notice a differnce. The responsibility for rasising an exception has simply been shifted up to the caller.
 5. Adapters have been refactored again, with changes to the repositories. In particular, the repository builder has been tweaked. It now expects to be explicitly told if you want to use the default adapters or not, and expects individual readers and writers to be added, one by one. Similar changes have been applied to the store factory. Moreover, the `ApacheAdapter` has been changed so that it behaves much like the other adapters. The old behaviour can be simulated by composing it with the new `ReplacingWriter` (see below). We will no longer include this adapter in our default setup, so that people can enable exactly what they need. Finally, by default, we will no longer be using the `PutenvAdapter`. It can be added, as required.
-6. Variable whitelisting has moved from the loader to be a responsibility of the repository, implemented via a special adapter.
+6. Variable whitelisting has been replaced with allow listing, and the responsibility has moved from the loader to a new adapter `GuardedWriter`.
 7. The parser has been moved to its own namespace and parses entire files now. This change is expected to have little impact when upgrading. The `Lines` class has also moved to the parser namespace.
 8. The loader now only returns the variables that were actually loaded into the repository, and not all the variables from the file. Moreover, it now expects as input the result of running the new parser (an array of entries), rather than raw file content.
 

src/Repository/Adapter/WhitelistWriter.php renamed to src/Repository/Adapter/GuardedWriter.php

@@ -4,7 +4,7 @@
 
 namespace Dotenv\Repository\Adapter;
 
-final class WhitelistWriter implements WriterInterface
+final class GuardedWriter implements WriterInterface
 {
     /**
      * The inner writer to use.
@@ -14,24 +14,24 @@ final class WhitelistWriter implements WriterInterface
     private $writer;
 
     /**
-     * The variable name whitelist.
+     * The variable name allow list.
      *
      * @var string[]
      */
-    private $whitelist;
+    private $allowList;
 
     /**
-     * Create a new whitelist writer instance.
+     * Create a new guarded writer instance.
      *
      * @param \Dotenv\Repository\Adapter\WriterInterface $writer
-     * @param string[]                                   $whitelist
+     * @param string[]                                   $allowList
      *
      * @return void
      */
-    public function __construct(WriterInterface $writer, array $whitelist)
+    public function __construct(WriterInterface $writer, array $allowList)
     {
         $this->writer = $writer;
-        $this->whitelist = $whitelist;
+        $this->allowList = $allowList;
     }
 
     /**
@@ -44,8 +44,8 @@ public function __construct(WriterInterface $writer, array $whitelist)
      */
     public function write(string $name, string $value)
     {
-        // Don't set non-whitelisted variables
-        if (!$this->isWhitelisted($name)) {
+        // Don't set non-allowed variables
+        if (!$this->isAllowed($name)) {
             return false;
         }
 
@@ -62,8 +62,8 @@ public function write(string $name, string $value)
      */
     public function delete(string $name)
     {
-        // Don't clear non-whitelisted variables
-        if (!$this->isWhitelisted($name)) {
+        // Don't clear non-allowed variables
+        if (!$this->isAllowed($name)) {
             return false;
         }
 
@@ -72,14 +72,14 @@ public function delete(string $name)
     }
 
     /**
-     * Determine if the given variable is whitelisted.
+     * Determine if the given variable is allowed.
      *
      * @param string $name
      *
      * @return bool
      */
-    private function isWhitelisted(string $name)
+    private function isAllowed(string $name)
     {
-        return \in_array($name, $this->whitelist, true);
+        return \in_array($name, $this->allowList, true);
     }
 }

src/Repository/RepositoryBuilder.php

@@ -11,7 +11,7 @@
 use Dotenv\Repository\Adapter\MultiWriter;
 use Dotenv\Repository\Adapter\ReaderInterface;
 use Dotenv\Repository\Adapter\ServerConstAdapter;
-use Dotenv\Repository\Adapter\WhitelistWriter;
+use Dotenv\Repository\Adapter\GuardedWriter;
 use Dotenv\Repository\Adapter\WriterInterface;
 use InvalidArgumentException;
 use PhpOption\Some;
@@ -51,28 +51,28 @@ final class RepositoryBuilder
     private $immutable;
 
     /**
-     * The variable name whitelist.
+     * The variable name allow list.
      *
      * @var string[]|null
      */
-    private $whitelist;
+    private $allowList;
 
     /**
      * Create a new repository builder instance.
      *
      * @param \Dotenv\Repository\Adapter\ReaderInterface[] $readers
      * @param \Dotenv\Repository\Adapter\WriterInterface[] $writers
      * @param bool                                         $immutable
-     * @param string[]|null                                $whitelist
+     * @param string[]|null                                $allowList
      *
      * @return void
      */
-    private function __construct(array $readers = [], array $writers = [], bool $immutable = false, array $whitelist = null)
+    private function __construct(array $readers = [], array $writers = [], bool $immutable = false, array $allowList = null)
     {
         $this->readers = $readers;
         $this->writers = $writers;
         $this->immutable = $immutable;
-        $this->whitelist = $whitelist;
+        $this->allowList = $allowList;
     }
 
     /**
@@ -158,7 +158,7 @@ public function addReader($reader)
 
         $readers = \array_merge($this->readers, \iterator_to_array($optional));
 
-        return new self($readers, $this->writers, $this->immutable, $this->whitelist);
+        return new self($readers, $this->writers, $this->immutable, $this->allowList);
     }
 
     /**
@@ -191,7 +191,7 @@ public function addWriter($writer)
 
         $writers = \array_merge($this->writers, \iterator_to_array($optional));
 
-        return new self($this->readers, $writers, $this->immutable, $this->whitelist);
+        return new self($this->readers, $writers, $this->immutable, $this->allowList);
     }
 
     /**
@@ -226,7 +226,7 @@ public function addAdapter($adapter)
         $readers = \array_merge($this->readers, \iterator_to_array($optional));
         $writers = \array_merge($this->writers, \iterator_to_array($optional));
 
-        return new self($readers, $writers, $this->immutable, $this->whitelist);
+        return new self($readers, $writers, $this->immutable, $this->allowList);
     }
 
     /**
@@ -236,19 +236,19 @@ public function addAdapter($adapter)
      */
     public function immutable()
     {
-        return new self($this->readers, $this->writers, true, $this->whitelist);
+        return new self($this->readers, $this->writers, true, $this->allowList);
     }
 
     /**
-     * Creates a repository builder with the given whitelist.
+     * Creates a repository builder with the given allow list.
      *
-     * @param string[]|null $whitelist
+     * @param string[]|null $allowList
      *
      * @return \Dotenv\Repository\RepositoryBuilder
      */
-    public function whitelist(array $whitelist = null)
+    public function allowList(array $allowList = null)
     {
-        return new self($this->readers, $this->writers, $this->immutable, $whitelist);
+        return new self($this->readers, $this->writers, $this->immutable, $allowList);
     }
 
     /**
@@ -265,8 +265,8 @@ public function make()
             $writer = new ImmutableWriter($writer, $reader);
         }
 
-        if ($this->whitelist !== null) {
-            $writer = new WhitelistWriter($writer, $this->whitelist);
+        if ($this->allowList !== null) {
+            $writer = new GuardedWriter($writer, $this->allowList);
         }
 
         return new AdapterRepository($reader, $writer);

tests/Dotenv/Loader/LoaderTest.php

@@ -32,10 +32,10 @@ public function testLoaderWithNoReaders()
         self::assertSame($expected, $loader->load($repository, (new Parser())->parse($content)));
     }
 
-    public function testLoaderWithWhitelist()
+    public function testLoaderWithAllowList()
     {
         $adapter = ArrayAdapter::create()->get();
-        $repository = RepositoryBuilder::createWithNoAdapters()->addReader($adapter)->addWriter($adapter)->whitelist(['FOO'])->make();
+        $repository = RepositoryBuilder::createWithNoAdapters()->addReader($adapter)->addWriter($adapter)->allowList(['FOO'])->make();
         $loader = new Loader();
 
         self::assertSame(['FOO' => 'Hello'], $loader->load($repository, (new Parser())->parse("FOO=\"Hello\"\nBAR=\"World!\"\n")));