feat: enhance type hints and improve verbosity handling in commands (#1186)

phpstan.neon

@@ -1,6 +1,6 @@
 parameters:
   reportUnmatchedIgnoredErrors: false
-  level: 4
+  level: 5
   phpVersion: 80400
   paths:
     - ./src/

src/StaticPHP/Command/CraftCommand.php

@@ -110,7 +110,7 @@ class CraftCommand extends BaseCommand
      *     shared-extensions: array<string>,
      *     packages: array<string>,
      *     sapi: array<string>,
-     *     verbosity: int,
+     *     verbosity: 128|16|256|32|64|8,
      *     debug: bool,
      *     clean-build: bool,
      *     build-options: array<string, mixed>,
@@ -171,11 +171,16 @@ class CraftCommand extends BaseCommand
         }
 
         // verbosity
-        $verbosity_level = $craft['verbosity'] ?? OutputInterface::VERBOSITY_NORMAL;
         $debug = $craft['debug'] ?? false;
-        if ($debug) {
+        $verbosity_level = $debug
-            $verbosity_level = OutputInterface::VERBOSITY_DEBUG;
+            ? OutputInterface::VERBOSITY_DEBUG
-        }
+            : match ((int) ($craft['verbosity'] ?? 0)) {
+                OutputInterface::VERBOSITY_QUIET => OutputInterface::VERBOSITY_QUIET,
+                OutputInterface::VERBOSITY_VERBOSE => OutputInterface::VERBOSITY_VERBOSE,
+                OutputInterface::VERBOSITY_VERY_VERBOSE => OutputInterface::VERBOSITY_VERY_VERBOSE,
+                OutputInterface::VERBOSITY_DEBUG => OutputInterface::VERBOSITY_DEBUG,
+                default => OutputInterface::VERBOSITY_NORMAL,
+            };
         $craft['verbosity'] = $verbosity_level;
 
         // clean-build (if true, reset before all builds)

src/StaticPHP/Command/Dev/GenExtTestMatrixCommand.php

@@ -16,7 +16,7 @@ class GenExtTestMatrixCommand extends BaseCommand
 
     private const array OS_RUNNERS = [
         'linux' => ['arch' => 'x86_64', 'runner' => 'ubuntu-latest', 'os_key' => 'Linux'],
-        'windows' => ['arch' => 'x86_64', 'runner' => 'windows-latest', 'os_key' => 'Windows'],
+        'windows' => ['arch' => 'x86_64', 'runner' => 'windows-2025', 'os_key' => 'Windows'],
         'macos' => ['arch' => 'aarch64', 'runner' => 'macos-15', 'os_key' => 'Darwin'],
     ];
 

src/StaticPHP/Command/Dev/TestBotCommand.php

@@ -154,7 +154,7 @@ class TestBotCommand extends BaseCommand
             'targets' => array_values($targets),
             'gen_matrix_args' => $gen_matrix_args,
             'gen_matrix_args_tier2' => $gen_matrix_args_tier2,
-            'php_versions' => array_values($php_versions),
+            'php_versions' => $php_versions,
             'tier2' => $tier2,
             'comment_body' => $comment_body,
         ];

src/StaticPHP/DI/ApplicationContext.php

@@ -79,11 +79,11 @@ class ApplicationContext
     /**
      * Get a service from the container.
      *
-     * @template T
+     * @template T of object
      *
-     * @param class-string<T> $id Service identifier
+     * @param class-string<T>|string $id Service identifier
      *
-     * @return null|T
+     * @return ($id is class-string<T> ? T : mixed)
      */
     public static function get(string $id): mixed
     {

src/StaticPHP/Package/PackageInstaller.php

@@ -75,6 +75,9 @@ class PackageInstaller
         }
         // special check for php target packages
         if (in_array($package->getName(), ['php', 'php-cli', 'php-fpm', 'php-micro', 'php-cgi', 'php-embed', 'frankenphp'], true)) {
+            if (!$package instanceof TargetPackage) {
+                throw new WrongUsageException("Package '{$package->getName()}' is expected to be a TargetPackage.");
+            }
             $this->handlePhpTargetPackage($package);
             return $this;
         }

src/StaticPHP/Runtime/Executor/UnixAutoconfExecutor.php

@@ -117,7 +117,7 @@ class UnixAutoconfExecutor extends Executor
     /**
      * Add configure args.
      */
-    public function addConfigureArgs(...$args): static
+    public function addConfigureArgs(string ...$args): static
     {
         $this->configure_args = [...$this->configure_args, ...$args];
         return $this;
@@ -126,7 +126,7 @@ class UnixAutoconfExecutor extends Executor
     /**
      * Remove some configure args, to bypass the configure option checking for some libs.
      */
-    public function removeConfigureArgs(...$args): static
+    public function removeConfigureArgs(string ...$args): static
     {
         $this->configure_args = array_diff($this->configure_args, $args);
         return $this;

src/StaticPHP/Runtime/Executor/UnixCMakeExecutor.php

@@ -135,7 +135,7 @@ class UnixCMakeExecutor extends Executor
     /**
      * Add configure args.
      */
-    public function addConfigureArgs(...$args): static
+    public function addConfigureArgs(string ...$args): static
     {
         $this->configure_args = [...$this->configure_args, ...$args];
         return $this;
@@ -144,7 +144,7 @@ class UnixCMakeExecutor extends Executor
     /**
      * Remove some configure args, to bypass the configure option checking for some libs.
      */
-    public function removeConfigureArgs(...$args): static
+    public function removeConfigureArgs(string ...$args): static
     {
         $this->ignore_args = [...$this->ignore_args, ...$args];
         return $this;

src/StaticPHP/Runtime/Executor/WindowsCMakeExecutor.php

@@ -99,7 +99,7 @@ class WindowsCMakeExecutor extends Executor
     /**
      * Add configure args.
      */
-    public function addConfigureArgs(...$args): static
+    public function addConfigureArgs(string ...$args): static
     {
         $this->configure_args = [...$this->configure_args, ...$args];
         return $this;
@@ -108,7 +108,7 @@ class WindowsCMakeExecutor extends Executor
     /**
      * Remove some configure args, to bypass the configure option checking for some libs.
      */
-    public function removeConfigureArgs(...$args): static
+    public function removeConfigureArgs(string ...$args): static
     {
         $this->ignore_args = [...$this->ignore_args, ...$args];
         return $this;

src/StaticPHP/Util/InteractiveTerm.php

@@ -17,8 +17,8 @@ class InteractiveTerm
 
     public static function notice(string $message, bool $indent = false): void
     {
-        $no_ansi = ApplicationContext::get(InputInterface::class)?->getOption('no-ansi') ?? false;
+        $no_ansi = (bool) ApplicationContext::get(InputInterface::class)->getOption('no-ansi');
-        $output = ApplicationContext::get(OutputInterface::class) ?? new ConsoleOutput();
+        $output = ApplicationContext::get(OutputInterface::class);
         if ($output->isVerbose()) {
             logger()->notice(strip_ansi_colors($message));
         } else {
@@ -29,8 +29,8 @@ class InteractiveTerm
 
     public static function success(string $message, bool $indent = false): void
     {
-        $no_ansi = ApplicationContext::get(InputInterface::class)?->getOption('no-ansi') ?? false;
+        $no_ansi = (bool) ApplicationContext::get(InputInterface::class)->getOption('no-ansi');
-        $output = ApplicationContext::get(OutputInterface::class) ?? new ConsoleOutput();
+        $output = ApplicationContext::get(OutputInterface::class);
         if ($output->isVerbose()) {
             logger()->info(strip_ansi_colors($message));
         } else {
@@ -41,8 +41,8 @@ class InteractiveTerm
 
     public static function plain(string $message, string $level = 'info'): void
     {
-        $no_ansi = ApplicationContext::get(InputInterface::class)?->getOption('no-ansi') ?? false;
+        $no_ansi = (bool) ApplicationContext::get(InputInterface::class)->getOption('no-ansi');
-        $output = ApplicationContext::get(OutputInterface::class) ?? new ConsoleOutput();
+        $output = ApplicationContext::get(OutputInterface::class);
         if ($output->isVerbose()) {
             match ($level) {
                 'debug' => logger()->debug(strip_ansi_colors($message)),
@@ -59,8 +59,8 @@ class InteractiveTerm
 
     public static function info(string $message): void
     {
-        $no_ansi = ApplicationContext::get(InputInterface::class)?->getOption('no-ansi') ?? false;
+        $no_ansi = (bool) ApplicationContext::get(InputInterface::class)->getOption('no-ansi');
-        $output = ApplicationContext::get(OutputInterface::class) ?? new ConsoleOutput();
+        $output = ApplicationContext::get(OutputInterface::class);
         if (!$output->isVerbose()) {
             $output->writeln(($no_ansi ? 'strip_ansi_colors' : 'strval')(ConsoleColor::green('▶ ') . $message));
         }
@@ -69,8 +69,8 @@ class InteractiveTerm
 
     public static function error(string $message, bool $indent = true): void
     {
-        $no_ansi = ApplicationContext::get(InputInterface::class)?->getOption('no-ansi') ?? false;
+        $no_ansi = (bool) ApplicationContext::get(InputInterface::class)->getOption('no-ansi');
-        $output = ApplicationContext::get(OutputInterface::class) ?? new ConsoleOutput();
+        $output = ApplicationContext::get(OutputInterface::class);
         if ($output->isVerbose()) {
             logger()->error(strip_ansi_colors($message));
         } else {
@@ -86,16 +86,16 @@ class InteractiveTerm
 
     public static function setMessage(string $message): void
     {
-        $no_ansi = ApplicationContext::get(InputInterface::class)?->getOption('no-ansi') ?? false;
+        $no_ansi = (bool) ApplicationContext::get(InputInterface::class)->getOption('no-ansi');
         self::$indicator?->setMessage(($no_ansi ? 'strip_ansi_colors' : 'strval')($message));
         logger()->debug(strip_ansi_colors($message));
     }
 
     public static function finish(string $message, bool $status = true): void
     {
-        $no_ansi = ApplicationContext::get(InputInterface::class)?->getOption('no-ansi') ?? false;
+        $no_ansi = (bool) ApplicationContext::get(InputInterface::class)->getOption('no-ansi');
         $message = $no_ansi ? strip_ansi_colors($message) : $message;
-        $output = ApplicationContext::get(OutputInterface::class) ?? new ConsoleOutput();
+        $output = ApplicationContext::get(OutputInterface::class);
         if ($output->isVerbose()) {
             if ($status) {
                 logger()->info($message);
@@ -116,8 +116,8 @@ class InteractiveTerm
 
     public static function indicateProgress(string $message): void
     {
-        $no_ansi = ApplicationContext::get(InputInterface::class)?->getOption('no-ansi') ?? false;
+        $no_ansi = (bool) ApplicationContext::get(InputInterface::class)->getOption('no-ansi');
-        $output = ApplicationContext::get(OutputInterface::class) ?? new ConsoleOutput();
+        $output = ApplicationContext::get(OutputInterface::class);
         if ($output->isVerbose()) {
             logger()->info(strip_ansi_colors($message));
             return;