README

一个用于将 Storyblok 头部 CMS 集成到您的 Symfony 应用的 Symfony 扩展包。

此扩展包利用 sensiolabs-de/storyblok-api，一个为 Storyblok 提供类型安全的 PHP SDK。它配置 Storyblok 客户端并提供一个用于简化调试和监控 Storyblok API 交互的 Symfony Profiler 扩展。

安装

要安装此扩展包，请运行

composer require sensiolabs-de/storyblok-api sensiolabs-de/storyblok-bundle

配置

Symfony Flex

如果您使用 symfony/flex，扩展包将自动启用，配置文件将添加到您的项目中。

手动配置

如果 symfony/flex 不可用或您希望手动设置，请按照以下步骤操作

1. 添加配置 将以下配置添加到您的 config/packages/storyblok.yaml

   storyblok:
     base_uri: '%env(STORYBLOK_API_BASE_URI)%'
     token: '%env(STORYBLOK_API_TOKEN)%'

   如果您想使用 AssetsApi，也可以添加以下配置

   storyblok:
     # ...
     assets_token: '%env(STORYBLOK_ASSETS_API_TOKEN)%'

2. 设置环境变量 在您的 .env 文件中定义必要的环境变量

   STORYBLOK_API_BASE_URI=https://api.storyblok.com/v1
   STORYBLOK_API_TOKEN=your_storyblok_api_token

使用方法

API 使用

设置好扩展包后，您可以在您的 Symfony 应用程序中使用 Storyblok 客户端与 Storyblok CMS API 交互。

有关详细使用方法和示例，请参阅 Storyblok API SDK 文档。

Webhooks

Storyblok Webhooks 允许您的 Symfony 应用程序对内容更改等事件做出反应。此扩展包提供处理这些 Webhooks 的简单设置。

配置

要启用 Webhooks，将以下路由添加到您的应用程序

# config/routes/storyblok.yaml
storyblok:
    resource: '@StoryblokBundle/config/routes.php'

这将使 /storyblok/webhook 路由可用，以接收 Webhook 请求。有关 Webhooks 的工作原理的更多详细信息，请参阅 Storyblok Webhooks 文档。

验证 Webhook 签名（安全性）

为了安全性，您可以启用 Webhook 签名的验证，以确保请求来自 Storyblok。这是通过配置一个 webhook_secret 来实现的

# config/packages/storyblok.yaml
storyblok:
    # ...
    webhook_secret: '%env(STORYBLOK_WEBHOOK_SECRET)%'

您需要在您的 .env 文件中设置此密钥

STORYBLOK_WEBHOOK_SECRET=your_webhook_secret

启用后，扩展包将自动将每个 Webhook 请求与该密钥进行验证。

处理 Webhook 事件

要处理 Webhooks，实现 WebhookHandlerInterface。扩展包自动将实现此接口的任何类注册为 Webhook 处理程序，无需额外的服务配置。

示例 Webhook 处理程序

以下是一个示例 Webhook 处理程序，它会在发生某些事件（例如内容发布或删除）时清除 Varnish 缓存

<?php

namespace App\Webhook;

use SensioLabs\Storyblok\Bundle\Webhook\Event;
use SensioLabs\Storyblok\Bundle\Webhook\Handler\WebhookHandlerInterface;

final class PurgeVarnishHandler implements WebhookHandlerInterface
{
    public function handle(Event $event, array $payload): void
    {
        // Your custom logic for handling the event
        // Example: purging Varnish cache
    }

    public function supports(Event $event): bool
    {
        // Specify the events your handler supports
        return $event->equalsOneOf([
            Event::StoryPublished,
            Event::StoryUnpublished,
            Event::StoryDeleted,
            Event::StoryMoved,
        ]);
    }

    public static function priority(): int
    {
        // Define the priority for your handler
        return -2000;
    }
}

最佳实践

• 仅处理必要的事件：使用 supports 方法过滤处理程序应处理的 Webhook 事件。
• 优先处理程序：如果您有多个处理程序，请适当地设置优先级。优先级更高的处理程序（整数值更低）将首先执行。
• 添加日志记录：记录传入的 Webhooks 和执行的操作是个好主意，特别是用于调试和监控。

这种方案提供了一种简化和安全的方式来处理来自Storyblok的Webhooks，允许您的Symfony应用程序有效地响应变化。有关更多细节和用例，您可以随时参考Storyblok API SDK文档。