Update the limitations section (#288)

Author: theofidry

README.md

@@ -592,35 +592,39 @@ composer dump-autoload --working-dir build --classmap-authoritative
 
 There is 3 things to manage when dealing with isolated PHARs:
 
-- The dependencies: which dependencies are you shipping? Fine controlled ones managed
-  with a `composer.lock` or you always ship your application with up to date dependencies?
-- The PHAR format: there is some incompatibilities such as `realpath()` which will no
-  longer work for the files within the PHAR since the paths are not virtual.
-- Isolating the code: due to the dynamic nature of PHP, isolating your dependencies will
-  never be a trivial task and as a result you should have some end-to-end test to ensure
-  your isolated code is working properly. You will also likely need to configure the
-  [whitelists][whitelist] or [patchers][patchers].
-
-As a result, you _should_ have end-to-end tests for your (at the minimum) your released
-PHAR.
-
-Since dealing with the 3 issues mentioned above at once can be tedious, it is highly
-recommended to have several tests for each steps.
-
-For example you can have a test for both your non-isolated PHAR and your isolated PHAR,
-this way you will know which step is causing an issue. If the isolated PHAR is not working,
-you can try to test the isolated code directly outside the PHAR to make sure the scoping
-process is not the issue.
+- The dependencies: which dependencies are you shipping? Fine controlled ones 
+  managed with a `composer.lock` or you always ship your application with up 
+  to date dependencies?
+- The PHAR format: there is some incompatibilities such as `realpath()` which 
+  will no longer work for the files within the PHAR since the paths are not 
+  virtual.
+- Isolating the code: due to the dynamic nature of PHP, isolating your 
+  dependencies will never be a trivial task and as a result you should have
+  some end-to-end test to ensure your isolated code is working properly. You 
+  will also likely need to configure the [whitelists][whitelist] or 
+  [patchers][patchers].
+
+As a result, you _should_ have end-to-end tests for your (at the minimum) your 
+released PHAR.
+
+Since dealing with the 3 issues mentioned above at once can be tedious, it is
+highly recommended to have several tests for each steps.
+
+For example you can have a test for both your non-isolated PHAR and your 
+isolated PHAR, this way you will know which step is causing an issue. If the 
+isolated PHAR is not working, you can try to test the isolated code directly 
+outside the PHAR to make sure the scoping process is not the issue.
 
 To check if the isolated code is working correctly, you have a number of solutions:
 
-- When using PHP-Scoper directly, by default PHP-Scoper dump the files in a `build` directory.
-  Do not forget that
+- When using PHP-Scoper directly, by default PHP-Scoper dump the files in a 
+  `build` directory. Do not forget that
   [you need to dump the Composer autoloader for the isolated code to work!](#step-2-run-php-scoper).
-- When using [Box][box], you can use its `--debug` option from the `compile` command in order to have the
-  code shipped in the PHAR dumped in the `.box` directory.
-- When using a PHAR (created by [Box][box] or any other PHAR building tool), you can use the
-  [`Phar::extractTo()`][phar-extract-to] method.
+- When using [Box][box], you can use its `--debug` option from the `compile` 
+  command in order to have the code shipped in the PHAR dumped in the `.box` 
+  directory.
+- When using a PHAR (created by [Box][box] or any other PHAR building tool), 
+  you can use the [`Phar::extractTo()`][phar-extract-to] method.
 
 Also take into consideration that bundling code in a PHAR is not guaranteed to work
 out of the box either. Indeed there is a number of things such as 
@@ -630,42 +634,80 @@ For this reason, you should also h
 
 ## Limitations
 
-### PSR-0 support
+### Dynamic symbols
 
-With the following `composer.json` autoloading configuration:
+PHP-Scoper tries to prefix strings as well whenever possible. There will however be cases in which it will not be
+possible such as:
 
-```json
-{
-    "autoload": {
-        "psr-0": {
-            "Foo": "src/"
-        }
-    }
-}
-```
+- strings in regexps, e.g. `/^Acme\\\\Foo/`
+- concatenated strings strings, e.g.:
+    - `$class = 'Symfony\\Component\\'.$name;`
+    - `const X = 'Symfony\\Component' . '\\Yaml\\Ya_1';`
 
-If following PSR-0, with the expected file structure is:
 
-```
-src/
-    Foo/
-        A.php
-        B.php
-```
+### Heredoc values
+
+If you consider the following code:
+
+```php
+<?php
+
+<<<PHP_HEREDOC
+<?php
 
-However this also works:
+use Acme\Foo;
 
+PHP_HEREDOC;
 ```
-src/
-    Foo.php
+
+The content of `PHP_HEREDOC` will not be prefixed. Some partial support could be added in the future but is bound to
+be very limited due to the dynamic nature of heredocs. If you consider the following for example:
+
+```php
+<?php
+
+<<<EOF
+<?php
+
+{$namespaceLine}
+
+// This file has been auto-generated by the Symfony Dependency Injection Component for internal use.
+
+if (\\class_exists(\\Container{$hash}\\{$options['class']}::class, false)) {
+    // no-op
+} elseif (!include __DIR__.'/Container{$hash}/{$options['class']}.php') {
+    touch(__DIR__.'/Container{$hash}.legacy');
+    return;
+}
+
+if (!\\class_exists({$options['class']}::class, false)) {
+    \\class_alias(\\Container{$hash}\\{$options['class']}::class, {$options['class']}::class, false);
+}
+
+return new \\Container{$hash}\\{$options['class']}(array(
+    'container.build_hash' => '$hash',
+    'container.build_id' => '$id',
+    'container.build_time' => $time,
+), __DIR__.\\DIRECTORY_SEPARATOR.'Container{$hash}');
+
+EOF;
 ```
 
-This is unexpected as `Foo` is a file rather than a directory.
+It would be very hard to properly scope the relevant classes.
+
+
+### Callables
 
-PHP-Scoper supports PSR-0 by transforming the configuration into a PSR-4 configuration.
-However support a case like above would require to scan the file structure which would
-add a significant overhead besides being more complex. As a result PHP-Scoper do not
-support the exotic case above.
+If you consider the two following values:
+
+```php
+['Acme\Foo', 'bar'];
+'Acme\Foo::bar';
+```
+
+The classes used there will not be scoped. It should not be impossible to add
+support for it but it is currently not supported. See 
+[#286](https://github.com/humbug/php-scoper/issues/286).
 
 
 ### String values
@@ -689,13 +731,15 @@ prefixed. But there is bound to have confusing cases. For example:
   is no way to know if it is a class name or a random string except for a
   handful of methods:
 
+- `class_alias()`
+- `class_exists()`
+- `define()`
+- `defined()`
+- `function_exists()`
+- `interface_exists()`
 - `is_a()`
 - `is_subclass_of()`
-- `interface_exists()`
-- `class_exists()`
 - `trait_exists()`
-- `function_exists()`
-- `class_alias()`
 
 
 ### Native functions and constants shadowing
@@ -711,13 +755,17 @@ is_array([]);
 
 ```
 
-No use statement is used for the function `is_array`. This means that PHP will try to load the function `\Foo\is_array`
-and if fails to do so will fallback on `\is_array` (note that PHP does so only for functions and constants: not classes).
+No use statement is used for the function `is_array`. This means that PHP will 
+try to load the function `\Foo\is_array` and if fails to do so will fallback 
+on `\is_array` (note that PHP does so only for functions and constants: not 
+classes).
 
-In order to bring some performance optimisation, the call will nonetheless be prefixed in `\is_array`. This *will* break
-your code if you were relying on `\Foo\is_array` instead. This however should be _extremely_ rare, so if that happens
-you have two solutions: use a [patcher](#patchers) or simpler remove any ambiguity by making use of a use statement
-(which is unneeded outside of the context of prefixing your code):
+In order to bring some performance optimisation, the call will nonetheless be 
+prefixed in `\is_array`. This *will* break your code if you were relying on 
+`\Foo\is_array` instead. This however should be _extremely_ rare, so if that 
+happens you have two solutions: use a [patcher](#patchers) or simpler remove 
+any ambiguity by making use of a use statement (which is unneeded outside of 
+the context of prefixing your code):
 
 ```php
 <?php
@@ -752,21 +800,24 @@ const Y = 'bar';
 
 ### Composer Autoloader
 
-PHP-Scoper does not support prefixing the dumped Composer autoloader and autoloading files. This is why you have to
-manually dump the autoloader again after prefixing an application.
+PHP-Scoper does not support prefixing the dumped Composer autoloader and 
+autoloading files. This is why you have to manually dump the autoloader again 
+after prefixing an application.
 
 Note: when using Box, Box is able to take care of that step for you.
 
 
 ### Composer Plugins
 
-Composer plugins are not supported. The issue is that for [whitelisting symbols](#whitelist) PHP-Scoper relies on the
-fact that you should load the `vendor/scoper-autoload.php` file instead of `vendor/autoload.php` to trigger the loading
-of the right classes with their class aliases. However Composer does not do that and as a result interfaces such as
+Composer plugins are not supported. The issue is that for 
+[whitelisting symbols](#whitelist) PHP-Scoper relies on the fact that you 
+should load the `vendor/scoper-autoload.php` file instead of 
+`vendor/autoload.php` to trigger the loading of the right classes with their 
+class aliases. However Composer does not do that and as a result interfaces such as
 `Composer\Plugin\Capability\Capable` are prefixed but the alias is not registered. 
 
-This cannot be changed easily so for now when you are using an isolated version of Composer, you will need to use the
-`--no-plugins` option.
+This cannot be changed easily so for now when you are using an isolated version
+ of Composer, you will need to use the `--no-plugins` option.
 
 
 ## Contributing

src/PhpParser/NodeVisitor/StringScalarPrefixer.php

@@ -56,15 +56,15 @@
 final class StringScalarPrefixer extends NodeVisitorAbstract
 {
     private const SPECIAL_FUNCTION_NAMES = [
-        'is_a',
-        'is_subclass_of',
-        'interface_exists',
-        'class_exists',
-        'trait_exists',
-        'function_exists',
         'class_alias',
+        'class_exists',
         'define',
         'defined',
+        'function_exists',
+        'interface_exists',
+        'is_a',
+        'is_subclass_of',
+        'trait_exists',
     ];
 
     private $prefix;