feat(chore): Adds download-docs command (#697)

Author: silasjoisten

.devcontainer/Dockerfile

@@ -4,8 +4,8 @@ ARG XDEBUG_MODE=coverage
 RUN apt update -y && apt install -y git composer php-cli php-dom php-curl php-xdebug vim
 WORKDIR /app
 RUN git config --global --add safe.directory /app && \
-    git config --global --add safe.directory /app/generator/doc/doc-en/en && \
-    git config --global --add safe.directory /app/generator/doc/doc-en/doc-base
-CMD cd /app/generator/doc && ./update.sh && \
-    cd /app && composer install && \
-    cd /app/generator && composer install && php ./safe.php generate
+    git config --global --add safe.directory /app/generator/docs
+CMD cd /app && composer install && \
+    cd /app/generator && composer install && \
+    php ./safe.php download-docs && \
+    php ./safe.php generate

.github/workflows/auto-regenerate.yml

@@ -22,14 +22,14 @@ jobs:
       - name: "Check out salathe/phpdoc-base"
         uses: "actions/checkout@v4"
         with:
-          path: "generator/doc/doc-en/doc-base"
+          path: "generator/docs/salathe/phpdoc-base"
           repository: "salathe/phpdoc-base"
           fetch-depth: 0
 
       - name: "Check out php/doc-en"
         uses: "actions/checkout@v4"
         with:
-          path: "generator/doc/doc-en/en"
+          path: "generator/docs"
           repository: "php/doc-en"
           fetch-depth: 0
 

.github/workflows/continuous-integration.yml

@@ -18,27 +18,31 @@ jobs:
     steps:
       - name: "Checkout"
         uses: "actions/checkout@v4"
+
       - name: "Get current date for the daily cache"
         id: "date"
         run: echo "date=$(date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
+
       - name: "Cache the php documentation"
-        id: cache-php-doc
+        id: cache-php-docs
         uses: "actions/cache@v4"
         with:
-          path: "generator/doc/doc-en"
-          key: php-doc-${{ steps.date.outputs.date }}
+          path: "generator/docs"
+          key: php-docs-${{ steps.date.outputs.date }}
+
       - name: "Check out salathe/phpdoc-base"
         uses: "actions/checkout@v4"
-        if: steps.cache-php-doc.outputs.cache-hit != 'true'
+        if: steps.cache-php-docs.outputs.cache-hit != 'true'
         with:
-          path: "generator/doc/doc-en/doc-base"
+          path: "generator/docs/salathe/phpdoc-base"
           repository: "salathe/phpdoc-base"
           fetch-depth: 0
+
       - name: "Check out php/doc-en"
         uses: "actions/checkout@v4"
-        if: steps.cache-php-doc.outputs.cache-hit != 'true'
+        if: steps.cache-php-docs.outputs.cache-hit != 'true'
         with:
-          path: "generator/doc/doc-en/en"
+          path: "generator/docs/php/doc-en"
           repository: "php/doc-en"
           fetch-depth: 0
 
@@ -61,11 +65,11 @@ jobs:
           coverage: "pcov"
           php-version: "${{ matrix.php-version }}"
       - name: "Fetch cached docs"
-        id: cache-php-doc
+        id: cache-docs
         uses: "actions/cache@v4"
         with:
-          path: "generator/doc/doc-en"
-          key: php-doc-${{ needs.fetch_defs.outputs.date }}
+          path: "generator/docs"
+          key: php-docs-${{ needs.fetch_defs.outputs.date }}
           fail-on-cache-miss: true
       - name: "Cache dependencies installed with composer"
         uses: "actions/cache@v4"
@@ -140,11 +144,11 @@ jobs:
           coverage: "pcov"
           php-version: "8.4"
       - name: "Fetch cached docs"
-        id: cache-php-doc
+        id: cache-php-docs
         uses: "actions/cache@v4"
         with:
-          path: "generator/doc/doc-en"
-          key: php-doc-${{ needs.fetch_defs.outputs.date }}
+          path: "generator/docs"
+          key: php-docs-${{ needs.fetch_defs.outputs.date }}
           fail-on-cache-miss: true
       - name: "Cache dependencies installed with composer"
         uses: "actions/cache@v4"

.gitignore

@@ -7,3 +7,4 @@ vendor/
 /generator/tests/rector/composer.lock
 .phpunit.result.cache
 .phpunit.cache
+docs/

CONTRIBUTING.md

@@ -91,12 +91,10 @@ generator, as well as some handy shortcut shell scripts. You can use
 The first step is to download the PHP documentation project locally, using git.
 
 ```bash
-$ cd generator/doc
-$ sh update.sh
+$ generator/safe.php download-docs
 ```
 
-The script can be used to both install the doc and to update it.
-All it does is pull from theses mirrors:
+This will download the PHP documentation from the official repository.
 
 https://github.com/salathe/phpdoc-base
 

generator/composer.json

@@ -14,7 +14,8 @@
         "phpstan/phpstan": "^2",
         "symfony/console": "^7",
         "symfony/process": "^7",
-        "symfony/finder": "^7"
+        "symfony/finder": "^7",
+        "symfony/filesystem": "^7.2"
     },
     "require-dev": {
         "phpunit/phpunit": "^12",

generator/composer.lock

@@ -7,11 +7,13 @@
 use Safe\Commands\FunctionInfoCommand;
 use Safe\Commands\GenerateCommand;
 use Safe\Commands\ScanObjectsCommand;
+use Safe\Commands\DownloadDocsCommand;
 use Symfony\Component\Console\Application;
 
 $application = new Application();
 $application->addCommands([new GenerateCommand()]);
 $application->addCommands([new ScanObjectsCommand()]);
 $application->addCommands([new FunctionInfoCommand()]);
+$application->addCommands([new DownloadDocsCommand()]);
 
 $application->run();

generator/doc/entities/.gitkeep

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Safe\Commands;
+
+use Safe\Filesystem\PathHelper;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Helper\ProgressIndicator;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Console\Style\SymfonyStyle;
+use Symfony\Component\Filesystem\Filesystem;
+use Symfony\Component\Process\Process;
+
+final class DownloadDocsCommand extends Command
+{
+    private SymfonyStyle $io;
+    private Filesystem $filesystem;
+
+    protected function configure(): void
+    {
+        $this
+            ->setName('download-docs')
+            ->setDescription('Download the recent version of the PHP documentation')
+        ;
+    }
+
+    protected function initialize(InputInterface $input, OutputInterface $output): void
+    {
+        $this->io = new SymfonyStyle($input, $output);
+        $this->filesystem = new Filesystem();
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $this->io->title($this->getDescription());
+
+        // Clean up before cloning.
+        $this->filesystem->remove(PathHelper::docsDirectory());
+        $this->filesystem->mkdir(PathHelper::docsDirectory());
+
+        $this->clone($output, 'salathe/phpdoc-base');
+        $this->clone($output, 'php/doc-en');
+
+        return self::SUCCESS;
+    }
+
+    private function clone(OutputInterface $output, string $repository): void
+    {
+        $progressIndicator = new ProgressIndicator($output);
+        $progressIndicator->start(\sprintf('Cloning <info>%s</info>', $repository));
+
+        $process = new Process(['git', 'clone', \sprintf('https://github.com/%s', $repository), \sprintf('%s/%s', PathHelper::docsDirectory(), $repository)]);
+        $process->start();
+
+        while ($process->isRunning()) {
+            $progressIndicator->advance();
+        }
+
+        $progressIndicator->finish(\sprintf('Downloaded <info>%s</info>', $repository));
+    }
+}

generator/doc/update.sh

@@ -32,7 +32,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $phpStanFunctionMapReader = new PhpStanFunctionMapReader();
 
         $finder = new Finder();
-        $finder->in(DocPage::findReferenceDir() . "/*/functions/")->name($targetFilename)->sortByName();
+        $finder->in(DocPage::referenceDir() . "/*/functions/")->name($targetFilename)->sortByName();
 
         foreach ($finder as $file) {
             $docPage = new DocPage($file->getPathname());

generator/safe.php

@@ -4,6 +4,7 @@
 
 namespace Safe\Commands;
 
+use Safe\Filesystem\PathHelper;
 use Safe\XmlDocParser\Scanner;
 use Safe\XmlDocParser\DocPage;
 use Safe\Generator\FileCreator;
@@ -34,7 +35,7 @@ protected function execute(
         $this->rmGenerated();
 
         // Let's build the DTD necessary to load the XML files.
-        $this->checkout(DocPage::findReferenceDir(), "master");
+        $this->checkout(DocPage::referenceDir(), "master");
         DocPage::buildEntities();
 
         // PHP documentation is a living document, which broadly reflects
@@ -66,8 +67,8 @@ protected function execute(
 
             // Scan the documentation for a given PHP version and find all
             // functions that we need to generate safe wrappers for.
-            $this->checkout(DocPage::findReferenceDir(), $commit);
-            $scanner = new Scanner(DocPage::findReferenceDir());
+            $this->checkout(DocPage::referenceDir(), $commit);
+            $scanner = new Scanner(DocPage::referenceDir());
             $res = $scanner->getMethods($scanner->getFunctionsPaths(), $pastFunctionNames, $output);
             $output->writeln(
                 'Functions have been ignored and must be dealt with manually: ' .
@@ -133,8 +134,8 @@ private function rmGenerated(): void
             }
         }
 
-        if (\file_exists(DocPage::findDocDir() . '/entities/generated.ent')) {
-            \unlink(DocPage::findDocDir() . '/entities/generated.ent');
+        if (\file_exists(PathHelper::docsDirectory() . '/generated.ent')) {
+            \unlink(PathHelper::docsDirectory() . '/generated.ent');
         }
     }
 

generator/src/Commands/DownloadDocsCommand.php

@@ -22,7 +22,7 @@ protected function configure(): void
 
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
-        $scanner = new Scanner(DocPage::findReferenceDir());
+        $scanner = new Scanner(DocPage::referenceDir());
 
         $paths = $scanner->getMethodsPaths();
 

generator/src/Commands/FunctionInfoCommand.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Safe\Filesystem;
+
+final class PathHelper
+{
+    public static function projectRootDir(): string
+    {
+        $path = realpath(__DIR__ . '/../../..');
+
+        if (false === $path) {
+            throw new \RuntimeException('Unable to locate root directory');
+        }
+
+        return $path;
+    }
+
+    public static function docsDirectory(): string
+    {
+        return \sprintf('%s/generator/docs', self::projectRootDir());
+    }
+
+    private function __construct()
+    {
+    }
+}