Add GUIDE section for v3 docs

src/Package/Target/php.php

@@ -296,18 +296,29 @@ class php extends TargetPackage
             $x->isBuildStatic());
         $shared_extensions = parse_extension_list($package->getBuildOption('build-shared') ?? []);
         $install_packages = array_filter($installer->getResolvedPackages(), fn ($x) => $x->getType() !== 'php-extension' && $x->getName() !== 'php' && !str_starts_with($x->getName(), 'php-'));
-        return [
+
+        $builder = ApplicationContext::get(PackageBuilder::class);
+        $ignore_cache = $builder->getOption('dl-ignore-cache', false);
+        $php_will_be_refreshed = $ignore_cache !== false && (
+            $ignore_cache === null ||   // --dl-ignore-cache with no value (ignore all)
+            str_contains((string) $ignore_cache, 'php-src')
+        );
+
+        $info = [
             'Build OS' => SystemTarget::getTargetOS() . ' (' . SystemTarget::getTargetArch() . ')',
             'Build Target' => getenv('SPC_TARGET') ?: '',
             'Build Toolchain' => ToolchainManager::getToolchainClass(),
             'Build SAPI' => implode(', ', $sapis),
-            'PHP Version' => self::getPHPVersion(return_null_if_failed: true) ?? self::getPHPVersionFromArchive(return_null_if_failed: true) ?? 'Unknown',
-            'Static Extensions (' . count($static_extensions) . ')' => implode(',', array_map(fn ($x) => substr($x->getName(), 4), $static_extensions)),
-            'Shared Extensions (' . count($shared_extensions) . ')' => implode(',', $shared_extensions),
-            'Install Packages (' . count($install_packages) . ')' => implode(',', array_map(fn ($x) => $x->getName(), $install_packages)),
-            'Strip Binaries' => $package->getBuildOption('no-strip') ? 'No' : 'Yes',
-            'Enable ZTS' => $package->getBuildOption('enable-zts') ? 'Yes' : 'No',
         ];
+        if (!$php_will_be_refreshed) {
+            $info['PHP Version'] = self::getPHPVersion(return_null_if_failed: true) ?? self::getPHPVersionFromArchive(return_null_if_failed: true) ?? 'Unknown';
+        }
+        $info['Static Extensions (' . count($static_extensions) . ')'] = implode(',', array_map(fn ($x) => substr($x->getName(), 4), $static_extensions));
+        $info['Shared Extensions (' . count($shared_extensions) . ')'] = implode(',', $shared_extensions);
+        $info['Install Packages (' . count($install_packages) . ')'] = implode(',', array_map(fn ($x) => $x->getName(), $install_packages));
+        $info['Strip Binaries'] = $package->getBuildOption('no-strip') ? 'No' : 'Yes';
+        $info['Enable ZTS'] = $package->getBuildOption('enable-zts') ? 'Yes' : 'No';
+        return $info;
     }
 
     #[BeforeStage('php', 'build')]

src/StaticPHP/Command/Dev/GenExtDocsCommand.php

@@ -0,0 +1,87 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Command\Dev;
+
+use StaticPHP\Command\BaseCommand;
+use StaticPHP\Config\PackageConfig;
+use Symfony\Component\Console\Attribute\AsCommand;
+
+#[AsCommand('dev:gen-ext-docs', 'Generate extension list JSON for documentation', [], true)]
+class GenExtDocsCommand extends BaseCommand
+{
+    protected bool $no_motd = true;
+
+    public function handle(): int
+    {
+        if (!spc_mode(SPC_MODE_SOURCE)) {
+            $this->output->writeln('<error>This command is only available in source mode.</error>');
+            return static::USER_ERROR;
+        }
+
+        $all = PackageConfig::getAll();
+        $extensions = [];
+
+        foreach ($all as $pkg_name => $config) {
+            if (($config['type'] ?? '') !== 'php-extension') {
+                continue;
+            }
+
+            // Strip ext- prefix for display name
+            $name = str_starts_with($pkg_name, 'ext-') ? substr($pkg_name, 4) : $pkg_name;
+
+            // Determine OS support from php-extension.os field.
+            // If the field is absent, the extension supports all three OSes.
+            $os_list = $config['php-extension']['os'] ?? null;
+            if ($os_list === null) {
+                $linux = true;
+                $macos = true;
+                $windows = true;
+            } else {
+                $linux = in_array('Linux', $os_list, true);
+                $macos = in_array('Darwin', $os_list, true);
+                $windows = in_array('Windows', $os_list, true);
+            }
+
+            $extensions[] = [
+                'name' => $name,
+                'linux' => $linux,
+                'macos' => $macos,
+                'windows' => $windows,
+                'url' => $this->resolveSourceUrl($config, $name),
+            ];
+        }
+
+        // Sort alphabetically by name
+        usort($extensions, fn ($a, $b) => strcmp($a['name'], $b['name']));
+
+        $output = [
+            'generated_at' => date('c'),
+            'extensions' => $extensions,
+        ];
+
+        $output_path = ROOT_DIR . '/docs/.vitepress/ext-data.json';
+        file_put_contents($output_path, json_encode($output, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . PHP_EOL);
+
+        $this->output->writeln("<info>Generated {$output_path} with " . count($extensions) . ' extensions.</info>');
+        return static::SUCCESS;
+    }
+
+    private function resolveSourceUrl(array $config, string $ext_name): ?string
+    {
+        $source = $config['artifact']['source'] ?? null;
+        if ($source === null) {
+            return null;
+        }
+
+        return match ($source['type'] ?? '') {
+            'pecl' => 'https://pecl.php.net/package/' . ($source['name'] ?? $ext_name),
+            'git' => rtrim($source['url'] ?? '', '/'),
+            'ghtar', 'ghrel', 'ghtagtar', 'pie' => isset($source['repo'])
+                ? 'https://github.com/' . $source['repo']
+                : null,
+            default => null,
+        };
+    }
+}

src/StaticPHP/Command/SPCConfigCommand.php

@@ -18,7 +18,7 @@ class SPCConfigCommand extends BaseCommand
     {
         $this->addArgument('extensions', InputArgument::OPTIONAL, 'The extensions will be compiled, comma separated');
         $this->addOption('with-libs', null, InputOption::VALUE_REQUIRED, 'add additional libraries, comma separated', '');
-        $this->addOption('with-packages', null, InputOption::VALUE_REQUIRED, 'add additional libraries, comma separated', '');
+        $this->addOption('with-packages', 'p', InputOption::VALUE_REQUIRED, 'add additional libraries, comma separated', '');
         $this->addOption('with-suggested-libs', 'L', null, 'Build with suggested libs for selected exts and libs');
         $this->addOption('with-suggests', null, null, 'Build with suggested packages for selected exts and libs');
         $this->addOption('with-suggested-exts', 'E', null, 'Build with suggested extensions for selected exts');

src/StaticPHP/ConsoleApplication.php

@@ -11,6 +11,7 @@ use StaticPHP\Command\CraftCommand;
 use StaticPHP\Command\Dev\DumpCapabilitiesCommand;
 use StaticPHP\Command\Dev\DumpStagesCommand;
 use StaticPHP\Command\Dev\EnvCommand;
+use StaticPHP\Command\Dev\GenExtDocsCommand;
 use StaticPHP\Command\Dev\IsInstalledCommand;
 use StaticPHP\Command\Dev\LintConfigCommand;
 use StaticPHP\Command\Dev\PackageInfoCommand;
@@ -81,6 +82,7 @@ class ConsoleApplication extends Application
             new DumpStagesCommand(),
             new DumpCapabilitiesCommand(),
             new PackageInfoCommand(),
+            new GenExtDocsCommand(),
         ]);
 
         // add additional commands from registries