feat: support Giphy and external GIF embeds

README.md

@@ -29,6 +29,8 @@ composer setup
 composer dev
 ```
 
+Giphy share links and verified public HTTPS `.gif` links play inline from their external host. GIFs autoplay while visible; reduced-motion users press Play.
+
 Run `composer test` before opening a pull request.
 
 ## License

app/Actions/UpdateLinkPreview.php

@@ -6,9 +6,12 @@
 
 use App\Contracts\Services\DnsResolver;
 use App\Models\LinkPreview;
+use App\Services\LinkPreviews\LimitedResponseBody;
+use App\Services\PreviewLinkProviders\GifPreviewLink;
 use Dom\HTMLDocument;
 use GuzzleHttp\Exception\ResponseException;
 use GuzzleHttp\Psr7\Utils;
+use GuzzleHttp\RequestOptions;
 use Illuminate\Http\Client\ConnectionException;
 use Illuminate\Http\Client\Response;
 use Illuminate\Support\Facades\Http;
@@ -17,7 +20,7 @@
 use Uri\WhatWg\Url;
 
 /**
- * @phpstan-type Metadata array{title: string|null, description: string|null, image_url: string|null, site_name: string|null}
+ * @phpstan-type Metadata array{title: string|null, description: string|null, image_url: string|null, site_name: string|null, gif_url: string|null}
  */
 final readonly class UpdateLinkPreview
 {
@@ -59,9 +62,10 @@
         'description' => null,
         'image_url' => null,
         'site_name' => null,
+        'gif_url' => null,
     ];
 
-    public function __construct(private DnsResolver $dns)
+    public function __construct(private DnsResolver $dns, private GifPreviewLink $gifs)
     {
         //
     }
@@ -84,21 +88,30 @@ public function handle(LinkPreview $linkPreview): void
     private function fetchMetadata(string $url): array
     {
         $page = Url::parse($url);
+        $isGif = $this->gifs->isGifUrl($page);
 
         for ($hop = 0; $hop <= self::MAX_REDIRECTS && $page instanceof Url; $hop++) {
+            if ($isGif && ($page->getScheme() !== 'https' || $page->getPort() !== null)) {
+                return self::NO_METADATA;
+            }
+
             $address = $this->publicAddress($page);
 
             if ($address === null) {
                 return self::NO_METADATA;
             }
 
-            $response = $this->get($page, $address);
+            $response = $this->get($page, $address, $isGif);
 
             if ($response->serverError() || $response->tooManyRequests()) {
                 $response->throw();
             }
 
             if (! $response->redirect()) {
+                if ($isGif && $response->successful()) {
+                    return $this->gifMetadata($response, $page);
+                }
+
                 return $response->successful() && $this->isHtml($response)
                     ? $this->parse($this->body($response), $page)
                     : self::NO_METADATA;
@@ -141,12 +154,12 @@ private function isPublic(string $address): bool
      * (by that limit or by the timeout) is still used, as metadata lives at the top of the page. English is asked for
      * explicitly, as sites such as YouTube otherwise pick the language from the server's location.
      */
-    private function get(Url $url, string $address): Response
+    private function get(Url $url, string $address, bool $isGif): Response
     {
         $port = $url->getPort() ?? ($url->getScheme() === 'https' ? 443 : 80);
 
         $request = Http::withUserAgent(sprintf('Mozilla/5.0 (compatible; devnull-linkpreview/1.0; +%s)', config()->string('app.url')))
-            ->accept('text/html')
+            ->accept($isGif ? GifPreviewLink::CONTENT_TYPE : 'text/html')
             ->withHeaders(['Accept-Language' => 'en-US,en;q=0.9'])
             ->connectTimeout(3)
             ->timeout(5)
@@ -159,6 +172,11 @@ private function get(Url $url, string $address): Response
                 ],
             ]);
 
+        if ($isGif) {
+            $request->withHeaders(['Range' => sprintf('bytes=0-%d', GifPreviewLink::HEADER_BYTES - 1)])
+                ->withOptions([RequestOptions::SINK => new LimitedResponseBody(GifPreviewLink::HEADER_BYTES)]);
+        }
+
         try {
             return $request->get($url->toAsciiString());
         } catch (ConnectionException $connectionException) {
@@ -172,19 +190,31 @@ private function get(Url $url, string $address): Response
         }
     }
 
+    /**
+     * @return Metadata
+     */
+    private function gifMetadata(Response $response, Url $page): array
+    {
+        return [...self::NO_METADATA, 'gif_url' => $this->gifs->getVerifiedUrl(
+            $page,
+            $response->header('Content-Type'),
+            $this->body($response, GifPreviewLink::HEADER_BYTES),
+        )];
+    }
+
     private function isHtml(Response $response): bool
     {
         $mediaType = mb_strtolower(mb_trim(Str::before($response->header('Content-Type'), ';')));
 
         return in_array($mediaType, ['text/html', 'application/xhtml+xml'], true);
     }
 
-    private function body(Response $response): string
+    private function body(Response $response, int $limit = self::MAX_BODY_BYTES): string
     {
         $body = $response->toPsrResponse()->getBody();
         $body->rewind();
 
-        return Utils::copyToString($body, self::MAX_BODY_BYTES);
+        return Utils::copyToString($body, $limit);
     }
 
     /**
@@ -205,6 +235,7 @@ private function parse(string $html, Url $page): array
             'description' => $this->text([$meta['og:description'] ?? '', $meta['twitter:description'] ?? '', $meta['description'] ?? ''], 500),
             'image_url' => $this->imageUrl([$meta['og:image:secure_url'] ?? '', $meta['og:image'] ?? '', $meta['twitter:image'] ?? ''], $page),
             'site_name' => $this->text([$meta['og:site_name'] ?? ''], 100),
+            'gif_url' => null,
         ];
     }
 

app/Dto/Embed.php

@@ -24,8 +24,6 @@ private function __construct(
     }
 
     /**
-     * The poster stands in for the player until it is played, for when the link's own preview has no image.
-     *
      * @param  array<string, string|int>  $query
      */
     public static function video(string $provider, string $src, array $query = [], string $aspectRatio = '16 / 9', ?string $poster = null): self
@@ -41,6 +39,11 @@ public static function fixed(string $provider, EmbedKind $kind, string $src, int
         return new self($provider, $kind, self::withQuery($src, $query), null, $height);
     }
 
+    public static function gif(string $provider, string $src, ?string $poster = null): self
+    {
+        return new self($provider, EmbedKind::Gif, $src, null, null, $poster);
+    }
+
     /**
      * @return array{provider: string, kind: string, src: string, aspect_ratio: string|null, height: int|null, poster: string|null}
      */

app/Enums/EmbedKind.php

@@ -9,4 +9,5 @@ enum EmbedKind: string
     case Video = 'video';
     case Audio = 'audio';
     case Code = 'code';
+    case Gif = 'gif';
 }

app/Models/LinkPreview.php

@@ -20,6 +20,7 @@
  * @property-read string|null $description
  * @property-read string|null $image_url
  * @property-read string|null $site_name
+ * @property-read string|null $gif_url
  * @property-read CarbonInterface|null $fetched_at
  * @property-read CarbonInterface $created_at
  * @property-read CarbonInterface $updated_at
@@ -51,6 +52,7 @@ public function casts(): array
             'description' => 'string',
             'image_url' => 'string',
             'site_name' => 'string',
+            'gif_url' => 'string',
             'fetched_at' => 'datetime',
             'created_at' => 'datetime',
             'updated_at' => 'datetime',
@@ -62,6 +64,6 @@ public function casts(): array
      */
     public function toArray(): array
     {
-        return [...parent::toArray(), 'is_pending' => $this->fetched_at === null, 'embed' => resolve(Embeds::class)->for($this->url)?->toArray()];
+        return [...parent::toArray(), 'is_pending' => $this->fetched_at === null, 'embed' => resolve(Embeds::class)->for($this->url, $this->gif_url)?->toArray()];
     }
 }

app/Services/EmbedProviders/Giphy.php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\EmbedProviders;
+
+use App\Contracts\Services\EmbedProvider;
+use App\Dto\Embed;
+use Illuminate\Support\Str;
+use Uri\WhatWg\Url;
+
+final readonly class Giphy implements EmbedProvider
+{
+    private const array SUPPORTED_SCHEMES = ['http', 'https'];
+
+    private const array SUPPORTED_HOSTS = ['giphy.com', 'www.giphy.com'];
+
+    private const int PATH_SEGMENT_COUNT = 2;
+
+    public function embed(Url $url): ?Embed
+    {
+        if (! $this->supportsUrl($url)) {
+            return null;
+        }
+
+        $identifier = $this->getGifId($url->getPath());
+
+        if ($identifier === null) {
+            return null;
+        }
+
+        $mediaUrl = "https://media.giphy.com/media/{$identifier}";
+
+        return Embed::gif('GIPHY', "{$mediaUrl}/giphy.gif", "{$mediaUrl}/giphy_s.gif");
+    }
+
+    private function supportsUrl(Url $url): bool
+    {
+        if (! in_array($url->getScheme(), self::SUPPORTED_SCHEMES, true)) {
+            return false;
+        }
+
+        if (! in_array($url->getAsciiHost(), self::SUPPORTED_HOSTS, true)) {
+            return false;
+        }
+
+        if (($url->getUsername() ?? '') !== '') {
+            return false;
+        }
+
+        if (($url->getPassword() ?? '') !== '') {
+            return false;
+        }
+
+        return $url->getPort() === null;
+    }
+
+    private function getGifId(string $path): ?string
+    {
+        $segments = explode('/', mb_trim($path, '/'));
+
+        if (count($segments) !== self::PATH_SEGMENT_COUNT) {
+            return null;
+        }
+
+        [$section, $slug] = $segments;
+        $identifier = match (Str::lower($section)) {
+            'gifs' => Str::afterLast($slug, '-'),
+            'embed' => $slug,
+            default => '',
+        };
+
+        return ctype_alnum($identifier) ? $identifier : null;
+    }
+}

app/Services/Embeds.php

@@ -11,12 +11,14 @@
 
 final readonly class Embeds
 {
+    private const string GIF_PROVIDER = 'GIF';
+
     public function __construct(private Container $container)
     {
         //
     }
 
-    public function for(string $url): ?Embed
+    public function for(string $url, ?string $gifUrl = null): ?Embed
     {
         $parsed = Url::parse($url);
 
@@ -32,7 +34,13 @@ public function for(string $url): ?Embed
             }
         }
 
-        return null;
+        $only = config()->array('embeds.only');
+
+        if ($gifUrl === null || ($only !== [] && ! in_array('gif', $only, true))) {
+            return null;
+        }
+
+        return Embed::gif(self::GIF_PROVIDER, $gifUrl);
     }
 
     /**

app/Services/LinkPreviews/LimitedResponseBody.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\LinkPreviews;
+
+use GuzzleHttp\Psr7\Stream;
+use GuzzleHttp\Psr7\Utils;
+
+final class LimitedResponseBody extends Stream
+{
+    private const string BINARY_ENCODING = '8bit';
+
+    public function __construct(private readonly int $maxBytes)
+    {
+        parent::__construct(Utils::tryFopen('php://temp', 'w+'));
+    }
+
+    public function write(string $string): int
+    {
+        $remaining = max(0, $this->maxBytes - $this->tell());
+
+        return parent::write(mb_substr($string, 0, $remaining, self::BINARY_ENCODING));
+    }
+}