From 591fa68cc8110ad67c28c7ce46539f016d5bdee8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Piotr=20Ha=C5=82as?= <piotr.h@decodo.com>
Date: Sat, 2 May 2026 23:00:44 +0200
Subject: [PATCH] fix: handle null from shell_exec('nproc') in
 Utils::cpuCount() (#150)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

shell_exec('nproc') returns null when nproc is not available on the
system (e.g., minimal containers without coreutils). Casting null to
int yields 0, causing cpuCount() to return 0 — downstream this means
zero workers spawned in ServerWorker.

Fix: explicitly check for null, add trim() for shell output, and
return 1 as safe fallback.
---
 src/Utils.php       | 18 ++++++++++++++----
 tests/UtilsTest.php |  9 +++++++++
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/src/Utils.php b/src/Utils.php
index 82c2689..d8e6948 100644
--- a/src/Utils.php
+++ b/src/Utils.php
@@ -24,10 +24,20 @@ public static function cpuCount(): int
             return 1;
         }
 
-        return \strtolower(\PHP_OS) === 'darwin'
-            ? (int) shell_exec('sysctl -n machdep.cpu.core_count')
-            : (int) shell_exec('nproc')
-        ;
+        $command = \strtolower(\PHP_OS) === 'darwin'
+            ? 'sysctl -n machdep.cpu.core_count'
+            : 'nproc';
+
+        $result = shell_exec($command);
+
+        // shell_exec returns null (no output) or false (command failed)
+        if (!\is_string($result)) {
+            return 1;
+        }
+
+        $count = (int) \trim($result);
+
+        return $count > 0 ? $count : 1;
     }
 
     public static function isWindows(): bool
diff --git a/tests/UtilsTest.php b/tests/UtilsTest.php
index 1eef9cc..110366b 100644
--- a/tests/UtilsTest.php
+++ b/tests/UtilsTest.php
@@ -25,6 +25,15 @@ public function testCpuCountReturnsPositiveInteger(): void
         $this->assertGreaterThanOrEqual(1, $cpuCount);
     }
 
+    public function testCpuCountNeverReturnsZero(): void
+    {
+        // Regression test for #150: Utils::cpuCount() must NEVER return 0,
+        // even when shell_exec('nproc') returns null (command not available)
+        // or produces empty/unexpected output. Returning 0 would cause
+        // downstream issues: zero workers spawned in ServerWorker.
+        $this->assertNotSame(0, Utils::cpuCount());
+    }
+
     /**
      * @requires OS Windows
      */