Composer-specific source locator builder

.gitignore

@@ -1,4 +1,4 @@
 /.phpcs-cache
 /.phpunit.result.cache
 /phpcs.xml
-/vendor
+./vendor

composer.json

@@ -4,6 +4,7 @@
     "license": "MIT",
     "require": {
         "php": ">=7.2.0,<7.4.0",
+        "ext-json": "*",
         "jetbrains/phpstorm-stubs": "2019.1",
         "nikic/php-parser": "^4.0.4",
         "phpdocumentor/reflection-docblock": "^4.1.1",

docs/usage.md

@@ -118,6 +118,39 @@ $classInfo = ReflectionClass::createFromName('MyClass');
 $functionInfo = ReflectionFunction::createFromName('foo');
 ```
 
+### Inspecting code and dependencies of a composer-based project
+
+If you need to inspect code from a project that has a `composer.json` and
+its associated `vendor/` directory populated, this package offers some
+factories that ease the setup of the source locator. These are:
+
+ * `Roave\BetterReflection\SourceLocator\Type\Composer\Factory\MakeLocatorForComposerJsonAndInstalledJson` - if
+   you need to inspect project and dependencies
+ * `Roave\BetterReflection\SourceLocator\Type\Composer\Factory\MakeLocatorForComposerJson` - if you only want to
+   inspect project sources
+ * `Roave\BetterReflection\SourceLocator\Type\Composer\Factory\MakeLocatorForInstalledJson` - if you only want
+   to inspect project dependencies
+
+Here's an example of `MakeLocatorForComposerJsonAndInstalledJson` usage:
+
+```php
+<?php
+
+use Roave\BetterReflection\BetterReflection;
+use Roave\BetterReflection\Reflector\ClassReflector;
+use Roave\BetterReflection\SourceLocator\Type\AggregateSourceLocator;
+use Roave\BetterReflection\SourceLocator\Type\PhpInternalSourceLocator;
+use Roave\BetterReflection\SourceLocator\Type\Composer\Factory\MakeLocatorForComposerJsonAndInstalledJson;
+
+$astLocator = (new BetterReflection())->astLocator();
+$reflector  = new ClassReflector(new AggregateSourceLocator([
+    (new MakeLocatorForComposerJsonAndInstalledJson)('path/to/the/project', $astLocator),
+    new PhpInternalSourceLocator($astLocator)
+]));
+
+$classes = $reflector->getAllClasses();
+```
+
 ### Using the Composer autoloader directly
 
 ```php

src/SourceLocator/Type/Composer/Factory/Exception/Exception.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Roave\BetterReflection\SourceLocator\Type\Composer\Factory\Exception;
+
+use Throwable;
+
+interface Exception extends Throwable
+{
+}

src/SourceLocator/Type/Composer/Factory/Exception/FailedToParseJson.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Roave\BetterReflection\SourceLocator\Type\Composer\Factory\Exception;
+
+use UnexpectedValueException;
+use function sprintf;
+
+final class FailedToParseJson extends UnexpectedValueException implements Exception
+{
+    public static function inFile(string $file) : self
+    {
+        return new self(sprintf(
+            'Could not parse JSON file "%s"',
+            $file
+        ));
+    }
+}

src/SourceLocator/Type/Composer/Factory/Exception/InvalidProjectDirectory.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Roave\BetterReflection\SourceLocator\Type\Composer\Factory\Exception;
+
+use InvalidArgumentException;
+use function sprintf;
+
+final class InvalidProjectDirectory extends InvalidArgumentException implements Exception
+{
+    public static function atPath(string $path) : self
+    {
+        return new self(sprintf(
+            'Could not locate project directory "%s"',
+            $path
+        ));
+    }
+}

src/SourceLocator/Type/Composer/Factory/Exception/MissingComposerJson.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Roave\BetterReflection\SourceLocator\Type\Composer\Factory\Exception;
+
+use UnexpectedValueException;
+use function sprintf;
+
+final class MissingComposerJson extends UnexpectedValueException implements Exception
+{
+    public static function inProjectPath(string $path) : self
+    {
+        return new self(sprintf(
+            'Could not locate a "composer.json" file in "%s"',
+            $path
+        ));
+    }
+}

src/SourceLocator/Type/Composer/Factory/Exception/MissingInstalledJson.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Roave\BetterReflection\SourceLocator\Type\Composer\Factory\Exception;
+
+use UnexpectedValueException;
+use function sprintf;
+
+final class MissingInstalledJson extends UnexpectedValueException implements Exception
+{
+    public static function inProjectPath(string $path) : self
+    {
+        return new self(sprintf(
+            'Could not locate a "vendor/composer/installed.json" file in "%s"',
+            $path
+        ));
+    }
+}

src/SourceLocator/Type/Composer/Factory/MakeLocatorForComposerJson.php

@@ -0,0 +1,145 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Roave\BetterReflection\SourceLocator\Type\Composer\Factory;
+
+use Roave\BetterReflection\SourceLocator\Ast\Locator;
+use Roave\BetterReflection\SourceLocator\Type\AggregateSourceLocator;
+use Roave\BetterReflection\SourceLocator\Type\Composer\Factory\Exception\FailedToParseJson;
+use Roave\BetterReflection\SourceLocator\Type\Composer\Factory\Exception\InvalidProjectDirectory;
+use Roave\BetterReflection\SourceLocator\Type\Composer\Factory\Exception\MissingComposerJson;
+use Roave\BetterReflection\SourceLocator\Type\Composer\Psr\Psr0Mapping;
+use Roave\BetterReflection\SourceLocator\Type\Composer\Psr\Psr4Mapping;
+use Roave\BetterReflection\SourceLocator\Type\Composer\PsrAutoloaderLocator;
+use Roave\BetterReflection\SourceLocator\Type\DirectoriesSourceLocator;
+use Roave\BetterReflection\SourceLocator\Type\SingleFileSourceLocator;
+use Roave\BetterReflection\SourceLocator\Type\SourceLocator;
+use function array_filter;
+use function array_map;
+use function array_merge;
+use function file_exists;
+use function file_get_contents;
+use function is_array;
+use function is_dir;
+use function json_decode;
+use function realpath;
+
+final class MakeLocatorForComposerJson
+{
+    public function __invoke(string $installationPath, Locator $astLocator) : SourceLocator
+    {
+        $realInstallationPath = (string) realpath($installationPath);
+
+        if (! is_dir($realInstallationPath)) {
+            throw InvalidProjectDirectory::atPath($installationPath);
+        }
+
+        $composerJsonPath = $realInstallationPath . '/composer.json';
+
+        if (! file_exists($composerJsonPath)) {
+            throw MissingComposerJson::inProjectPath($installationPath);
+        }
+
+        $composer = json_decode((string) file_get_contents($composerJsonPath), true);
+
+        if (! is_array($composer)) {
+            throw FailedToParseJson::inFile($composerJsonPath);
+        }
+
+        $pathPrefix          = $realInstallationPath . '/';
+        $classMapPaths       = $this->prefixPaths($this->packageToClassMapPaths($composer), $pathPrefix);
+        $classMapFiles       = array_filter($classMapPaths, 'is_file');
+        $classMapDirectories = array_filter($classMapPaths, 'is_dir');
+        $filePaths           = $this->prefixPaths($this->packageToFilePaths($composer), $pathPrefix);
+
+        return new AggregateSourceLocator(array_merge(
+            [
+                new PsrAutoloaderLocator(
+                    Psr4Mapping::fromArrayMappings(
+                        $this->prefixWithInstallationPath($this->packageToPsr4AutoloadNamespaces($composer), $pathPrefix)
+                    ),
+                    $astLocator
+                ),
+                new PsrAutoloaderLocator(
+                    Psr0Mapping::fromArrayMappings(
+                        $this->prefixWithInstallationPath($this->packageToPsr0AutoloadNamespaces($composer), $pathPrefix)
+                    ),
+                    $astLocator
+                ),
+                new DirectoriesSourceLocator($classMapDirectories, $astLocator),
+            ],
+            ...array_map(static function (string $file) use ($astLocator) : array {
+                return [new SingleFileSourceLocator($file, $astLocator)];
+            }, array_merge($classMapFiles, $filePaths))
+        ));
+    }
+
+    /**
+     * @param mixed[] $package
+     *
+     * @return array<string, array<int, string>>
+     */
+    private function packageToPsr4AutoloadNamespaces(array $package) : array
+    {
+        return array_map(static function ($namespacePaths) : array {
+            return (array) $namespacePaths;
+        }, $package['autoload']['psr-4'] ?? []);
+    }
+
+    /**
+     * @param mixed[] $package
+     *
+     * @return array<string, array<int, string>>
+     */
+    private function packageToPsr0AutoloadNamespaces(array $package) : array
+    {
+        return array_map(static function ($namespacePaths) : array {
+            return (array) $namespacePaths;
+        }, $package['autoload']['psr-0'] ?? []);
+    }
+
+    /**
+     * @param mixed[] $package
+     *
+     * @return array<int, string>
+     */
+    private function packageToClassMapPaths(array $package) : array
+    {
+        return $package['autoload']['classmap'] ?? [];
+    }
+
+    /**
+     * @param mixed[] $package
+     *
+     * @return array<int, string>
+     */
+    private function packageToFilePaths(array $package) : array
+    {
+        return $package['autoload']['files'] ?? [];
+    }
+
+    /**
+     * @param array<string, array<int, string>> $paths
+     *
+     * @return array<string, array<int, string>>
+     */
+    private function prefixWithInstallationPath(array $paths, string $trimmedInstallationPath) : array
+    {
+        return array_map(function (array $paths) use ($trimmedInstallationPath) : array {
+            return $this->prefixPaths($paths, $trimmedInstallationPath);
+        }, $paths);
+    }
+
+    /**
+     * @param array<int, string> $paths
+     *
+     * @return array<int, string>
+     */
+    private function prefixPaths(array $paths, string $prefix) : array
+    {
+        return array_map(static function (string $path) use ($prefix) {
+            return $prefix . $path;
+        }, $paths);
+    }
+}