[path] Fix phpDocumentor template runtime fallbacks

Author: coisa

CHANGELOG.md

@@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Keep global `dev-tools:sync` runs machine-independent by removing only deprecated DevTools-managed Composer GrumPHP default-path metadata while wiring packaged Git hooks to prefer a project-local `grumphp.yml` and otherwise use the active packaged DevTools config path resolved at sync time (#288)
-- Complete global runtime binary fallback support for phpdoc, phpunit, and phpmetrics commands (#297)
+- Complete global runtime fallback support for phpdoc, phpunit, and phpmetrics commands, including packaged phpDocumentor templates used by `docs` and `wiki` (#297)
 
 ## [1.24.2] - 2026-04-30
 

src/Console/Command/DocsCommand.php

@@ -58,6 +58,11 @@ final class DocsCommand extends Command
     use HasJsonOption;
     use LogsCommandResults;
 
+    /**
+     * @var string the default phpDocumentor template path relative to the consumer project
+     */
+    private const string DEFAULT_TEMPLATE = 'vendor/fast-forward/phpdoc-bootstrap-template';
+
     /**
      * Creates a new DocsCommand instance.
      *
@@ -115,7 +120,7 @@ protected function configure(): void
                 name: 'template',
                 mode: InputOption::VALUE_OPTIONAL,
                 description: 'Path to the template directory for the generated HTML documentation.',
-                default: 'vendor/fast-forward/phpdoc-bootstrap-template',
+                default: self::DEFAULT_TEMPLATE,
             );
     }
 
@@ -137,6 +142,11 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $source = $this->filesystem->getAbsolutePath($input->getOption('source'));
         $target = $this->filesystem->getAbsolutePath($input->getOption('target'));
         $cacheDir = $this->filesystem->getAbsolutePath($input->getOption('cache-dir'));
+        $template = (string) $input->getOption('template');
+
+        if (self::DEFAULT_TEMPLATE === $template) {
+            $template = DevToolsPathResolver::getPreferredVendorPath(self::DEFAULT_TEMPLATE);
+        }
 
         $this->logger->info('Generating API documentation...', [
             'input' => $input,
@@ -151,7 +161,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $config = $this->createPhpDocumentorConfig(
             source: $source,
             target: $target,
-            template: $input->getOption('template'),
+            template: $template,
             cacheDir: $cacheEnabled ? $cacheDir : sys_get_temp_dir(),
         );
 

src/Console/Command/WikiCommand.php

@@ -55,6 +55,11 @@ final class WikiCommand extends Command
     use HasJsonOption;
     use LogsCommandResults;
 
+    /**
+     * @var string the default phpDocumentor Markdown template path relative to the consumer project
+     */
+    private const string DEFAULT_TEMPLATE = 'vendor/saggre/phpdocumentor-markdown/themes/markdown';
+
     /**
      * Creates a new WikiCommand instance.
      *
@@ -139,7 +144,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $processBuilder = $this->processBuilder
             ->withArgument('--ansi')
             ->withArgument('--visibility', 'public,protected')
-            ->withArgument('--template', 'vendor/saggre/phpdocumentor-markdown/themes/markdown')
+            ->withArgument('--template', DevToolsPathResolver::getPreferredVendorPath(self::DEFAULT_TEMPLATE))
             ->withArgument('--title', $this->composer->getDescription())
             ->withArgument('--target', $target);
 

src/Path/DevToolsPathResolver.php

@@ -128,6 +128,27 @@ public static function getRuntimeToolBinaryPath(string $binary, string $packageP
         return Path::join($packagePath, 'vendor', 'bin', $binary);
     }
 
+    /**
+     * Returns the active Composer vendor path for the current DevTools installation mode.
+     *
+     * Relative vendor paths MAY be passed either with or without a leading
+     * `vendor/` prefix.
+     *
+     * @param string $path the vendor-relative path to resolve
+     * @param string $packagePath an optional package root path; defaults to the current package root
+     */
+    public static function getRuntimeVendorPath(string $path, string $packagePath = ''): string
+    {
+        $packagePath = Path::canonicalize('' === $packagePath ? self::getPackagePath() : $packagePath);
+        $vendorPath = self::normalizeVendorRelativePath($path);
+
+        if (self::isInstalledAsDependency($packagePath)) {
+            return Path::canonicalize(Path::join($packagePath, '..', '..', $vendorPath));
+        }
+
+        return Path::join($packagePath, 'vendor', $vendorPath);
+    }
+
     /**
      * Returns the preferred tooling binary path for the active project and DevTools runtime.
      *
@@ -154,6 +175,33 @@ public static function getPreferredToolBinaryPath(
         return self::getRuntimeToolBinaryPath($binary, $packagePath);
     }
 
+    /**
+     * Returns the preferred Composer vendor path for the active project and DevTools runtime.
+     *
+     * Consumer projects SHOULD take precedence when they provide the requested
+     * vendor path locally. If the path is absent locally, the method MUST fall
+     * back to the active DevTools runtime vendor path.
+     *
+     * @param string $path the vendor-relative path to resolve
+     * @param string $projectPath an optional project root path; defaults to the working project root
+     * @param string $packagePath an optional package root path; defaults to the current package root
+     */
+    public static function getPreferredVendorPath(
+        string $path,
+        string $projectPath = '',
+        string $packagePath = '',
+    ): string {
+        $projectPath = '' === $projectPath ? WorkingProjectPathResolver::getProjectPath() : $projectPath;
+        $vendorPath = self::normalizeVendorRelativePath($path);
+        $projectVendorPath = Path::join($projectPath, 'vendor', $vendorPath);
+
+        if (file_exists($projectVendorPath)) {
+            return $projectVendorPath;
+        }
+
+        return self::getRuntimeVendorPath($vendorPath, $packagePath);
+    }
+
     /**
      * Detects whether the provided path belongs to an installed vendor copy of DevTools.
      *
@@ -175,4 +223,20 @@ public static function isRepositoryCheckout(string $packagePath = ''): bool
     {
         return ! self::isInstalledAsDependency($packagePath);
     }
+
+    /**
+     * Normalizes a path relative to the Composer vendor root.
+     *
+     * @param string $path the vendor-relative path to normalize
+     */
+    private static function normalizeVendorRelativePath(string $path): string
+    {
+        $path = Path::canonicalize($path);
+
+        if (str_starts_with($path, 'vendor/')) {
+            return substr($path, 7);
+        }
+
+        return $path;
+    }
 }

tests/Console/Command/DocsCommandTest.php

@@ -132,7 +132,14 @@ protected function setUp(): void
             ]);
         $this->composer->getName()
             ->willReturn('fast-forward/dev-tools');
-        $this->renderer->render('phpdocumentor.xml', Argument::type('array'))->willReturn('<phpdocumentor />');
+        $this->renderer->render(
+            'phpdocumentor.xml',
+            Argument::that(
+                static fn(array $context): bool => DevToolsPathResolver::getPreferredVendorPath(
+                    'vendor/fast-forward/phpdoc-bootstrap-template'
+                ) === $context['template']
+            )
+        )->willReturn('<phpdocumentor />');
         $this->processBuilder->withArgument(Argument::any())->willReturn($this->processBuilder->reveal());
         $this->processBuilder->withArgument(Argument::any(), Argument::any())->willReturn(
             $this->processBuilder->reveal()

tests/Console/Command/WikiCommandTest.php

@@ -130,6 +130,12 @@ protected function setUp(): void
     #[Test]
     public function executeWillReturnSuccessWhenProcessQueueSucceeds(): void
     {
+        $this->processBuilder->withArgument(
+            '--template',
+            DevToolsPathResolver::getPreferredVendorPath('vendor/saggre/phpdocumentor-markdown/themes/markdown')
+        )
+            ->willReturn($this->processBuilder->reveal())
+            ->shouldBeCalled();
         $this->processBuilder->withArgument(
             '--cache-folder',
             ManagedWorkspace::getCacheDirectory(ManagedWorkspace::PHPDOC)

tests/Path/DevToolsPathResolverTest.php

@@ -51,6 +51,10 @@ public function itWillExposeCanonicalPackagePaths(): void
             \dirname(__DIR__, 2) . '/vendor/bin/ecs',
             DevToolsPathResolver::getRuntimeToolBinaryPath('ecs')
         );
+        self::assertSame(
+            \dirname(__DIR__, 2) . '/vendor/fast-forward/phpdoc-bootstrap-template',
+            DevToolsPathResolver::getRuntimeVendorPath('vendor/fast-forward/phpdoc-bootstrap-template')
+        );
         self::assertSame(
             \dirname(__DIR__, 2) . '/resources/phpdocumentor.xml',
             DevToolsPathResolver::getResourcesPath('phpdocumentor.xml')
@@ -93,7 +97,7 @@ public function itWillDetectWhetherDevToolsRunsFromVendorOrRepositoryCheckout():
      * @return void
      */
     #[Test]
-    public function itWillResolveRuntimeAutoloadPathsForRepositoryAndDependencyInstalls(): void
+    public function itWillResolveRuntimeAutoloadAndVendorPathsForRepositoryAndDependencyInstalls(): void
     {
         self::assertSame(
             '/workspaces/dev-tools/vendor/autoload.php',
@@ -103,6 +107,13 @@ public function itWillResolveRuntimeAutoloadPathsForRepositoryAndDependencyInsta
             '/workspaces/project/vendor/autoload.php',
             DevToolsPathResolver::getRuntimeAutoloadPath('/workspaces/project/vendor/fast-forward/dev-tools')
         );
+        self::assertSame(
+            '/workspaces/project/vendor/saggre/phpdocumentor-markdown/themes/markdown',
+            DevToolsPathResolver::getRuntimeVendorPath(
+                'vendor/saggre/phpdocumentor-markdown/themes/markdown',
+                '/workspaces/project/vendor/fast-forward/dev-tools'
+            )
+        );
     }
 
     /**
@@ -175,4 +186,50 @@ public function itWillFallbackToRuntimeToolBinariesWhenTheProjectDoesNotProvideT
             )
         );
     }
+
+    /**
+     * @return void
+     */
+    #[Test]
+    public function itWillPreferProjectVendorPathsWhenTheyExist(): void
+    {
+        $projectPath = sys_get_temp_dir() . '/dev-tools-vendor-path-resolver-' . bin2hex(random_bytes(4));
+        $vendorPath = $projectPath . '/vendor/saggre/phpdocumentor-markdown/themes/markdown';
+
+        mkdir($vendorPath, 0o777, true);
+
+        try {
+            self::assertSame(
+                $vendorPath,
+                DevToolsPathResolver::getPreferredVendorPath(
+                    'vendor/saggre/phpdocumentor-markdown/themes/markdown',
+                    $projectPath,
+                    '/Users/example/.composer/vendor/fast-forward/dev-tools'
+                )
+            );
+        } finally {
+            rmdir($vendorPath);
+            rmdir($projectPath . '/vendor/saggre/phpdocumentor-markdown/themes');
+            rmdir($projectPath . '/vendor/saggre/phpdocumentor-markdown');
+            rmdir($projectPath . '/vendor/saggre');
+            rmdir($projectPath . '/vendor');
+            rmdir($projectPath);
+        }
+    }
+
+    /**
+     * @return void
+     */
+    #[Test]
+    public function itWillFallbackToRuntimeVendorPathsWhenTheProjectDoesNotProvideThem(): void
+    {
+        self::assertSame(
+            '/Users/example/.composer/vendor/fast-forward/phpdoc-bootstrap-template',
+            DevToolsPathResolver::getPreferredVendorPath(
+                'vendor/fast-forward/phpdoc-bootstrap-template',
+                '/workspaces/project',
+                '/Users/example/.composer/vendor/fast-forward/dev-tools'
+            )
+        );
+    }
 }