Add files whitelist feature (#262)

Closes #196

Author: theofidry

README.md

@@ -37,6 +37,7 @@ potentially very difficult to debug due to dissimilar or unsupported package ver
     - [Prefix](#prefix)
     - [Finders and paths](#finders-and-paths)
     - [Patchers](#patchers)
+    - [Whitelisted files](#whitelisted-files)
     - [Whitelist][whitelist]
         - [Constants & functions from the global namespace](#constants--functions-from-the-global-namespace)
         - [Symbols](#symbols)
@@ -135,6 +136,7 @@ return [
     'prefix' => null,                       // string|null
     'finders' => [],                        // Finder[]
     'patchers' => [],                       // callable[]
+    'whitelisted-files' => [],              // string[]
     'whitelist' => [],                      // string[]
     'whitelist-global-constants' => true,   // bool
     'whitelist-global-classes' => true,     // bool
@@ -262,6 +264,12 @@ return [
 ```
 
 
+### Whitelisted files
+
+For the files listed in `whitelisted-files`, their content will be left
+untouched during the scoping process.
+
+
 ### Whitelist
 
 PHP-Scoper's goal is to make sure that all code for a project lies in a 

src/Configuration.php

@@ -20,15 +20,22 @@
 use RuntimeException;
 use SplFileInfo;
 use Symfony\Component\Finder\Finder;
+use const DIRECTORY_SEPARATOR;
+use function dirname;
+use function gettype;
+use function is_array;
 use function is_bool;
+use function is_string;
+use function realpath;
 
 /**
  * @final
  * TODO: make this class as final as soon as the underlying deprecated class is removed.
  */
 class Configuration
 {
-    private const PREFIX = 'prefix';
+    private const PREFIX_KEYWORD = 'prefix';
+    private const WHITELISTED_FILES_KEYWORD = 'files-whitelist';
     private const FINDER_KEYWORD = 'finders';
     private const PATCHERS_KEYWORD = 'patchers';
     private const WHITELIST_KEYWORD = 'whitelist';
@@ -37,10 +44,13 @@ class Configuration
     private const WHITELIST_GLOBAL_FUNCTIONS_KEYWORD = 'whitelist-global-functions';
 
     private const KEYWORDS = [
-        self::PREFIX,
+        self::PREFIX_KEYWORD,
+        self::WHITELISTED_FILES_KEYWORD,
         self::FINDER_KEYWORD,
         self::PATCHERS_KEYWORD,
         self::WHITELIST_KEYWORD,
+        self::WHITELIST_GLOBAL_CONSTANTS_KEYWORD,
+        self::WHITELIST_GLOBAL_FUNCTIONS_KEYWORD,
         self::WHITELIST_GLOBAL_FUNCTIONS_KEYWORD,
     ];
 
@@ -49,6 +59,7 @@ class Configuration
     private $filesWithContents;
     private $patchers;
     private $whitelist;
+    private $whitelistedFiles;
 
     /**
      * @param string|null $path  Absolute path to the configuration file.
@@ -77,14 +88,16 @@ public static function load(string $path = null, array $paths = []): self
 
         $prefix = self::retrievePrefix($config);
 
+        $whitelistedFiles = null === $path ? [] : self::retrieveWhitelistedFiles(dirname($path), $config);
+
         $patchers = self::retrievePatchers($config);
         $whitelist = self::retrieveWhitelist($config);
 
         $finders = self::retrieveFinders($config);
         $filesFromPaths = self::retrieveFilesFromPaths($paths);
         $filesWithContents = self::retrieveFilesWithContents(chain($filesFromPaths, ...$finders));
 
-        return new self($path, $prefix, $filesWithContents, $patchers, $whitelist);
+        return new self($path, $prefix, $filesWithContents, $patchers, $whitelist, $whitelistedFiles);
     }
 
     /**
@@ -97,19 +110,22 @@ public static function load(string $path = null, array $paths = []): self
      * @param Closure            $globalNamespaceWhitelisters Closure taking a class name from the global namespace as an argument and
      *                                                        returning a boolean which if `true` means the class should be scoped
      *                                                        (i.e. is ignored) or scoped otherwise.
+     * @param string[]           $whitelistedFiles            List of absolute paths of files to completely ignore
      */
     private function __construct(
         ?string $path,
         ?string $prefix,
         array $filesWithContents,
         array $patchers,
-        Whitelist $whitelist
+        Whitelist $whitelist,
+        array $whitelistedFiles
     ) {
         $this->path = $path;
         $this->prefix = $prefix;
         $this->filesWithContents = $filesWithContents;
         $this->patchers = $patchers;
         $this->whitelist = $whitelist;
+        $this->whitelistedFiles = $whitelistedFiles;
     }
 
     public function withPaths(array $paths): self
@@ -127,20 +143,22 @@ public function withPaths(array $paths): self
             $this->prefix,
             array_merge($this->filesWithContents, $filesWithContents),
             $this->patchers,
-            $this->whitelist
+            $this->whitelist,
+            $this->whitelistedFiles
         );
     }
 
     public function withPrefix(?string $prefix): self
     {
-        $prefix = self::retrievePrefix([self::PREFIX => $prefix]);
+        $prefix = self::retrievePrefix([self::PREFIX_KEYWORD => $prefix]);
 
         return new self(
             $this->path,
             $prefix,
             $this->filesWithContents,
             $this->patchers,
-            $this->whitelist
+            $this->whitelist,
+            $this->whitelistedFiles
         );
     }
 
@@ -172,6 +190,14 @@ public function getWhitelist(): Whitelist
         return $this->whitelist;
     }
 
+    /**
+     * @return string[]
+     */
+    public function getWhitelistedFiles(): array
+    {
+        return $this->whitelistedFiles;
+    }
+
     private static function validateConfigKeys(array $config): void
     {
         array_map(
@@ -200,7 +226,7 @@ private static function validateConfigKey(string $key): void
      */
     private static function retrievePrefix(array $config): ?string
     {
-        $prefix = array_key_exists(self::PREFIX, $config) ? $config[self::PREFIX] : null;
+        $prefix = array_key_exists(self::PREFIX_KEYWORD, $config) ? $config[self::PREFIX_KEYWORD] : null;
 
         if (null === $prefix) {
             return null;
@@ -325,6 +351,46 @@ private static function retrieveWhitelist(array $config): Whitelist
         return Whitelist::create($whitelistGlobalConstants, $whitelistGlobalClasses, $whitelistGlobalFunctions, ...$whitelist);
     }
 
+    /**
+     * @return string[] Absolute paths
+     */
+    private static function retrieveWhitelistedFiles(string $dirPath, array $config): array
+    {
+        if (false === array_key_exists(self::WHITELISTED_FILES_KEYWORD, $config)) {
+            return [];
+        }
+
+        $whitelistedFiles = $config[self::WHITELIST_KEYWORD];
+
+        if (false === is_array($whitelistedFiles)) {
+            throw new InvalidArgumentException(
+                sprintf(
+                    'Expected whitelisted files to be an array of strings, found "%s" instead.',
+                    gettype($whitelistedFiles)
+                )
+            );
+        }
+
+        foreach ($whitelistedFiles as $index => $file) {
+            if (is_string($file)) {
+                throw new InvalidArgumentException(
+                    sprintf(
+                        'Expected whitelisted files to be an array of string, the "%d" element is not.',
+                        $index
+                    )
+                );
+            }
+
+            if ('' !== $file && DIRECTORY_SEPARATOR !== $file[0]) {
+                $file = $dirPath.DIRECTORY_SEPARATOR.$file;
+            }
+
+            $whitelistedFiles[$index] = realpath($file);
+        }
+
+        return array_filter($whitelistedFiles);
+    }
+
     private static function retrieveFinders(array $config): array
     {
         if (false === array_key_exists(self::FINDER_KEYWORD, $config)) {

src/Console/Command/AddPrefixCommand.php

@@ -18,6 +18,7 @@
 use Humbug\PhpScoper\Configuration;
 use Humbug\PhpScoper\Logger\ConsoleLogger;
 use Humbug\PhpScoper\Scoper;
+use Humbug\PhpScoper\Scoper\ConfigurableScoper;
 use Humbug\PhpScoper\Throwable\Exception\ParsingException;
 use Humbug\PhpScoper\Whitelist;
 use Symfony\Component\Console\Exception\RuntimeException;
@@ -30,6 +31,7 @@
 use Symfony\Component\Console\Style\SymfonyStyle;
 use Symfony\Component\Filesystem\Filesystem;
 use Throwable;
+use function count;
 use function Humbug\PhpScoper\get_common_path;
 
 final class AddPrefixCommand extends BaseCommand
@@ -55,7 +57,7 @@ public function __construct(Filesystem $fileSystem, Scoper $scoper)
         parent::__construct();
 
         $this->fileSystem = $fileSystem;
-        $this->scoper = $scoper;
+        $this->scoper = new ConfigurableScoper($scoper);
     }
 
     /**
@@ -133,6 +135,10 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $config = $this->retrieveConfig($input, $output, $io);
         $output = $input->getOption(self::OUTPUT_DIR_OPT);
 
+        if ([] !== $config->getWhitelistedFiles()) {
+            $this->scoper = $this->scoper->withWhitelistedFiles(...$config->getWhitelistedFiles());
+        }
+
         $logger = new ConsoleLogger(
             $this->getApplication(),
             $io

src/Scoper/ConfigurableScoper.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the humbug/php-scoper package.
+ *
+ * Copyright (c) 2017 Théo FIDRY <[email protected]>,
+ *                    Pádraic Brady <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Humbug\PhpScoper\Scoper;
+
+use Humbug\PhpScoper\Scoper;
+use Humbug\PhpScoper\Whitelist;
+
+final class ConfigurableScoper implements Scoper
+{
+    private $decoratedScoper;
+
+    public function __construct(Scoper $decoratedScoper)
+    {
+        $this->decoratedScoper = $decoratedScoper;
+    }
+
+    public function withWhitelistedFiles(string ...$whitelistedFiles): self
+    {
+        $self = clone $this;
+
+        return [] === $whitelistedFiles ? $self : new self(new FileWhitelistScoper($self));
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function scope(string $filePath, string $contents, string $prefix, array $patchers, Whitelist $whitelist): string
+    {
+        return $this->decoratedScoper->scope($filePath, $contents, $prefix, $patchers, $whitelist);
+    }
+}

src/Scoper/FileWhitelistScoper.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the humbug/php-scoper package.
+ *
+ * Copyright (c) 2017 Théo FIDRY <[email protected]>,
+ *                    Pádraic Brady <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Humbug\PhpScoper\Scoper;
+
+use Humbug\PhpScoper\Scoper;
+use Humbug\PhpScoper\Whitelist;
+use function array_flip;
+use function array_key_exists;
+
+final class FileWhitelistScoper implements Scoper
+{
+    private $decoratedScoper;
+    private $filePaths;
+
+    public function __construct(Scoper $decoratedScoper, string ...$filePaths)
+    {
+        $this->decoratedScoper = $decoratedScoper;
+        $this->filePaths = array_flip($filePaths);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function scope(string $filePath, string $contents, string $prefix, array $patchers, Whitelist $whitelist): string
+    {
+        if (array_key_exists($filePath, $this->filePaths)) {
+            return $contents;
+        }
+
+        return $this->decoratedScoper->scope($filePath, $contents, $prefix, $patchers, $whitelist);
+    }
+}

src/scoper.inc.php.tpl

@@ -33,6 +33,13 @@ return [
         ]),
     ],
 
+    // Whitelists a list of files. Unlike the other whitelist related features, this one is about completely leaving
+    // a file untouched.
+    // Paths are relative to the configuration file unless if they are already absolute
+    'files-whitelist' => [
+        'src/a-whitelisted-file.php',
+    ],
+
     // When scoping PHP files, there will be scenarios where some of the code being scoped indirectly references the
     // original namespace. These will include, for example, strings or string manipulations. PHP-Scoper has limited
     // support for prefixing such strings. To circumvent that, you can define patchers to manipulate the file to your