Initial setup for file serve

With this change we provide an internal webserver in the application. And introduce a watch on changes. This introduces a new way of working with guides, allowing users to edit documentation without caring about rerendering. Optimizations are possible like parsing and rendering a single file to make rerendering faster.

Author: jaapio

app/Dockerfile

@@ -0,0 +1,10 @@
+FROM php:8.4-cli
+
+COPY --from=ghcr.io/php/pie:bin /pie /usr/bin/pie
+
+RUN apt update && apt install -y git
+
+RUN docker-php-ext-configure pcntl --enable-pcntl \
+ && docker-php-ext-install pcntl \
+ && pie install arnaud-lb/inotify
+

composer.lock

@@ -54,4 +54,6 @@ public function listContents(string $directory = '', bool $recursive = false): a
 
  /** @return StorageAttributes[] */
  public function find(SpecificationInterface $specification): iterable;
+
+ public function isDirectory(string $path): bool;
 }

packages/filesystem/src/FileSystem.php

@@ -92,4 +92,9 @@ public function find(SpecificationInterface $specification): iterable
  {
  return $this->filesystem->find($specification);
  }
+
+ public function isDirectory(string $path): bool
+ {
+ return $this->filesystem->isDirectory($path);
+ }
 }

packages/filesystem/src/FlySystemAdapter.php

@@ -75,4 +75,9 @@ public function find(SpecificationInterface $specification): iterable
  yield new \phpDocumentor\FileSystem\FlysystemV1\StorageAttributes($file);
  }
  }
+
+ public function isDirectory(string $path): bool
+ {
+ return $this->filesystem->directoryExists($path);
+ }
 }

packages/filesystem/src/FlysystemV1/FlysystemV1.php

@@ -35,6 +35,11 @@ public function has(string $path): bool
  return $this->filesystem->has($path);
  }
 
+ public function isDirectory(string $path): bool
+ {
+ return $this->filesystem->directoryExists($path);
+ }
+
  public function readStream(string $path): mixed
  {
  return $this->filesystem->readStream($path);

packages/filesystem/src/FlysystemV3/FlysystemV3.php

@@ -32,7 +32,10 @@
  "symfony/config": "^5.4 || ^6.3 || ^7.0",
  "symfony/console": "^5.4 || ^6.3 || ^7.0",
  "symfony/dependency-injection": "^5.4 || ^6.3 || ^7.0",
- "symfony/event-dispatcher": "^5.4 || ^6.3 || ^7.0"
+ "symfony/event-dispatcher": "^5.4 || ^6.3 || ^7.0",
+ "react/http": "^v1.11",
+ "react/socket": "^v1.16",
+ "league/mime-type-detection": "^1.16"
  },
  "bin": [
  "bin/guides"

packages/guides-cli/composer.json

@@ -6,7 +6,11 @@
 use phpDocumentor\Guides\Cli\Application;
 use phpDocumentor\Guides\Cli\Command\ProgressBarSubscriber;
 use phpDocumentor\Guides\Cli\Command\Run;
+use phpDocumentor\Guides\Cli\Command\Serve;
 use phpDocumentor\Guides\Cli\Command\WorkingDirectorySwitcher;
+use phpDocumentor\Guides\Cli\Command\SettingsBuilder;
+use phpDocumentor\Guides\Cli\Internal\RunCommand;
+use phpDocumentor\Guides\Cli\Internal\RunCommandHandler;
 use Psr\Clock\ClockInterface;
 use Psr\EventDispatcher\EventDispatcherInterface;
 use Psr\Log\LoggerInterface;
@@ -26,6 +30,10 @@
  ->public()
  ->tag('phpdoc.guides.cli.command')
 
+ ->set(Serve::class)
+ ->public()
+ ->tag('phpdoc.guides.cli.command')
+
  ->set(NativeClock::class)
  ->alias(ClockInterface::class, NativeClock::class)
 
@@ -44,5 +52,9 @@
  ->set(WorkingDirectorySwitcher::class)
  ->tag('event_listener', ['event' => ConsoleEvents::COMMAND, 'method' => '__invoke'])
 
- ->set(ProgressBarSubscriber::class);
+ ->set(ProgressBarSubscriber::class)
+ ->set(SettingsBuilder::class)
+ ->set(RunCommandHandler::class)
+ ->tag('phpdoc.guides.command', ['command' => RunCommand::class])
+ ;
 };

packages/guides-cli/resources/config/services.php

@@ -25,6 +25,7 @@
 use Monolog\Logger;
 use phpDocumentor\FileSystem\Finder\Exclude;
 use phpDocumentor\FileSystem\FlySystemAdapter;
+use phpDocumentor\Guides\Cli\Internal\RunCommand;
 use phpDocumentor\Guides\Cli\Logger\SpyProcessor;
 use phpDocumentor\Guides\Compiler\CompilerContext;
 use phpDocumentor\Guides\Event\PostProjectNodeCreated;
@@ -71,47 +72,13 @@ public function __construct(
  private readonly ClockInterface $clock,
  private readonly EventDispatcher $eventDispatcher,
  private readonly ProgressBarSubscriber $progressBarSubscriber,
+ private SettingsBuilder $settingsBuilder,
  ) {
  parent::__construct('run');
 
- $this->addArgument(
- 'input',
- InputArgument::OPTIONAL,
- 'Directory which holds the files to render',
- );
- $this->addOption(
- 'output',
- null,
- InputOption::VALUE_REQUIRED,
- 'Directory to write rendered files to',
- );
-
- $this->addOption(
- 'input-file',
- null,
- InputOption::VALUE_REQUIRED,
- 'If set, only the specified file is parsed, relative to the directory specified in "input"',
- );
-
- $this->addOption(
- 'exclude-path',
- null,
- InputOption::VALUE_REQUIRED | InputOption::VALUE_IS_ARRAY,
- 'Paths to exclude, doc files in these directories will not be parsed',
- );
+ $this->settingsBuilder ??= new SettingsBuilder($this->eventDispatcher, $this->settingsManager, $this->clock);
+ $this->settingsBuilder->configureCommand($this);
 
- $this->addOption(
- 'input-format',
- null,
- InputOption::VALUE_REQUIRED,
- 'Format of the input can be "RST", or "Markdown"',
- );
- $this->addOption(
- 'output-format',
- null,
- InputOption::VALUE_REQUIRED | InputOption::VALUE_IS_ARRAY,
- 'Format of the input can be "html" and/or "interlink"',
- );
  $this->addOption(
  'log-path',
  null,
@@ -132,13 +99,6 @@ public function __construct(
  'If set, returns a non-zero exit code as soon as any errors occur',
  );
 
- $this->addOption(
- 'theme',
- null,
- InputOption::VALUE_REQUIRED,
- 'The theme used for rendering',
- );
-
  $this->addOption(
  'progress',
  null,
@@ -159,93 +119,11 @@ public function registerProgressBar(ConsoleOutputInterface $output): void
  $this->progressBarSubscriber->subscribe($output, $this->eventDispatcher);
  }
 
- private function getSettingsOverriddenWithInput(InputInterface $input): ProjectSettings
- {
- $settings = $this->settingsManager->getProjectSettings();
-
- if ($settings->isShowProgressBar()) {
- $settings->setShowProgressBar($input->getOption('progress'));
- }
-
- if ($input->getArgument('input')) {
- $settings->setInput((string) $input->getArgument('input'));
- }
-
- if ($input->getOption('output')) {
- $settings->setOutput((string) $input->getOption('output'));
- }
-
- if ($input->getOption('input-file')) {
- $inputFile = (string) $input->getOption('input-file');
- $pathInfo = pathinfo($inputFile);
- $settings->setInputFile($pathInfo['filename']);
- if (!empty($pathInfo['extension'])) {
- $settings->setInputFormat($pathInfo['extension']);
- }
- }
-
- if ($input->getOption('input-format')) {
- $settings->setInputFormat((string) $input->getOption('input-format'));
- }
-
- if ($input->getOption('log-path')) {
- $settings->setLogPath((string) $input->getOption('log-path'));
- }
-
- if ($input->getOption('fail-on-error')) {
- $settings->setFailOnError(LogLevel::ERROR);
- }
-
- if ($input->getOption('fail-on-log')) {
- $settings->setFailOnError(LogLevel::WARNING);
- }
-
- if (count($input->getOption('output-format')) > 0) {
- $settings->setOutputFormats($input->getOption('output-format'));
- }
-
- if ($input->getOption('theme')) {
- $settings->setTheme((string) $input->getOption('theme'));
- }
-
- if (method_exists($settings, 'setExcludes')) {
- /** @var list<string> $excludePaths */
- $excludePaths = (array) $input->getOption('exclude-path');
- if ($excludePaths !== []) {
- $settings->setExcludes(
- $settings->getExcludes()->withPaths($excludePaths),
- );
- }
- }
-
- return $settings;
- }
-
  protected function execute(InputInterface $input, OutputInterface $output): int
  {
- $settings = $this->getSettingsOverriddenWithInput($input);
- $inputDir = $settings->getInput();
- if (!is_dir($inputDir)) {
- throw new RuntimeException(sprintf('Input directory "%s" was not found! ' . "\n" .
- 'Run "vendor/bin/guides -h" for information on how to configure this command.', $inputDir));
- }
-
- $projectNode = new ProjectNode(
- $settings->getTitle() === '' ? null : $settings->getTitle(),
- $settings->getVersion() === '' ? null : $settings->getVersion(),
- $settings->getRelease() === '' ? null : $settings->getRelease(),
- $settings->getCopyright() === '' ? null : $settings->getCopyright(),
- $this->clock->now(),
- );
-
- $event = new PostProjectNodeCreated($projectNode, $settings);
- $event = $this->eventDispatcher->dispatch($event);
- assert($event instanceof PostProjectNodeCreated);
- $projectNode = $event->getProjectNode();
- $settings = $event->getSettings();
-
- $outputDir = $settings->getOutput();
- $sourceFileSystem = FlySystemAdapter::createForPath($settings->getInput());
+ $this->settingsBuilder->overrideWithInput($input);
+ $projectNode = $this->settingsBuilder->createProjectNode();
+ $settings = $this->settingsBuilder->getSettings();
 
  $logPath = $settings->getLogPath();
  if ($logPath === 'php://stder') {
@@ -260,57 +138,16 @@ protected function execute(InputInterface $input, OutputInterface $output): int
  $this->logger->pushProcessor($spyProcessor);
  }
 
- $documents = [];
-
-
  if ($output instanceof ConsoleOutputInterface && $settings->isShowProgressBar()) {
  $this->progressBarSubscriber->subscribe($output, $this->eventDispatcher);
  }
 
- if ($settings->getInputFile() === '') {
- $documents = $this->commandBus->handle(
- new ParseDirectoryCommand(
- $sourceFileSystem,
- '',
- $settings->getInputFormat(),
- $projectNode,
- $this->getExclude($settings, $input),
- ),
- );
- } else {
- $documents[] = $this->commandBus->handle(
- new ParseFileCommand(
- $sourceFileSystem,
- '',
- $settings->getInputFile(),
- $settings->getInputFormat(),
- 1,
- $projectNode,
- true,
- ),
- );
- }
-
- $this->themeManager->useTheme($settings->getTheme());
-
- $documents = $this->commandBus->handle(new CompileDocumentsCommand($documents, new CompilerContext($projectNode)));
-
- $destinationFileSystem = FlySystemAdapter::createForPath($outputDir);
+ $documents = $this->commandBus->handle(
+ new RunCommand($settings, $projectNode, $input),
+ );
 
  $outputFormats = $settings->getOutputFormats();
-
- foreach ($outputFormats as $format) {
- $this->commandBus->handle(
- new RenderCommand(
- $format,
- $documents,
- $sourceFileSystem,
- $destinationFileSystem,
- $projectNode,
- ),
- );
- }
-
+ $outputDir = $settings->getOutput();
  if ($output->isQuiet() === false) {
  $lastFormat = '';
 
@@ -331,31 +168,4 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
  return Command::SUCCESS;
  }
-
- private function getExclude(ProjectSettings $settings, InputInterface|null $input = null): Exclude|SpecificationInterface|null
- {
- if (method_exists($settings, 'getExcludes')) {
- return $settings->getExcludes();
- }
-
- if ($input === null) {
- return null;
- }
-
- if ($input->getOption('exclude-path')) {
- /** @var string[] $excludedPaths */
- $excludedPaths = (array) $input->getOption('exclude-path');
- $excludedSpecifications = array_map(static fn (string $path) => new NotSpecification(new InPath(new Path($path))), $excludedPaths);
- $excludedSpecification = array_shift($excludedSpecifications);
- assert($excludedSpecification !== null);
-
- return array_reduce(
- $excludedSpecifications,
- static fn (SpecificationInterface $carry, SpecificationInterface $spec) => new OrSpecification($carry, $spec),
- $excludedSpecification,
- );
- }
-
- return null;
- }
 }