From e7e4e4311f94377fd6eb303a96304ee495808a05 Mon Sep 17 00:00:00 2001
From: Michael Beck <mambax7@gmail.com>
Date: Thu, 2 Jul 2026 21:16:20 -0400
Subject: [PATCH] fix(phpstan): declare XOOPS core classes via scanFiles so
 extends resolves
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The baseline referenced stubs/xoops.stub via `stubFiles`, which only refines
signatures of classes PHPStan can already discover — it does not register
stub-only classes as existing. Any module that extends a core class (e.g. a
preload extending XoopsPreloadItem, or an object extending XoopsObject) then
hits a non-ignorable class.notFound that cannot be baselined, failing
`composer qa`.

- phpstan.neon.dist: use `scanFiles` instead of `stubFiles` so the stub's
  classes are registered as existing and extends/implements resolve.
- stubs/xoops.stub: add the XoopsPreloadItem base class, extended by every
  module preload.

Went unnoticed because module-devops itself has no code extending a XOOPS
class; it only surfaces once the baseline is applied to a real module.
---
 phpstan.neon.dist | 9 ++++++---
 stubs/xoops.stub  | 5 +++++
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/phpstan.neon.dist b/phpstan.neon.dist
index 1b9337a..3ac9a42 100644
--- a/phpstan.neon.dist
+++ b/phpstan.neon.dist
@@ -35,9 +35,12 @@ parameters:
         - rector.php (?)
         - .php-cs-fixer.dist.php (?)
 
-    # XOOPS core classes (XoopsObject, handlers, Criteria, $xoopsDB, …) are not
-    # composer-autoloadable during analysis. Signatures come from this stub.
-    stubFiles:
+    # XOOPS core classes (XoopsObject, XoopsPreloadItem, handlers, Criteria, …) are
+    # not composer-autoloadable during analysis. Use `scanFiles` (NOT `stubFiles`) so
+    # the classes are registered as existing and `extends`/`implements` resolve —
+    # `stubFiles` only refines signatures of classes PHPStan can already discover, so a
+    # module extending a core class would hit a non-ignorable `class.notFound`.
+    scanFiles:
         - stubs/xoops.stub
 
     bootstrapFiles:
diff --git a/stubs/xoops.stub b/stubs/xoops.stub
index 380167c..3faa96b 100644
--- a/stubs/xoops.stub
+++ b/stubs/xoops.stub
@@ -175,6 +175,11 @@ namespace {
     {
         public static function getByDirname(string $dirname): mixed {}
     }
+
+    class XoopsPreloadItem
+    {
+        public function __construct() {}
+    }
 }
 
 namespace Xmf\Module {