feat: improve type safety with PHPStan (590→0 errors)

Comprehensively resolve all 590 PHPStan errors to improve type safety
and code quality across the entire codebase while maintaining PHP 7.4+
compatibility.
PHPStan: 0 errors (level max + strict rules)

Key improvements:
- Replace elvis operator (?:) with explicit null checks
- Replace empty() with explicit type-safe comparisons
- Add PHPDoc type annotations for better static analysis
- Replace == with === for strict comparisons
- Add null-safety checks for DOM/XPath operations
- Improve type inference for magic properties and dynamic methods
- Add PHP 7.4/8.x compatible type handling (resource vs CurlHandle)

Modified components:
- Core: Embed, Extractor, Document, EmbedCode, etc. (13 files)
- HTTP layer: Crawler, CurlClient, CurlDispatcher (5 files)
- Detectors: All core detectors (17 files)
- Adapters: Archive, Gist, ImageShack, Twitter, Wikipedia, etc. (60 files)
- Data sources: OEmbed, LinkedData, Metas, QueryResult (4 files)

Author: uzulla

.github/workflows/test.yml

@@ -42,3 +42,29 @@ jobs:
 
             - name: Tests
               run: composer test
+
+    phpstan:
+        name: PHPStan Static Analysis
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+
+            - name: Install PHP
+              uses: shivammathur/setup-php@v2
+              with:
+                  php-version: 8.4
+
+            - name: Cache PHP dependencies
+              uses: actions/cache@v4
+              with:
+                  path: vendor
+                  key: ${{ runner.os }}-php-8.4-composer-${{ hashFiles('**/composer.json') }}
+                  restore-keys: ${{ runner.os }}-php-8.4-composer-
+
+            - name: Install dependencies
+              run: composer install
+
+            - name: Run PHPStan
+              run: composer phpstan

phpstan.dist.neon

@@ -6,8 +6,10 @@ parameters:
     paths:
         - src
 #        - tests
-        - issue-report/tests
+    excludePaths:
+        - tests/cache
+        - tests/fixtures
     checkMissingCallableSignature: true
     checkUninitializedProperties: true
     checkTooWideReturnTypesInProtectedAndPublicMethods: true
-    checkImplicitMixed: true
+    checkImplicitMixed: true

src/Adapters/Archive/Api.php

@@ -9,6 +9,9 @@ class Api
 {
     use HttpApiTrait;
 
+    /**
+     * @return array<string, mixed>
+     */
     protected function fetchData(): array
     {
         $this->endpoint = $this->extractor->getUri()->withQuery('output=json');

src/Adapters/Archive/Detectors/AuthorName.php

@@ -3,15 +3,18 @@
 
 namespace Embed\Adapters\Archive\Detectors;
 
+use Embed\Adapters\Archive\Extractor;
 use Embed\Detectors\AuthorName as Detector;
 
 class AuthorName extends Detector
 {
     public function detect(): ?string
     {
-        $api = $this->extractor->getApi();
+        /** @var Extractor $extractor */
+        $extractor = $this->extractor;
+        $api = $extractor->getApi();
 
-        return $api->str('metadata', 'creator')
-            ?: parent::detect();
+        $result = $api->str('metadata', 'creator');
+        return $result !== null ? $result : parent::detect();
     }
 }

src/Adapters/Archive/Detectors/Description.php

@@ -3,15 +3,18 @@
 
 namespace Embed\Adapters\Archive\Detectors;
 
+use Embed\Adapters\Archive\Extractor;
 use Embed\Detectors\Description as Detector;
 
 class Description extends Detector
 {
     public function detect(): ?string
     {
-        $api = $this->extractor->getApi();
+        /** @var Extractor $extractor */
+        $extractor = $this->extractor;
+        $api = $extractor->getApi();
 
-        return $api->str('metadata', 'extract')
-            ?: parent::detect();
+        $result = $api->str('metadata', 'extract');
+        return $result !== null ? $result : parent::detect();
     }
 }

src/Adapters/Archive/Detectors/PublishedTime.php

@@ -4,17 +4,25 @@
 namespace Embed\Adapters\Archive\Detectors;
 
 use DateTime;
+use Embed\Adapters\Archive\Extractor;
 use Embed\Detectors\PublishedTime as Detector;
 
 class PublishedTime extends Detector
 {
     public function detect(): ?DateTime
     {
-        $api = $this->extractor->getApi();
+        /** @var Extractor $extractor */
+        $extractor = $this->extractor;
+        $api = $extractor->getApi();
 
-        return $api->time('metadata', 'publicdate')
-            ?: $api->time('metadata', 'addeddate')
-            ?: $api->time('metadata', 'date')
-            ?: parent::detect();
+        $fields = ['publicdate', 'addeddate', 'date'];
+        foreach ($fields as $field) {
+            $result = $api->time('metadata', $field);
+            if ($result !== null) {
+                return $result;
+            }
+        }
+
+        return parent::detect();
     }
 }

src/Adapters/Archive/Detectors/Title.php

@@ -3,15 +3,18 @@
 
 namespace Embed\Adapters\Archive\Detectors;
 
+use Embed\Adapters\Archive\Extractor;
 use Embed\Detectors\Title as Detector;
 
 class Title extends Detector
 {
     public function detect(): ?string
     {
-        $api = $this->extractor->getApi();
+        /** @var Extractor $extractor */
+        $extractor = $this->extractor;
+        $api = $extractor->getApi();
 
-        return $api->str('metadata', 'title')
-            ?: parent::detect();
+        $result = $api->str('metadata', 'title');
+        return $result !== null ? $result : parent::detect();
     }
 }

src/Adapters/Archive/Extractor.php

@@ -7,17 +7,21 @@
 
 class Extractor extends Base
 {
-    private Api $api;
+    private ?Api $api = null;
 
     public function getApi(): Api
     {
+        if ($this->api === null) {
+            $this->api = new Api($this);
+        }
         return $this->api;
     }
 
+    /**
+     * @return array<string, \Embed\Detectors\Detector>
+     */
     public function createCustomDetectors(): array
     {
-        $this->api = new Api($this);
-
         return [
             'title' => new Detectors\Title($this),
             'description' => new Detectors\Description($this),

src/Adapters/Bandcamp/Extractor.php

@@ -7,6 +7,9 @@
 
 class Extractor extends Base
 {
+    /**
+     * @return array<string, \Embed\Detectors\Detector>
+     */
     public function createCustomDetectors(): array
     {
         return [

src/Adapters/CadenaSer/Detectors/Code.php

@@ -13,8 +13,8 @@ class Code extends Detector
 {
     public function detect(): ?EmbedCode
     {
-        return parent::detect()
-            ?: $this->fallback();
+        $result = parent::detect();
+        return $result !== null ? $result : $this->fallback();
     }
 
     private function fallback(): ?EmbedCode