From 149f86bfaa0ffae2837e31a2fc305afb31e0fcf3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 10 Aug 2026 22:16:22 +0000
Subject: [PATCH] fix(kernel): correct the options shape accepted by
 AspectKernel::init()

The inline shape on init() was narrower than what the kernel actually
accepts and than what the KernelOptions type on the same class declares:

* "appDir" required a literal-string, so any application computing its
  root directory at runtime (a framework bridge calling base_path(), a
  path read from configuration, $_SERVER, getcwd(), ...) was reported as
  an invalid argument;
* "includePaths" and "excludePaths" were typed as array{}, i.e. only an
  empty array literal was accepted, even though listing directories is
  the entire purpose of both options.

Both are normalized by normalizeOptions(), which accepts any string for
"appDir" and filters both path lists with is_string(), so the annotation
was the only thing rejecting valid calls. Only the bundled demo passed a
literal __DIR__-based "appDir" and no include paths at all, which is why
this stayed unnoticed.

Express the accepted options as a UserKernelOptions type sitting next to
KernelOptions, so both stay in sync: same value types, all keys optional.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HRJrrw79a8r4YTLyAxzJTF
---
 src/Core/AspectKernel.php | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/src/Core/AspectKernel.php b/src/Core/AspectKernel.php
index e0a903fc..25364193 100644
--- a/src/Core/AspectKernel.php
+++ b/src/Core/AspectKernel.php
@@ -41,6 +41,16 @@
  *   excludePaths: string[],
  *   containerClass: class-string<AspectContainer>
  * }
+ * @phpstan-type UserKernelOptions array{
+ *   debug?: bool,
+ *   appDir?: string,
+ *   cacheDir?: string|null,
+ *   cacheFileMode?: int,
+ *   features?: int,
+ *   includePaths?: string[],
+ *   excludePaths?: string[],
+ *   containerClass?: class-string<AspectContainer>
+ * }
  */
 abstract class AspectKernel
 {
@@ -102,16 +112,7 @@ public static function getInstance(): self
     /**
      * Init the kernel and make adjustments
      *
-     * @phpstan-param array{
-     *   debug?: bool,
-     *   appDir?: literal-string&non-falsy-string,
-     *   cacheDir?: string|null,
-     *   cacheFileMode?: int,
-     *   features?: int,
-     *   includePaths?: array{},
-     *   excludePaths?: array{},
-     *   containerClass?: class-string<AspectContainer>
-     * } $options Additional kernel options
+     * @phpstan-param UserKernelOptions $options Additional kernel options
      */
     public function init(array $options = []): void
     {