Merge pull request #563 from sasezaki/generics

refactor: add PHPStan generic type annotations and simplify detector implementations

Enhance type safety with PHPStan generics and refactor detectors

This merge introduces generic type annotations using @extends and @template-extends across all Extractor and Detector classes in adapters (Archive, Gist, ImageShack, Twitter, Wikipedia, Facebook, Github, Flickr, etc.). It also removes redundant intermediate variables in detectors by directly accessing the API, and simplifies createCustomDetectors() return types.

Benefits include improved PHPStan type inference, better IDE support, and cleaner code overall.

Author: Vitorinox

src/Adapters/Archive/Detectors/AuthorName.php

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

src/Adapters/Archive/Detectors/Code.php

@@ -8,6 +8,9 @@
 use function Embed\html;
 use function Embed\matchPath;
 
+/**
+ * @extends Detector<\Embed\Adapters\Archive\Extractor>
+ */
 class Code extends Detector
 {
     public function detect(): ?EmbedCode

src/Adapters/Archive/Detectors/Description.php

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

src/Adapters/Archive/Detectors/ProviderName.php

@@ -5,6 +5,9 @@
 
 use Embed\Detectors\ProviderName as Detector;
 
+/**
+ * @extends Detector<\Embed\Adapters\Archive\Extractor>
+ */
 class ProviderName extends Detector
 {
     public function detect(): string

src/Adapters/Archive/Detectors/PublishedTime.php

@@ -4,16 +4,16 @@
 namespace Embed\Adapters\Archive\Detectors;
 
 use DateTime;
-use Embed\Adapters\Archive\Extractor;
 use Embed\Detectors\PublishedTime as Detector;
 
+/**
+ * @extends Detector<\Embed\Adapters\Archive\Extractor>
+ */
 class PublishedTime extends Detector
 {
     public function detect(): ?DateTime
     {
-        /** @var Extractor $extractor */
-        $extractor = $this->extractor;
-        $api = $extractor->getApi();
+        $api = $this->extractor->getApi();
 
         $fields = ['publicdate', 'addeddate', 'date'];
         foreach ($fields as $field) {

src/Adapters/Archive/Detectors/Title.php

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

src/Adapters/Archive/Extractor.php

@@ -9,6 +9,9 @@
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\UriInterface;
 
+/**
+ * @template-extends Base<\Embed\Detectors\Detector<self>>
+ */
 class Extractor extends Base
 {
     private Api $api;
@@ -28,9 +31,6 @@ public function getApi(): Api
         return $this->api;
     }
 
-    /**
-     * @return array<string, \Embed\Detectors\Detector>
-     */
     public function createCustomDetectors(): array
     {
         return [

src/Adapters/Bandcamp/Detectors/ProviderName.php

@@ -5,6 +5,9 @@
 
 use Embed\Detectors\ProviderName as Detector;
 
+/**
+ * @extends Detector<\Embed\Adapters\Bandcamp\Extractor>
+ */
 class ProviderName extends Detector
 {
     public function detect(): string

src/Adapters/Bandcamp/Extractor.php

@@ -5,11 +5,11 @@
 
 use Embed\Extractor as Base;
 
+/**
+ * @template-extends Base<\Embed\Detectors\Detector<self>>
+ */
 class Extractor extends Base
 {
-    /**
-     * @return array<string, \Embed\Detectors\Detector>
-     */
     public function createCustomDetectors(): array
     {
         return [

src/Adapters/CadenaSer/Detectors/Code.php

@@ -9,6 +9,9 @@
 use function Embed\html;
 use function Embed\matchPath;
 
+/**
+ * @extends Detector<\Embed\Adapters\CadenaSer\Extractor>
+ */
 class Code extends Detector
 {
     public function detect(): ?EmbedCode