Introduce #[AsBlock] attribute (#16)

Author: silasjoisten

README.md

@@ -181,6 +181,67 @@ This will replace `StoriesApi` to `StoriesResolvedApi`. The `StoriesResolvedApi`
 > [Storyblok docs](https://www.storyblok.com/docs/api/content-delivery/v2/stories/retrieve-a-single-story)
 > for more information
 
+## Block Registration with `#[AsBlock]`
+
+You can register Storyblok blocks using the `#[AsBlock]` attribute.
+
+The `name` and `template` parameters are optional, you will find their defaults in the following section.
+
+### Usage
+
+To define a block, use the attribute on a class:
+
+```php
+use Storyblok\Bundle\Block\Attribute\AsBlock;
+use Webmozart\Assert\Assert;
+
+#[AsBlock(name: 'sample', template: 'custom_blocks/sample.html.twig')]
+final readonly class SampleBlock
+{
+    public string $title;
+    public string $description;
+
+    public function __construct(array $values)
+    {
+        Assert::keyExists($values, 'title');
+        $this->title = $values['title'];
+
+        Assert::keyExists($values, 'description');
+        $this->description = $values['description'];
+    }
+}
+```
+
+### Attribute Parameters
+
+| Parameter  | Type    | Required? | Description |
+|------------|--------|-----------|-------------|
+| `name`     | `string` | No | The block name used in Storyblok. Defaults to the class name converted to snake_case. |
+| `template` | `string` | No | The Twig template for rendering the block. Defaults to `blocks/{name}.html.twig`. |
+
+### Customizing the Default Template Path
+
+You can change the default template path structure by configuring it in `storyblok.yaml`:
+
+```yaml
+# config/packages/storyblok.yaml
+storyblok:
+    blocks_template_path: 'my/custom/path'
+```
+
+### Rendering Blocks in Twig
+
+A new `render_block` Twig filter allows easy rendering of Storyblok blocks:
+
+```twig
+{% for block in page.body %}
+    {% if block is not null %}
+        {{ block|render_block }}
+    {% endif %}
+{% endfor %}
+```
+
+This ensures dynamic rendering of Storyblok components with minimal effort.
 
 #### Best Practices
 

composer.json

@@ -20,7 +20,9 @@
     "symfony/http-client": "^6.0 || ^7.0",
     "symfony/http-kernel": "^6.0 || ^7.0",
     "symfony/monolog-bundle": "^3.10",
+    "symfony/string": "^6.0 || ^7.0",
     "thecodingmachine/safe": "^2.0 || ^3.0",
+    "twig/twig": "^3.20",
     "webmozart/assert": "^1.11"
   },
   "require-dev": {

config/services.php

@@ -5,6 +5,9 @@
 namespace Symfony\Component\DependencyInjection\Loader\Configurator;
 
 use Storyblok\Api\StoryblokClientInterface;
+use Storyblok\Bundle\Block\BlockRegistry;
+use Storyblok\Bundle\Block\Renderer\BlockRenderer;
+use Storyblok\Bundle\Block\Renderer\RendererInterface;
 use Storyblok\Bundle\Controller\WebhookController;
 use Storyblok\Bundle\DataCollector\StoryblokCollector;
 use Storyblok\Bundle\Listener\UpdateProfilerListener;
@@ -17,6 +20,7 @@
 use Storyblok\Api\StoryblokClient;
 use Storyblok\Api\TagsApi;
 use Storyblok\Api\TagsApiInterface;
+use Storyblok\Bundle\Twig\BlockExtension;
 use Storyblok\Bundle\Webhook\WebhookEventHandlerChain;
 use Symfony\Component\HttpClient\HttpClient;
 use Symfony\Component\HttpClient\ScopingHttpClient;
@@ -92,5 +96,13 @@
                 'method' => 'onKernelResponse',
                 'priority' => -255,
             ])
+
+        ->set(BlockRenderer::class)
+        ->alias(RendererInterface::class, BlockRenderer::class)
+
+        ->set(BlockRegistry::class)
+
+        ->set(BlockExtension::class)
+        ->tag('twig.extension')
     ;
 };

phpstan-baseline.neon

@@ -1,31 +1,55 @@
 parameters:
 	ignoreErrors:
 		-
-			message: "#^Method Storyblok\\\\Bundle\\\\DataCollector\\\\StoryblokCollector\\:\\:collectOnClient\\(\\) return type has no value type specified in iterable type array\\.$#"
+			message: '#^Call to static method Webmozart\\Assert\\Assert\:\:stringNotEmpty\(\) with class\-string will always evaluate to true\.$#'
+			identifier: staticMethod.alreadyNarrowedType
+			count: 1
+			path: src/Block/BlockDefinition.php
+
+		-
+			message: '#^Method Storyblok\\Bundle\\DataCollector\\StoryblokCollector\:\:collectOnClient\(\) return type has no value type specified in iterable type array\.$#'
+			identifier: missingType.iterableValue
 			count: 1
 			path: src/DataCollector/StoryblokCollector.php
 
 		-
-			message: "#^Call to an undefined method Symfony\\\\Component\\\\Config\\\\Definition\\\\Builder\\\\NodeDefinition\\:\\:children\\(\\)\\.$#"
+			message: '#^Call to an undefined method Symfony\\Component\\Config\\Definition\\Builder\\NodeDefinition\:\:children\(\)\.$#'
+			identifier: method.notFound
 			count: 1
 			path: src/DependencyInjection/Configuration.php
 
 		-
-			message: "#^Method Storyblok\\\\Bundle\\\\Tests\\\\Unit\\\\Listener\\\\UpdateProfilerListenerTest\\:\\:createKernel\\(\\) has parameter \\$options with no value type specified in iterable type array\\.$#"
+			message: '#^Parameter \#2 \$configurator of method Symfony\\Component\\DependencyInjection\\ContainerBuilder\:\:registerAttributeForAutoconfiguration\(\) expects callable\(Symfony\\Component\\DependencyInjection\\ChildDefinition, Storyblok\\Bundle\\Block\\Attribute\\AsBlock, Reflector\)\: void, Closure\(Symfony\\Component\\DependencyInjection\\ChildDefinition, Storyblok\\Bundle\\Block\\Attribute\\AsBlock, ReflectionClass\)\: void given\.$#'
+			identifier: argument.type
+			count: 1
+			path: src/DependencyInjection/StoryblokExtension.php
+
+		-
+			message: '#^Parameter \#2 \$className of class Storyblok\\Bundle\\Block\\BlockDefinition constructor expects class\-string, string given\.$#'
+			identifier: argument.type
+			count: 2
+			path: tests/Unit/Block/BlockDefinitionTest.php
+
+		-
+			message: '#^Method Storyblok\\Bundle\\Tests\\Unit\\Listener\\UpdateProfilerListenerTest\:\:createKernel\(\) has parameter \$options with no value type specified in iterable type array\.$#'
+			identifier: missingType.iterableValue
 			count: 1
 			path: tests/Unit/Listener/UpdateProfilerListenerTest.php
 
 		-
-			message: "#^Method Storyblok\\\\Bundle\\\\Tests\\\\Util\\\\TestKernel\\:\\:create\\(\\) has parameter \\$options with no value type specified in iterable type array\\.$#"
+			message: '#^Method Storyblok\\Bundle\\Tests\\Util\\TestKernel\:\:create\(\) has parameter \$options with no value type specified in iterable type array\.$#'
+			identifier: missingType.iterableValue
 			count: 1
 			path: tests/Util/TestKernel.php
 
 		-
-			message: "#^Method Storyblok\\\\Bundle\\\\Tests\\\\Util\\\\TestKernel\\:\\:debug\\(\\) has parameter \\$options with no value type specified in iterable type array\\.$#"
+			message: '#^Method Storyblok\\Bundle\\Tests\\Util\\TestKernel\:\:debug\(\) has parameter \$options with no value type specified in iterable type array\.$#'
+			identifier: missingType.iterableValue
 			count: 1
 			path: tests/Util/TestKernel.php
 
 		-
-			message: "#^Method Storyblok\\\\Bundle\\\\Tests\\\\Util\\\\TestKernel\\:\\:environment\\(\\) has parameter \\$options with no value type specified in iterable type array\\.$#"
+			message: '#^Method Storyblok\\Bundle\\Tests\\Util\\TestKernel\:\:environment\(\) has parameter \$options with no value type specified in iterable type array\.$#'
+			identifier: missingType.iterableValue
 			count: 1
 			path: tests/Util/TestKernel.php

src/Block/Attribute/AsBlock.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of sensiolabs-de/storyblok-bundle.
+ *
+ * (c) SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Bundle\Block\Attribute;
+
+#[\Attribute(\Attribute::TARGET_CLASS)]
+final readonly class AsBlock
+{
+    public function __construct(
+        public ?string $name = null,
+        public ?string $template = null,
+    ) {
+    }
+}

src/Block/BlockDefinition.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of sensiolabs-de/storyblok-bundle.
+ *
+ * (c) SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Bundle\Block;
+
+use Webmozart\Assert\Assert;
+
+final readonly class BlockDefinition
+{
+    /**
+     * @param class-string $className
+     */
+    public function __construct(
+        public string $name,
+        public string $className,
+        public string $template,
+    ) {
+        Assert::stringNotEmpty($name);
+        Assert::notWhitespaceOnly($name);
+
+        Assert::stringNotEmpty($className);
+        Assert::notWhitespaceOnly($className);
+        Assert::classExists($className);
+
+        Assert::stringNotEmpty($template);
+        Assert::notWhitespaceOnly($template);
+    }
+
+    /**
+     * @param array<string, mixed> $values
+     */
+    public static function fromArray(array $values): self
+    {
+        Assert::keyExists($values, 'className');
+        Assert::string($values['className']);
+        Assert::classExists($values['className']);
+
+        Assert::keyExists($values, 'name');
+        Assert::string($values['name']);
+
+        Assert::keyExists($values, 'template');
+        Assert::string($values['template']);
+
+        return new self(
+            name: $values['name'],
+            className: $values['className'],
+            template: $values['template'],
+        );
+    }
+}

src/Block/BlockRegistry.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of sensiolabs-de/storyblok-bundle.
+ *
+ * (c) SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Bundle\Block;
+
+use Storyblok\Bundle\Block\Exception\BlockNotFoundException;
+
+final class BlockRegistry implements \Countable
+{
+    /**
+     * @var array<class-string, BlockDefinition>
+     */
+    public static array $blocks = [];
+
+    public function __construct()
+    {
+        // Noop! Only used by the dependency injection. Static methods are used to interact with the registry.
+    }
+
+    /**
+     * @param array<string, mixed>|BlockDefinition $definition
+     */
+    public static function add(array|BlockDefinition $definition): void
+    {
+        if (\is_array($definition)) {
+            $definition = BlockDefinition::fromArray($definition);
+        }
+
+        self::$blocks[$definition->className] = $definition;
+    }
+
+    /**
+     * @param class-string $fqcn
+     */
+    public static function get(string $fqcn): BlockDefinition
+    {
+        if (!\array_key_exists($fqcn, self::$blocks)) {
+            throw new BlockNotFoundException(\sprintf('Block "%s" not found.', $fqcn));
+        }
+
+        return self::$blocks[$fqcn];
+    }
+
+    public static function byName(string $name): BlockDefinition
+    {
+        $definitions = \array_values(\array_filter(
+            self::$blocks,
+            static fn (BlockDefinition $definition) => $definition->name === $name,
+        ));
+
+        if (0 === \count($definitions)) {
+            throw new BlockNotFoundException(\sprintf('Block "%s" not found.', $name));
+        }
+
+        return $definitions[0];
+    }
+
+    public function count(): int
+    {
+        return \count(self::$blocks);
+    }
+}

src/Block/Exception/BlockNotFoundException.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of sensiolabs-de/storyblok-bundle.
+ *
+ * (c) SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Bundle\Block\Exception;
+
+final class BlockNotFoundException extends \RuntimeException
+{
+}

src/Block/Renderer/BlockRenderer.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of sensiolabs-de/storyblok-bundle.
+ *
+ * (c) SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Bundle\Block\Renderer;
+
+use Storyblok\Bundle\Block\BlockRegistry;
+use Storyblok\Bundle\Block\Exception\BlockNotFoundException;
+use Twig\Environment;
+use Webmozart\Assert\Assert;
+
+final readonly class BlockRenderer implements RendererInterface
+{
+    public function __construct(
+        private Environment $twig,
+        private BlockRegistry $blocks,
+    ) {
+    }
+
+    public function render(array|object $values): string
+    {
+        try {
+            if (\is_object($values)) {
+                $definition = $this->blocks::get($values::class);
+
+                $block = $values;
+            } else {
+                Assert::keyExists($values, 'component');
+                $name = $values['component'];
+                $definition = $this->blocks::byName($name);
+
+                $block = new ($definition->className)($values);
+            }
+
+            return $this->twig->render($definition->template, ['block' => $block]);
+        } catch (BlockNotFoundException) {
+            return '';
+        }
+    }
+}