phpDocumentor · jaapio · Sep 14, 2025 · Sep 14, 2025 · Sep 14, 2025
diff --git a/packages/dev-server/src/Internal/HttpHandler.php b/packages/dev-server/src/Internal/HttpHandler.php
@@ -23,6 +23,7 @@
 use Ratchet\Http\HttpServerInterface;
 use Throwable;
 
+use function is_array;
 use function str_replace;
 use function strlen;
 use function trim;
@@ -33,9 +34,10 @@ final class HttpHandler implements HttpServerInterface
 
     private ExtensionMimeTypeDetector $detector;
 
+    /** @param string|string[] $indexFile */
     public function __construct(
         private FlySystemAdapter $files,
-        private string $indexFile = 'index.html',
+        private string|array $indexFile = 'index.html',
     ) {
         $this->detector = new ExtensionMimeTypeDetector();
     }
@@ -53,13 +55,17 @@ public function onOpen(ConnectionInterface $conn, RequestInterface|null $request
         // Remove leading slash and any route parameters
         $requestPath = trim($path, '/');
 
-        // For empty path (root) serve index.html
-        if ($requestPath === '') {
-            $requestPath = $this->indexFile;
-        }
-
-        if ($this->files->isDirectory($requestPath)) {
-            $requestPath .= '/' . $this->indexFile;
+        if ($requestPath === '' || $this->files->isDirectory($requestPath)) {
+            if (is_array($this->indexFile)) {
+                foreach ($this->indexFile as $indexFile) {
+                    if ($this->files->has(trim($requestPath . '/' . $indexFile, '/'))) {
+                        $requestPath = trim($requestPath . '/' . $indexFile, '/');
+                        break;
+                    }
+                }
+            } else {
+                $requestPath .= '/' . $this->indexFile;
+            }
         }
 
         if ($this->files->has($requestPath)) {
@@ -81,7 +87,9 @@ public function onOpen(ConnectionInterface $conn, RequestInterface|null $request
             return;
         }
 
-        $content = '<!DOCTYPE html><html><body><h1>404 - Page Not Found</h1></body></html>';
+        $content = '<!DOCTYPE html><html><body><h1>404 - Page Not Found</h1>
+<p>Path ' . $requestPath . ' does not exist</p>
+</body></html>';
         $headers = [
             'Content-Type' => 'text/html',
             'Content-Length' => strlen($content),
@@ -95,7 +103,7 @@ private function injectWebSocketClient(string $html): string
     {
         //Read html and inject script before closing body tag
         $injection = <<<'EOT'
-<script>    
+<script>
     const socket = new WebSocket('ws://' + window.location.host + '/ws');
     socket.addEventListener('message', function (event) {
         if (event.data === 'update') {

diff --git a/packages/dev-server/src/Server.php b/packages/dev-server/src/Server.php
@@ -60,7 +60,7 @@ public function watch(string $path): void
         $this->watcher->addPath($path);
     }
 
-    public function addListener(string $event, Closure $param): void
+    public function addListener(string $event, Closure|callable $param): void
     {
         $this->eventDispatcher->addListener($event, $param);
     }

diff --git a/packages/dev-server/src/ServerFactory.php b/packages/dev-server/src/ServerFactory.php
@@ -29,13 +29,14 @@ public function __construct(
     ) {
     }
 
+    /** @param string|string[] $indexFile */
     public function createDevServer(
         string $soureDirectory,
         FlySystemAdapter $files,
         string $host,
         string $listen,
         int $port,
-        string $indexFile = 'index.html',
+        string|array $indexFile = 'index.html',
     ): Server {
         $httpHandler = new HttpHandler($files, $indexFile);
         $wsServer = new WebSocketHandler($this->logger);

diff --git a/packages/guides-cli/src/Command/Serve.php b/packages/guides-cli/src/Command/Serve.php
@@ -19,25 +19,18 @@
 use phpDocumentor\DevServer\ServerFactory;
 use phpDocumentor\DevServer\Watcher\FileModifiedEvent;
 use phpDocumentor\FileSystem\FlySystemAdapter;
+use phpDocumentor\Guides\Cli\DevServer\RerenderListener;
 use phpDocumentor\Guides\Cli\Internal\RunCommand;
-use phpDocumentor\Guides\Compiler\CompilerContext;
 use phpDocumentor\Guides\Event\PostParseDocument;
-use phpDocumentor\Guides\Handlers\CompileDocumentsCommand;
-use phpDocumentor\Guides\Handlers\ParseFileCommand;
-use phpDocumentor\Guides\Handlers\RenderDocumentCommand;
 use phpDocumentor\Guides\Nodes\DocumentNode;
-use phpDocumentor\Guides\RenderContext;
-use phpDocumentor\Guides\Renderer\DocumentListIterator;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 
-use function assert;
 use function is_int;
 use function is_string;
 use function sprintf;
-use function substr;
 
 final class Serve extends Command
 {
@@ -123,58 +116,7 @@ static function (PostParseDocument $event) use ($app): void {
 
         $app->addListener(
             FileModifiedEvent::class,
-            function (FileModifiedEvent $event) use ($documents, $sourceFileSystem, $projectNode, $settings, $app, $output): void {
-                $output->writeln(
-                    sprintf(
-                        'File modified: %s, rerendering...',
-                        $event->path,
-                    ),
-                );
-                $file = substr($event->path, 0, -4);
-
-                $document = $this->commandBus->handle(
-                    new ParseFileCommand(
-                        $sourceFileSystem,
-                        '',
-                        $file,
-                        $settings->getInputFormat(),
-                        1,
-                        $projectNode,
-                        true,
-                    ),
-                );
-                assert($document instanceof DocumentNode);
-
-                $documents[$file] = $document;
-
-                /** @var array<string, DocumentNode> $documents */
-                $documents = $this->commandBus->handle(new CompileDocumentsCommand($documents, new CompilerContext($projectNode)));
-                $destinationFileSystem = FlySystemAdapter::createForPath($settings->getOutput());
-
-                $documentIterator = DocumentListIterator::create(
-                    $projectNode->getRootDocumentEntry(),
-                    $documents,
-                );
-
-                $renderContext = RenderContext::forProject(
-                    $projectNode,
-                    $documents,
-                    $sourceFileSystem,
-                    $destinationFileSystem,
-                    '/',
-                    'html',
-                )->withIterator($documentIterator);
-
-                $this->commandBus->handle(
-                    new RenderDocumentCommand(
-                        $documents[$file],
-                        $renderContext->withDocument($documents[$file]),
-                    ),
-                );
-
-                $output->writeln('Rerendering completed.');
-                $app->notifyClients();
-            },
+            new RerenderListener($output, $this->commandBus, $sourceFileSystem, $settings, $projectNode, $documents, $app),
         );
 
         $output->writeln(

diff --git a/packages/guides-cli/src/DevServer/RerenderListener.php b/packages/guides-cli/src/DevServer/RerenderListener.php
@@ -0,0 +1,105 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\Cli\DevServer;
+
+use League\Tactician\CommandBus;
+use phpDocumentor\DevServer\Server;
+use phpDocumentor\DevServer\Watcher\FileModifiedEvent;
+use phpDocumentor\FileSystem\FileSystem;
+use phpDocumentor\FileSystem\FlySystemAdapter;
+use phpDocumentor\Guides\Compiler\CompilerContext;
+use phpDocumentor\Guides\Handlers\CompileDocumentsCommand;
+use phpDocumentor\Guides\Handlers\ParseFileCommand;
+use phpDocumentor\Guides\Handlers\RenderDocumentCommand;
+use phpDocumentor\Guides\Nodes\DocumentNode;
+use phpDocumentor\Guides\Nodes\ProjectNode;
+use phpDocumentor\Guides\RenderContext;
+use phpDocumentor\Guides\Renderer\DocumentListIterator;
+use phpDocumentor\Guides\Settings\ProjectSettings;
+use Symfony\Component\Console\Output\OutputInterface;
+
+use function assert;
+use function sprintf;
+use function substr;
+
+final class RerenderListener
+{
+    /** @param array<string, DocumentNode> $documents */
+    public function __construct(
+        private readonly OutputInterface $output,
+        private readonly CommandBus $commandBus,
+        private readonly FileSystem $sourceFileSystem,
+        private readonly ProjectSettings $settings,
+        private readonly ProjectNode $projectNode,
+        private array $documents,
+        private readonly Server $server,
+    ) {
+    }
+
+    public function __invoke(FileModifiedEvent $event): void
+    {
+        $this->output->writeln(
+            sprintf(
+                'File modified: %s, rerendering...',
+                $event->path,
+            ),
+        );
+        $file = substr($event->path, 0, -4);
+
+        $document = $this->commandBus->handle(
+            new ParseFileCommand(
+                $this->sourceFileSystem,
+                '',
+                $file,
+                $this->settings->getInputFormat(),
+                1,
+                $this->projectNode,
+                true,
+            ),
+        );
+        assert($document instanceof DocumentNode);
+
+        $documents = $this->documents;
+        $documents[$file] = $document;
+
+        /** @var array<string, DocumentNode> $documents */
+        $documents = $this->commandBus->handle(new CompileDocumentsCommand($documents, new CompilerContext($this->projectNode)));
+        $this->documents = $documents;
+        $destinationFileSystem = FlySystemAdapter::createForPath($this->settings->getOutput());
+
+        $documentIterator = DocumentListIterator::create(
+            $this->projectNode->getRootDocumentEntry(),
+            $this->documents,
+        );
+
+        $renderContext = RenderContext::forProject(
+            $this->projectNode,
+            $this->documents,
+            $this->sourceFileSystem,
+            $destinationFileSystem,
+            '/',
+            'html',
+        )->withIterator($documentIterator);
+
+        $this->commandBus->handle(
+            new RenderDocumentCommand(
+                $this->documents[$file],
+                $renderContext->withDocument($this->documents[$file]),
+            ),
+        );
+
+        $this->output->writeln('Rerendering completed.');
+        $this->server->notifyClients();
+    }
+}
diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon
@@ -1,7 +1,7 @@
 parameters:
 	ignoreErrors:
 		-
-			message: "#^Parameter \\#2 \\$headers of class GuzzleHttp\\\\Psr7\\\\Response constructor expects array\\<array\\<string\\>\\|string\\>, array\\<string, int\\|string\\> given\\.$#"
+			message: "#^Parameter \\#2 \\$headers of class GuzzleHttp\\\\Psr7\\\\Response constructor expects array\\<array\\<string\\>\\|string\\>, array\\<string, int\\<1, max\\>\\|string\\> given\\.$#"
 			count: 1
 			path: packages/dev-server/src/Internal/HttpHandler.php