Add an init command (#114)

Add an init command to generate a configuration file listing all the
configuration keys with their documentations.

While running the add-prefix command — provided the `--no-config` option
is not used, and no config file is found, the user will be prompted
a messager asking whether or not he wishes to generate the init command.

For now the init command provides a limited interactive experience as
little configuration is convenient to configure from the command line
in an easy way. We are also not entirely sure of how those configuration
will evolve before reaching a stable version.

Author: theofidry

Makefile

@@ -58,36 +58,43 @@ tc: vendor/bin/phpunit
 	phpdbg -qrr -d zend.enable_gc=0 $(PHPUNIT) --coverage-html=dist/coverage --coverage-text
 
 e2e:		## Run end-to-end tests
-e2e: e2e_004 e2e_005 e2e_011
+e2e: e2e_004 e2e_005 e2e_011 e2e_013
 
-e2e_004:	## Run end-to-end tests for the fixture set 004
+e2e_004:	## Run end-to-end tests for the fixture set 004: source code case
 e2e_004: bin/php-scoper.phar
-	php -d zend.enable_gc=0 $(PHPSCOPER) add-prefix --working-dir=fixtures/set004 --output-dir=../../build/set004 --force
+	php -d zend.enable_gc=0 $(PHPSCOPER) add-prefix --working-dir=fixtures/set004 --output-dir=../../build/set004 --force --no-config --no-interaction
 	composer --working-dir=build/set004 dump-autoload
 	php -d zend.enable_gc=0 -d phar.readonly=0 $(BOX) build -c build/set004/box.json.dist
 
 	php build/set004/bin/greet.phar > build/set004/output
 	diff fixtures/set004/expected-output build/set004/output
 
-e2e_005:	## Run end-to-end tests for the fixture set 005
+e2e_005:	## Run end-to-end tests for the fixture set 005: third-party code case
 e2e_005: bin/php-scoper.phar fixtures/set005/vendor
-	php -d zend.enable_gc=0 $(PHPSCOPER) add-prefix --working-dir=fixtures/set005 --output-dir=../../build/set005 --force
+	php -d zend.enable_gc=0 $(PHPSCOPER) add-prefix --working-dir=fixtures/set005 --output-dir=../../build/set005 --force --no-config --no-interaction
 	composer --working-dir=build/set005 dump-autoload
 	php -d zend.enable_gc=0 -d phar.readonly=0 $(BOX) build -c build/set005/box.json.dist
 
 	php build/set005/bin/greet.phar > build/set005/output
 	diff fixtures/set005/expected-output build/set005/output
 
-e2e_011:	## Run end-to-end tests for the fixture set 011
+e2e_011:	## Run end-to-end tests for the fixture set 011: whitelist case
 e2e_011: bin/php-scoper.phar fixtures/set011/vendor
-	php -d zend.enable_gc=0 $(PHPSCOPER) add-prefix --working-dir=fixtures/set011 --output-dir=../../build/set011 --force
+	php -d zend.enable_gc=0 $(PHPSCOPER) add-prefix --working-dir=fixtures/set011 --output-dir=../../build/set011 --force --no-interaction
 	cp -R fixtures/set011/tests build/set011/
 	composer --working-dir=build/set011 dump-autoload
 	php -d zend.enable_gc=0 -d phar.readonly=0 $(BOX) build -c build/set011/box.json.dist
 
 	php build/set011/bin/greet.phar > build/set011/output
 	diff fixtures/set011/expected-output build/set011/output
 
+e2e_013:	# Run end-to-end tests for the fixture set 013: the init command
+e2e_013: bin/php-scoper.phar
+	rm -rf build/set013
+	cp -R fixtures/set013 build/set013
+	$(PHPSCOPER) init --working-dir=build/set013 --no-interaction
+	diff src/scoper.inc.php.tpl build/set013/scoper.inc.php
+
 tb:		## Run Blackfire profiling
 tb: vendor
 	rm -rf build

README.md

@@ -44,7 +44,7 @@ potentially very difficult to debug due to dissimilar or unsupported package ver
 ## Installation
 
 
-### PHAR (preferred)
+### PHAR (preferred) [NOT SUPPORTED YET]
 
 The preferred method of installation is to use the PHP-Scoper PHAR, which can
 be downloaded from the most recent [Github Release](releases). Subsequent updates
@@ -103,8 +103,9 @@ PHP-Scoper's makefile.
 
 ## Configuration
 
-By default, PHP-Scoper will look for the file `scoper.inc.php` in the current
-working directory:
+If you need more granular configuration, you can create a `scoper.inc.php` by
+running the command `php-scoper init`. A different file/location can be passed
+with a `--config` option.
 
 ```php
 <?php declare(strict_types=1);

fixtures/set002/original/scoper.inc.php

@@ -0,0 +1,3 @@
+<?php
+
+return [];

fixtures/set002/scoped/scoper.inc.php

@@ -0,0 +1,3 @@
+<?php
+
+return [];

fixtures/set013/.gitkeep

@@ -1,7 +1,79 @@
 <?php
 
+declare(strict_types=1);
+
+use Isolated\Symfony\Component\Finder\Finder;
+
 return [
+    'global_namespace_whitelist' => [
+        'AppKernel',
+        function (string $className): bool {
+            return 'PHPUnit' === substr($className, 0, 6);
+        },
+    ],
+
+    // By default when running php-scoper add-prefix, it will prefix all relevant code found in the current working
+    // directory. You can however define which files should be scoped by defining a collection of Finders in the
+    // following configuration key.
+    //
+    // For more see: https://github.com/humbug/php-scoper#finders-and-paths
+    'finders' => [
+        Finder::create()->files()->in('src'),
+        Finder::create()
+            ->files()
+            ->ignoreVCS(true)
+            ->notName('/LICENSE|.*\\.md|.*\\.dist|Makefile|composer\\.json|composer\\.lock/')
+            ->exclude([
+                'doc',
+                'test',
+                'test_old',
+                'tests',
+                'Tests',
+                'vendor-bin',
+            ])
+            ->in('vendor'),
+        Finder::create()->append([
+            'composer.json',
+        ]),
+    ],
+
+    // 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
+    // heart contents.
+    //
+    // For more see: https://github.com/humbug/php-scoper#patchers
+    'patchers' => [
+        function (string $filePath, string $prefix, string $content): string {
+            // Change the content here.
+
+            return $content;
+        },
+    ],
+
+    // By default, PHP-Scoper only prefixes code where the namespace is non-global. In other words, non-namespaced
+    // code is not prefixed. This leaves the majority of classes, functions and constants in PHP - and most extensions,
+    // untouched.
+    //
+    // This is not necessarily a desirable outcome for vendor dependencies which are also not namespaced. To ensure
+    // they are isolated, you can configure the following which can be a list of strings or callables taking a string
+    // (the class name) as an argument and return a boolean (true meaning the class is going to prefixed).
+    //
+    // For more, see https://github.com/humbug/php-scoper#global-namespace-whitelisting
+    'global_namespace_whitelist' => [
+        'AppKernel',
+    ],
+
+    // PHP-Scoper's goal is to make sure that all code for a project lies in a distinct PHP namespace. However, you
+    // may want to share a common API between the bundled code of your PHAR and the consumer code. For example if
+    // you have a PHPUnit PHAR with isolated code, you still want the PHAR to be able to understand the
+    // PHPUnit\Framework\TestCase class.
+    //
+    // A way to achieve this is by specifying a list of classes to not prefix with the following configuration key. Note
+    // that this does not work with functions or constants neither with classes belonging to the global namespace.
+    //
+    // Fore more see https://github.com/humbug/php-scoper#whitelist
     'whitelist' => [
-        'Acme\Foo',
+        'PHPUnit\Framework\TestCase',
     ],
 ];

fixtures/set013/scoper.inc.php

@@ -15,12 +15,6 @@
 use Isolated\Symfony\Component\Finder\Finder;
 
 return [
-    'global_namespace_whitelist' => [
-        'AppKernel',
-        function (string $className): bool {
-            return 'PHPUnit' === substr($className, 0, 6);
-        },
-    ],
     'finders' => [
         Finder::create()->files()->in('src'),
         Finder::create()

scoper.inc.php

@@ -17,19 +17,18 @@
 use Humbug\PhpScoper\Console\Configuration;
 use Humbug\PhpScoper\Handler\HandleAddPrefix;
 use Humbug\PhpScoper\Logger\ConsoleLogger;
-use InvalidArgumentException;
-use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Exception\RuntimeException;
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Input\StringInput;
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Console\Style\OutputStyle;
 use Symfony\Component\Console\Style\SymfonyStyle;
 use Symfony\Component\Filesystem\Filesystem;
 use Throwable;
 
-final class AddPrefixCommand extends Command
+final class AddPrefixCommand extends BaseCommand
 {
     private const PATH_ARG = 'paths';
     private const PREFIX_OPT = 'prefix';
@@ -39,7 +38,6 @@ final class AddPrefixCommand extends Command
     private const CONFIG_FILE_OPT = 'config';
     private const CONFIG_FILE_DEFAULT = 'scoper.inc.php';
     private const NO_CONFIG_OPT = 'no-config';
-    private const WORKING_DIR_OPT = 'working-dir';
 
     private $fileSystem;
     private $handle;
@@ -60,6 +58,8 @@ public function __construct(Filesystem $fileSystem, HandleAddPrefix $handle)
      */
     protected function configure(): void
     {
+        parent::configure();
+
         $this
             ->setName('add-prefix')
             ->setDescription('Goes through all the PHP files found in the given paths to apply the given prefix to namespaces & FQNs.')
@@ -113,13 +113,6 @@ protected function configure(): void
                 ),
                 null
             )
-            ->addOption(
-                self::WORKING_DIR_OPT,
-                'd',
-                InputOption::VALUE_REQUIRED,
-                'If specified, use the given directory as working directory.',
-                null
-            )
         ;
     }
 
@@ -137,7 +130,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $this->validatePaths($input);
         $this->validateOutputDir($input, $io);
 
-        $config = $this->retrieveConfig($input, $io);
+        $config = $this->retrieveConfig($input, $output, $io);
 
         $logger = new ConsoleLogger(
             $this->getApplication(),
@@ -173,32 +166,6 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         return 0;
     }
 
-    private function changeWorkingDirectory(InputInterface $input): void
-    {
-        $workingDir = $input->getOption(self::WORKING_DIR_OPT);
-
-        if (null !== $workingDir) {
-            if (false === file_exists($workingDir)) {
-                throw new InvalidArgumentException(
-                    sprintf(
-                        'Could not change the working directory to "%s": directory does not exists.',
-                        $workingDir
-                    )
-                );
-            }
-
-            if (false === chdir($workingDir)) {
-                throw new RuntimeException(
-                    sprintf(
-                        'Failed to change the working directory to "%s" from "%s".',
-                        $workingDir,
-                        getcwd()
-                    )
-                );
-            }
-        }
-    }
-
     private function validatePrefix(InputInterface $input): void
     {
         $prefix = $input->getOption(self::PREFIX_OPT);
@@ -306,7 +273,7 @@ private function validateOutputDir(InputInterface $input, OutputStyle $io): void
         }
     }
 
-    private function retrieveConfig(InputInterface $input, OutputStyle $io): Configuration
+    private function retrieveConfig(InputInterface $input, OutputInterface $output, OutputStyle $io): Configuration
     {
         if ($input->getOption(self::NO_CONFIG_OPT)) {
             $io->writeln(
@@ -323,6 +290,13 @@ private function retrieveConfig(InputInterface $input, OutputStyle $io): Configu
             $configFile = $this->makeAbsolutePath(self::CONFIG_FILE_DEFAULT);
 
             if (false === file_exists($configFile)) {
+                $initCommand = $this->getApplication()->find('init');
+
+                $initInput = new StringInput('');
+                $initInput->setInteractive($input->isInteractive());
+
+                $initCommand->run($initInput, $output);
+
                 $io->writeln(
                     sprintf(
                         'Config file "<comment>%s</comment>" not found. Skipping.',

src/Console/Command/AddPrefixCommand.php

@@ -0,0 +1,68 @@
+<?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\Console\Command;
+
+use InvalidArgumentException;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Exception\RuntimeException;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+
+abstract class BaseCommand extends Command
+{
+    private const WORKING_DIR_OPT = 'working-dir';
+
+    /**
+     * @inheritdoc
+     */
+    protected function configure(): void
+    {
+        $this->addOption(
+            self::WORKING_DIR_OPT,
+            'd',
+            InputOption::VALUE_REQUIRED,
+            'If specified, use the given directory as working directory.',
+            null
+        );
+    }
+
+    final public function changeWorkingDirectory(InputInterface $input): void
+    {
+        $workingDir = $input->getOption(self::WORKING_DIR_OPT);
+
+        if (null === $workingDir) {
+            return;
+        }
+
+        if (false === file_exists($workingDir)) {
+            throw new InvalidArgumentException(
+                sprintf(
+                    'Could not change the working directory to "%s": directory does not exists.',
+                    $workingDir
+                )
+            );
+        }
+
+        if (false === chdir($workingDir)) {
+            throw new RuntimeException(
+                sprintf(
+                    'Failed to change the working directory to "%s" from "%s".',
+                    $workingDir,
+                    getcwd()
+                )
+            );
+        }
+    }
+}