feat(assets): Adds Asset CDN Controller (#89)

Author: silasjoisten

README.md

@@ -626,6 +626,158 @@ It works out of the box with:
 - A default TipTap editor configuration
 - Automatic rendering of registered Storyblok blocks using the `Storyblok\Bundle\Block\BlockRegistry`
 
+
+## CDN Asset Handling
+
+> [!WARNING]
+> This feature only supports **public Storyblok assets**. Private assets are not supported.
+
+The bundle provides a CDN feature that allows you to serve Storyblok assets through your own domain. This is useful for:
+- Serving assets from your own CDN
+- Applying custom caching strategies
+- Avoiding mixed content issues
+- Better control over asset delivery
+
+### Configuration
+
+First, enable the CDN route in your application:
+
+```yaml
+# config/routes/storyblok.yaml
+storyblok_cdn:
+    resource: '@StoryblokBundle/config/routes/cdn.php'
+```
+
+The CDN feature is **enabled by default** with filesystem storage at `%kernel.project_dir%/var/cdn`. It only supports public Storyblok assets.
+
+```yaml
+# config/packages/storyblok.yaml
+storyblok:
+    # ...
+
+    # CDN is enabled by default with these settings:
+    # cdn:
+    #     enabled: true
+    #     storage:
+    #         type: filesystem
+    #         path: '%kernel.project_dir%/var/cdn'
+
+    # Custom configuration example:
+    cdn:
+        storage:
+            type: filesystem
+            path: '%kernel.project_dir%/var/cdn'
+        cache:
+            public: true
+            max_age: 31536000   # 1 year
+            smax_age: 31536000
+```
+
+#### Disabling CDN
+
+To disable the CDN feature and remove all related services:
+
+```yaml
+storyblok:
+    cdn: false
+```
+
+### Usage in Twig
+
+#### Generating CDN URLs
+
+Use the `cdn_url` function to generate a URL that serves the asset through your CDN:
+
+```twig
+{# From an Asset #}
+<img src="{{ cdn_url(asset) }}" alt="My image">
+
+{# From an Image (with transformations) #}
+{% set image = asset|storyblok_image(800, 600) %}
+<img src="{{ cdn_url(image) }}" alt="Resized image">
+
+{# Combine filter and function #}
+<img src="{{ cdn_url(asset|storyblok_image(400, 300)) }}" alt="Thumbnail">
+```
+
+The `cdn_url` function accepts an optional second argument to specify the URL reference type. See Symfony's [UrlGeneratorInterface](https://symfony.com/doc/current/routing.html#generating-urls) for available options (`ABSOLUTE_URL`, `ABSOLUTE_PATH`, `RELATIVE_PATH`, `NETWORK_PATH`).
+
+#### Supported Formats
+
+The CDN supports all file formats served by Storyblok, including images (JPG, PNG, WebP, GIF, SVG, AVIF), documents (PDF), and other assets.
+
+**Example URLs:**
+
+| Asset Type | Storyblok URL | CDN URL |
+|------------|---------------|---------|
+| Original image | `https://a.storyblok.com/f/12345/1920x1080/abc123/photo.jpg` | `https://example.com/f/a1b2c3d4e5f6g7h8/1920x1080-photo.jpg` |
+| Resized image | `https://a.storyblok.com/f/12345/1920x1080/abc123/photo.jpg/m/800x600` | `https://example.com/f/b2c3d4e5f6g7h8i9/800x600-photo.jpg` |
+| PDF document | `https://a.storyblok.com/f/12345/document.pdf` | `https://example.com/f/c3d4e5f6g7h8i9j0/document.pdf` |
+
+> [!WARNING]
+> Private assets are not supported yet. Only public Storyblok assets can be served through the CDN.
+
+### Cleanup Command
+
+The bundle provides a console command to clean up cached CDN files:
+
+```bash
+# Delete all cached files
+php bin/console storyblok:cdn:cleanup
+
+# Preview what would be deleted (dry-run)
+php bin/console storyblok:cdn:cleanup --dry-run
+
+# Delete only expired files
+php bin/console storyblok:cdn:cleanup --expired
+```
+
+> [!TIP]
+> Configure this command as a cronjob to automatically clean up expired files. For example, to run daily at midnight:
+> ```bash
+> 0 0 * * * php bin/console storyblok:cdn:cleanup --expired
+> ```
+
+### How It Works
+
+The CDN feature uses a lazy-loading approach for optimal performance:
+
+1. **During Twig rendering**: When `cdn_url()` is called, only metadata (the original Storyblok URL) is stored locally. No download occurs at this point, keeping page rendering fast.
+
+2. **On first browser request**: When a browser requests the CDN URL, the controller downloads the file from Storyblok, stores it locally with enriched metadata (content type, etag, expiration), and serves it.
+
+3. **On subsequent requests**: The file is served directly from local storage with appropriate caching headers.
+
+This approach ensures that page rendering is not blocked by asset downloads, even when dealing with many images.
+
+### Custom Storage Implementation
+
+By default, assets are stored on the filesystem. You can implement your own storage by creating a class that implements `CdnStorageInterface`:
+
+```php
+use Storyblok\Bundle\Cdn\Storage\CdnStorageInterface;
+use Symfony\Component\DependencyInjection\Attribute\AsAlias;
+
+#[AsAlias(CdnStorageInterface::class)]
+final class RedisCdnStorage implements CdnStorageInterface
+{
+    // Implement the interface methods
+}
+```
+
+Then configure the bundle to use custom storage:
+
+```yaml
+# config/packages/storyblok.yaml
+storyblok:
+    cdn:
+        storage:
+            type: custom  # This removes the built-in filesystem storage
+```
+
+> [!NOTE]
+> When using `type: custom`, the `path` option should not be set. The built-in cleanup command is also removed since it's specific to filesystem storage.
+
 ### Image Transformation
 
 The bundle provides a `storyblok_image` Twig filter to convert Storyblok Assets to Image objects with optional resizing. This filter integrates with the [storyblok/php-image-service](https://github.com/storyblok/php-image-service) library and returns an immutable `Image` instance that you can further transform using the fluent API.

composer.json

@@ -17,7 +17,10 @@
     "storyblok/php-image-service": ">=0.5.0",
     "storyblok/php-tiptap-extension": "^1.0",
     "symfony/config": "^6.0 || ^7.0 || ^8.0",
+    "symfony/console": "^6.0 || ^7.0 || ^8.0",
     "symfony/dependency-injection": "^6.0 || ^7.0 || ^8.0",
+    "symfony/filesystem": "^6.0 || ^7.0 || ^8.0",
+    "symfony/finder": "^6.0 || ^7.0 || ^8.0",
     "symfony/framework-bundle": "^6.0 || ^7.0 || ^8.0",
     "symfony/http-client": "^6.0 || ^7.0 || ^8.0",
     "symfony/http-kernel": "^6.0 || ^7.0 || ^8.0",

config/routes.php

@@ -7,4 +7,5 @@
 return function (RoutingConfigurator $routes): void {
     $routes->import('@StoryblokBundle/config/routes/webhook.php');
     $routes->import('@StoryblokBundle/config/routes/content_type.php');
+    $routes->import('@StoryblokBundle/config/routes/cdn.php');
 };

config/routes/cdn.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Symfony\Component\Routing\Loader\Configurator;
+
+use Storyblok\Bundle\Controller\CdnController;
+use Storyblok\Bundle\Routing\Route;
+use Symfony\Component\HttpFoundation\Request;
+
+return function (RoutingConfigurator $routes): void {
+    $routes->add(Route::CDN, '/f/{id}/{filename}.{extension}')
+        ->controller(CdnController::class)
+        ->methods([Request::METHOD_GET, Request::METHOD_HEAD])
+        ->requirements([
+            'id' => '[a-f0-9]{16}',
+            'extension' => 'jpe?g|png|gif|webp|svg|avif|pdf|mp4',
+        ])
+        ->options([
+            'priority' => 1,
+        ]);
+};

config/services.php

@@ -19,6 +19,15 @@
 use Storyblok\Bundle\Block\BlockRegistry;
 use Storyblok\Bundle\Block\Renderer\BlockRenderer;
 use Storyblok\Bundle\Block\Renderer\RendererInterface;
+use Storyblok\Bundle\Cdn\CdnUrlGenerator;
+use Storyblok\Bundle\Cdn\CdnUrlGeneratorInterface;
+use Storyblok\Bundle\Command\CdnCleanupCommand;
+use Storyblok\Bundle\Cdn\Download\AssetDownloader;
+use Storyblok\Bundle\Cdn\Download\FileDownloaderInterface;
+use Storyblok\Bundle\Cdn\Storage\CdnFilesystemStorage;
+use Storyblok\Bundle\Cdn\Storage\CdnStorageInterface;
+use Storyblok\Bundle\Cdn\Storage\TraceableCdnStorage;
+use Storyblok\Bundle\DataCollector\CdnCollector;
 use Storyblok\Bundle\ContentType\ContentTypeControllerRegistry;
 use Storyblok\Bundle\ContentType\ContentTypeRegistry;
 use Storyblok\Bundle\ContentType\ContentTypeRegistryInterface;
@@ -27,12 +36,14 @@
 use Storyblok\Bundle\ContentType\Listener\GlobalCachingListener;
 use Storyblok\Bundle\ContentType\Listener\ResolveControllerListener;
 use Storyblok\Bundle\ContentType\Listener\StoryNotFoundExceptionListener;
+use Storyblok\Bundle\Controller\CdnController;
 use Storyblok\Bundle\Controller\WebhookController;
 use Storyblok\Bundle\DataCollector\StoryblokCollector;
 use Storyblok\Bundle\Listener\UpdateProfilerListener;
 use Storyblok\Bundle\Tiptap\DefaultEditorBuilder;
 use Storyblok\Bundle\Tiptap\EditorBuilderInterface;
 use Storyblok\Bundle\Twig\BlockExtension;
+use Storyblok\Bundle\Twig\CdnExtension;
 use Storyblok\Bundle\Twig\ImageExtension;
 use Storyblok\Bundle\Twig\LiveEditorExtension;
 use Storyblok\Bundle\Twig\RichTextExtension;
@@ -110,6 +121,19 @@
                 'priority' => 255,
             ])
 
+        ->set(TraceableCdnStorage::class)
+            ->args([
+                '$decorated' => service(CdnFilesystemStorage::class),
+            ])
+
+        ->set(CdnCollector::class)
+            ->args([
+                '$storage' => service(TraceableCdnStorage::class),
+            ])
+            ->tag('data_collector', [
+                'priority' => 254,
+            ])
+
         ->set(UpdateProfilerListener::class)
             ->tag('kernel.event_listener', [
                 'event' => KernelEvents::RESPONSE,
@@ -181,5 +205,36 @@
 
         ->set(ImageExtension::class)
             ->tag('twig.extension')
+
+        ->set(CdnController::class)
+            ->args([
+                '$storage' => service(CdnStorageInterface::class),
+                '$downloader' => service(FileDownloaderInterface::class),
+                '$public' => abstract_arg('public cache directive'),
+                '$maxAge' => abstract_arg('max-age cache directive'),
+                '$smaxAge' => abstract_arg('smaxage cache directive'),
+            ])
+            ->tag('controller.service_arguments')
+
+        ->set(AssetDownloader::class)
+            ->alias(FileDownloaderInterface::class, AssetDownloader::class)
+
+        ->set(CdnFilesystemStorage::class)
+            ->args([
+                '$storagePath' => abstract_arg('CDN storage path'),
+            ])
+            ->alias(CdnStorageInterface::class, CdnFilesystemStorage::class)
+
+        ->set(CdnUrlGenerator::class)
+            ->alias(CdnUrlGeneratorInterface::class, CdnUrlGenerator::class)
+
+        ->set(CdnExtension::class)
+            ->tag('twig.extension')
+
+        ->set(CdnCleanupCommand::class)
+            ->args([
+                '$storagePath' => abstract_arg('CDN storage path'),
+            ])
+            ->tag('console.command')
     ;
 };

src/Cdn/CdnUrlGenerator.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of storyblok/symfony-bundle.
+ *
+ * (c) Storyblok GmbH <info@storyblok.com>
+ * in cooperation with SensioLabs Deutschland <info@sensiolabs.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Bundle\Cdn;
+
+use Storyblok\Api\Domain\Type\Asset;
+use Storyblok\Bundle\Cdn\Domain\AssetInfo;
+use Storyblok\Bundle\Cdn\Domain\CdnFileMetadata;
+use Storyblok\Bundle\Cdn\Storage\CdnStorageInterface;
+use Storyblok\Bundle\Routing\Route;
+use Storyblok\ImageService\Image;
+use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
+
+/**
+ * @author Silas Joisten <silasjoisten@proton.me>
+ * @author Stiven Llupa <stiven.llupa@gmail.com>
+ */
+final readonly class CdnUrlGenerator implements CdnUrlGeneratorInterface
+{
+    public function __construct(
+        private CdnStorageInterface $storage,
+        private UrlGeneratorInterface $urlGenerator,
+    ) {
+    }
+
+    public function generate(Asset|Image $asset, int $referenceType = UrlGeneratorInterface::ABSOLUTE_URL): string
+    {
+        $assetInfo = new AssetInfo($asset);
+
+        if (!$this->storage->hasMetadata($assetInfo->id, $assetInfo->fullFilename)) {
+            $this->storage->setMetadata($assetInfo->id, $assetInfo->fullFilename, new CdnFileMetadata(originalUrl: $assetInfo->url));
+        }
+
+        return $this->urlGenerator->generate(Route::CDN, [
+            'id' => $assetInfo->id->value,
+            'filename' => $assetInfo->filename,
+            'extension' => $assetInfo->extension,
+        ], $referenceType);
+    }
+}

src/Cdn/CdnUrlGeneratorInterface.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of storyblok/symfony-bundle.
+ *
+ * (c) Storyblok GmbH <info@storyblok.com>
+ * in cooperation with SensioLabs Deutschland <info@sensiolabs.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Bundle\Cdn;
+
+use Storyblok\Api\Domain\Type\Asset;
+use Storyblok\ImageService\Image;
+use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
+
+/**
+ * @author Silas Joisten <silasjoisten@proton.me>
+ * @author Stiven Llupa <stiven.llupa@gmail.com>
+ */
+interface CdnUrlGeneratorInterface
+{
+    /**
+     * @param UrlGeneratorInterface::* $referenceType
+     */
+    public function generate(Asset|Image $asset, int $referenceType = UrlGeneratorInterface::ABSOLUTE_URL): string;
+}