Whitelist global functions by default (#231)

Closes #226

Makefile

@@ -181,6 +181,15 @@ e2e_023: bin/php-scoper.phar fixtures/set023/vendor
 	php build/set023/main.php > build/set023/output
 	diff fixtures/set023/expected-output build/set023/output
 
+.PHONY: e2e_024
+e2e_024:	## Run end-to-end tests for the fixture set 024 — Whitelisting user functions registered in the global namespace
+e2e_024: bin/php-scoper.phar fixtures/set024/vendor
+	$(PHPNOGC) $(PHPSCOPER) add-prefix --working-dir=fixtures/set024 --output-dir=../../build/set024 --force --no-interaction --stop-on-failure --no-config
+	composer --working-dir=build/set024 dump-autoload
+
+	php build/set024/main.php > build/set024/output
+	diff fixtures/set024/expected-output build/set024/output
+
 
 .PHONY: tb
 BLACKFIRE=blackfire
@@ -261,6 +270,10 @@ fixtures/set023/vendor: fixtures/set023/composer.lock
 	composer --working-dir=fixtures/set023 install
 	touch $@
 
+fixtures/set024/vendor: fixtures/set024/composer.lock
+	composer --working-dir=fixtures/set024 install
+	touch $@
+
 composer.lock: composer.json
 	@echo composer.lock is not up to date.
 
@@ -294,6 +307,9 @@ fixtures/set021-composer/composer.lock: fixtures/set021-composer/composer.json
 fixtures/set023/composer.lock: fixtures/set023/composer.json
 	@echo fixtures/set023/composer.lock is not up to date.
 
+fixtures/set024/composer.lock: fixtures/set024/composer.json
+	@echo fixtures/set024/composer.lock is not up to date.
+
 bin/php-scoper.phar: bin/php-scoper src vendor scoper.inc.php box.json
 	$(BOX) compile
 	touch $@

README.md

@@ -40,6 +40,7 @@ potentially very difficult to debug due to dissimilar or unsupported package ver
     - [Whitelist][whitelist]
         - [Constants from the global namespace whitelisting](#constants-from-the-global-namespace-whitelisting)
         - [Classes & Constants whitelisting](#classes--constants-whitelisting)
+        - [Global user functions](#global-user-functions)
         - [Namespaces whitelisting](#namespaces-whitelisting)
 - [Building a scoped PHAR](#building-a-scoped-phar)
     - [With Box](#with-box)
@@ -132,6 +133,7 @@ return [
     'patchers' => [],                       // callable[]
     'whitelist' => [],                      // string[]
     'whitelist-global-constants' => true,   // bool
+    'whitelist-global-functions' => true,   // bool
 ];
 ```
 
@@ -322,6 +324,67 @@ post regarding the differences
 [here](https://stackoverflow.com/a/3193704/3902761)
 
 
+### Global user functions
+
+By default, functions declared by users in the global namespace are whitelisted:
+
+```php
+<?php declare(strict_types=1);
+
+// scoper.inc.php
+
+use Isolated\Symfony\Component\Finder\Finder;
+
+return [
+    'whitelist-global-functions' => true,
+];
+```
+
+So when you declare a function like so:
+
+```php
+<?php
+
+// No namespace: this is the global namespace
+
+if (!function_exists('dd')) {
+    function dd() {}
+}
+```
+
+The file will be scoped as usual in order to avoid any autoloading issue:
+
+```
+<?php
+
+namespace PhpScoperPrefix;
+
+if (!function_exists('PhpScoperPrefix\dd')) {
+    function dd() {...}
+}
+```
+
+And the following function which will serve as an alias will be
+declared in the `scoper-autoload.php` file:
+
+
+```php
+<?php
+
+// scoper-autoload.php @generated by PhpScoper
+
+$loader = require_once __DIR__.'/autoload.php';
+
+if (!function_exists('dd')) {
+    function dd() {
+        return \PhpScoperPrefix\dd(func_get_args());
+    }
+}
+
+return $loader;
+```
+
+
 ### Namespaces whitelisting
 
 If you want to be more generic and whitelist a whole namespace, you can

fixtures/set024/composer.json

@@ -0,0 +1,5 @@
+{
+    "require": {
+        "symfony/var-dumper": "^4.1"
+    }
+}

fixtures/set024/expected-output

@@ -0,0 +1,3 @@
+array:1 [
+  0 => "yo"
+]

fixtures/set024/main.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Acme;
+
+use function file_exists;
+
+if (file_exists($autoload = __DIR__ . '/vendor/scoper-autoload.php')) {
+    require_once $autoload;
+} else {
+    require_once __DIR__ . '/vendor/autoload.php';
+}
+
+dump('yo');

specs/binary/simple.php

@@ -19,6 +19,7 @@
         'prefix' => 'Humbug',
         'whitelist' => [],
         'whitelist-global-constants' => true,
+        'whitelist-global-functions' => true,
     ],
 
     'some statements made directly in the global namespace: wrap them in a namespace statement' => <<<'PHP'

specs/class-FQ.php

@@ -19,6 +19,7 @@
         'prefix' => 'Humbug',
         'whitelist' => [],
         'whitelist-global-constants' => true,
+        'whitelist-global-functions' => true,
     ],
 
     [

specs/class-const/global-scope-single-level-with-single-level-use-statement-and-alias.php

@@ -19,6 +19,7 @@
         'prefix' => 'Humbug',
         'whitelist' => [],
         'whitelist-global-constants' => true,
+        'whitelist-global-functions' => true,
     ],
 
     [

specs/class-const/global-scope-single-level-with-single-level-use-statement.php

@@ -19,6 +19,7 @@
         'prefix' => 'Humbug',
         'whitelist' => [],
         'whitelist-global-constants' => true,
+        'whitelist-global-functions' => true,
     ],
 
     [

specs/class-const/global-scope-single-level.php

@@ -19,6 +19,7 @@
         'prefix' => 'Humbug',
         'whitelist' => [],
         'whitelist-global-constants' => true,
+        'whitelist-global-functions' => true,
     ],
 
     [