fix: resolve all PHPStan level 8 errors

- Add PHPDoc annotations for array types in BookStackClient
- Add array type annotations to BookStackClientInterface
- Fix exception classes: use self instead of static in final classes
- Add proper array type annotations to all DTOs
- Fix SyncService return type with explicit array shape
- Fix BookStackExportCommand parameter types
- Update Facade PHPDoc with precise return types

Author: abkrim

phpstan.neon.dist

@@ -2,7 +2,7 @@ includes:
     - phpstan-baseline.neon
 
 parameters:
-    level: 5
+    level: 8
     paths:
         - src
         - config

src/Api/BookStackClient.php

@@ -58,6 +58,9 @@ public function getShelf(int $id): ShelfDTO
         return ShelfDTO::fromArray($response);
     }
 
+    /**
+     * @param  array<int>  $bookIds
+     */
     public function createShelf(string $name, ?string $description = null, array $bookIds = []): ShelfDTO
     {
         $data = ['name' => $name];
@@ -73,6 +76,9 @@ public function createShelf(string $name, ?string $description = null, array $bo
         return ShelfDTO::fromArray($response);
     }
 
+    /**
+     * @param  array<int>|null  $bookIds
+     */
     public function updateShelf(int $id, ?string $name = null, ?string $description = null, ?array $bookIds = null): ShelfDTO
     {
         $data = array_filter([
@@ -294,6 +300,10 @@ public function search(string $query, int $count = 100, int $offset = 0): array
     }
 
     // HTTP methods
+    /**
+     * @param  array<string, mixed>  $query
+     * @return array<string, mixed>
+     */
     private function get(string $endpoint, array $query = []): array
     {
         try {
@@ -320,6 +330,10 @@ private function getRaw(string $endpoint): string
         }
     }
 
+    /**
+     * @param  array<string, mixed>  $data
+     * @return array<string, mixed>
+     */
     private function post(string $endpoint, array $data = []): array
     {
         try {
@@ -333,6 +347,10 @@ private function post(string $endpoint, array $data = []): array
         }
     }
 
+    /**
+     * @param  array<string, mixed>  $data
+     * @return array<string, mixed>
+     */
     private function put(string $endpoint, array $data = []): array
     {
         try {
@@ -357,6 +375,9 @@ private function delete(string $endpoint): void
         }
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     private function parseResponse(ResponseInterface $response): array
     {
         $body = (string) $response->getBody();

src/BookStackSync.php

@@ -86,6 +86,9 @@ public function shelf(int $id): ShelfDTO
         return $this->client->getShelf($id);
     }
 
+    /**
+     * @param  array<int>  $bookIds
+     */
     public function createShelf(string $name, ?string $description = null, array $bookIds = []): ShelfDTO
     {
         return $this->client->createShelf($name, $description, $bookIds);

src/Commands/BookStackExportCommand.php

@@ -22,13 +22,13 @@ class BookStackExportCommand extends Command
 
     public function handle(BookStackSync $bookstack): int
     {
-        $type = $this->argument('type');
+        $type = (string) $this->argument('type');
         $id = (int) $this->argument('id');
-        $formatStr = $this->option('format');
+        $formatStr = (string) $this->option('format');
         $output = $this->option('output');
 
         // Validate type
-        if (! in_array($type, ['book', 'chapter', 'page'])) {
+        if (! in_array($type, ['book', 'chapter', 'page'], true)) {
             $this->error("Invalid type '{$type}'. Must be: book, chapter, or page");
 
             return self::FAILURE;
@@ -48,8 +48,7 @@ public function handle(BookStackSync $bookstack): int
             $content = match ($type) {
                 'book' => $bookstack->exportBook($id, $format),
                 'chapter' => $bookstack->client()->exportChapter($id, $format),
-                'page' => $bookstack->exportPage($id, $format),
-                default => throw new \InvalidArgumentException("Invalid type: {$type}"),
+                default => $bookstack->exportPage($id, $format),
             };
 
             if ($output) {

src/Contracts/BookStackClientInterface.php

@@ -21,8 +21,14 @@ public function listShelves(int $count = 100, int $offset = 0): array;
 
     public function getShelf(int $id): ShelfDTO;
 
+    /**
+     * @param  array<int>  $bookIds
+     */
     public function createShelf(string $name, ?string $description = null, array $bookIds = []): ShelfDTO;
 
+    /**
+     * @param  array<int>|null  $bookIds
+     */
     public function updateShelf(int $id, ?string $name = null, ?string $description = null, ?array $bookIds = null): ShelfDTO;
 
     public function deleteShelf(int $id): bool;

src/DTOs/BaseDTO.php

@@ -16,6 +16,9 @@ public function __construct(
         public readonly ?string $updatedAt = null,
     ) {}
 
+    /**
+     * @return array<string, mixed>
+     */
     public function toArray(): array
     {
         return array_filter(
@@ -24,6 +27,9 @@ public function toArray(): array
         );
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     public function jsonSerialize(): array
     {
         return $this->toArray();
@@ -50,5 +56,8 @@ protected static function extractUserId(mixed $value): ?int
         return null;
     }
 
+    /**
+     * @param  array<string, mixed>  $data
+     */
     abstract public static function fromArray(array $data): static;
 }

src/DTOs/BookDTO.php

@@ -26,6 +26,9 @@ public function __construct(
         parent::__construct($id, $name, $slug, $createdAt, $updatedAt);
     }
 
+    /**
+     * @param  array<string, mixed>  $data
+     */
     public static function fromArray(array $data): static
     {
         $contents = [];

src/DTOs/ChapterDTO.php

@@ -28,6 +28,9 @@ public function __construct(
         parent::__construct($id, $name, $slug, $createdAt, $updatedAt);
     }
 
+    /**
+     * @param  array<string, mixed>  $data
+     */
     public static function fromArray(array $data): static
     {
         $pages = [];

src/DTOs/PageDTO.php

@@ -31,6 +31,9 @@ public function __construct(
         parent::__construct($id, $name, $slug, $createdAt, $updatedAt);
     }
 
+    /**
+     * @param  array<string, mixed>  $data
+     */
     public static function fromArray(array $data): static
     {
         return new self(

src/DTOs/SearchResultDTO.php

@@ -8,6 +8,9 @@
 
 final class SearchResultDTO extends BaseDTO
 {
+    /**
+     * @param  array<string, mixed>|null  $tags
+     */
     public function __construct(
         ?int $id = null,
         ?string $name = null,
@@ -24,6 +27,9 @@ public function __construct(
         parent::__construct($id, $name, $slug, $createdAt, $updatedAt);
     }
 
+    /**
+     * @param  array<string, mixed>  $data
+     */
     public static function fromArray(array $data): static
     {
         $type = null;