README

简介

此模块/库的目的是简化使用 prismic.io 的内容 API 作为后端服务开发内容驱动网站。

如果您之前没有听说过 Prismic，您可以在 这里了解它。

要求

此模块仅适用于 Zend Expressive ^3.0 和 PHP ^7.1

此外，它使用官方 Prismic.io php 库的分支，您可以在 netglue/prismic-php-kit 中查看。此分支与官方套件相当不同，如果您已经熟悉官方库，我建议您查看文档/代码以了解差异。

安装

使用 composer 安装 composer require netglue/expressive-prismic

这将询问您是否要注入配置提供程序。

测试

$ composer install
$ vendor/bin/phpunit

基本配置

此库将 Prismic API 实例暴露在您的容器中，作为 Prismic\Api。至少，您需要配置您的凭据如下

    return [
        'prismic' => [
            'api' => [
                'token' => 'Permanent Access Token',
                'url' => 'https://Repo-name.prismic.io/api',
            ],
        ],
    ];

定义路由

为了允许您在路由过程中指定文档的属性，您必须将您想要使用的路由参数名称映射到 prismic 文档/api 等效项。默认值为

    'prismic' => [
        'route_params' => [
            'id'       => 'prismic-id',
            'bookmark' => 'prismic-bookmark',
            'uid'      => 'prismic-uid',
            'type'     => 'prismic-type',
            'lang'     => 'prismic-lang',
        ],
    ],

因此，假设以上内容，要定义一个指向书签文档的路由，您将配置如下

    /**
     * @var \Zend\Expressive\Application $app
     * @var \Zend\Stratigility\MiddlewarePipeInterface $middlewarePipe
     */
    $app->route('/', [$middlewarePipe], ['GET'], 'home')
        ->setOptions([
            'defaults' => [
                'template' => 'page::default',
                'prismic-bookmark' => 'home',
            ],
        ]);

通常，为了节省一些精力，您会有一个可以渲染任何给定类型的页面的模板，例如一个 'case-study' 类型的页面。假设您想要 /case-studies/{case-study-uid} 的 URL，那么您将定义一个如下的路由 (如果您使用 FastRoute)

    $app->route('/case-studies/{prismic-uid}', [$middlewarePipe], ['GET'], 'case-studies')
            ->setOptions([
                'defaults' => [
                    'template' => 'my:case-study',
                    'prismic-type' => 'case-study',
                ],
            ]);

缓存破坏 Webhook

您将在 Factory\PipelineAndRoutesDelegator 中看到默认连接了两个路由，其中一个是用于破坏缓存的 webhook。为了使用它，您 应该 提供一个共享密钥，Prismic.io 将将其发送到 webhook 负载中，并将其存储在本地配置文件或 Config Provider 中，如下所示

    return [
        'prismic' => [
            'webhook_secret' => 'SomeSuperToughSharedSecret',
        ],
    ];

您还需要将此密钥输入到您的 Prismic 仓库设置中的相关位置。

默认情况下，密钥为 null，这意味着即使密钥由 Prismic 发送，也不会进行验证。如果您决定不设置密钥，我 强烈 建议您配置一个难以猜测的 URL，否则任何人都可以向您的 webhook 端点 POST，并按需破坏缓存，这会减慢您的网站。

默认情况下，webhook的URL为/prismicio-cache-webhook。您应按照以下方式将其更改为足够随机的值。

    return [
        'prismic' => [
            'webhook_url' => '/send-prismic-webhooks-here',
        ],
    ];

如果使用POST请求访问webhook URL并带有有效的JSON有效负载，则预配置的中介件将清空Prismic API实例附加的缓存。

webhook路由指向名为ExpressivePrismic\Middleware\WebhookPipe的中介管道，因此如果您想修改管道以执行其他操作或完全替换它，只需将该管道别名到不同的工厂或为该管道实现一个代理工厂。

链接解析器

链接解析器是Prismic引入的一个概念，用于将文档或文档链接片段转换为本地URL，此包中有一个具体的实现，位于ExpressivePrismic\LinkResolver。

使用相同的路由参数设置，它尝试使用Expressive URL助手生成本地URL。它在容器中设置为Prismic\LinkResolver以及ExpressivePrismic\LinkResolver，在整个包中通过名称Prismic\LinkResolver检索，因此如果您需要，可以轻松地将其替换为您的具体实现。

预览

还有一个与缓存清除webhook类似的自动绑定的路由，用于启动预览。您只需要在Prismic存储库的设置中添加URL，在写作室中点击预览按钮将使网站进入预览模式。您可以在Factory\PipelineAndRoutesDelegator中看到此配置 - 默认URL为/prismic-preview，但您可以通过设置以下配置值来更改URL。

    return [
        'prismic' => [
            'preview_url' => '/some-other-endpoint',
        ],
    ];

在4.2.0版本中，负责启动预览会话的中介件被修改为捕获预览令牌过期时抛出的异常，并随后返回一个描述性错误的简单HTML响应。在此之前，在这种情况下会发生未捕获的异常。

视图助手

URL助手 $this->prismicUrl()

此视图助手将使用链接解析器生成本地URL。它的__invoke()方法接受以下内容：

• 字符串 - 被视为文档ID
• \Prismic\Document
• \Prismic\Document\Fragment\LinkInterface

片段助手 $this->fragment()

此视图助手在当前解析的文档上操作，并提供了一种轻松渲染简单片段到视图的方法。它不需要完全限定的片段名称，即documentType.fragmentName，而您只需传递'fragmentName'即可。

$this->fragment()->get('title');将返回片段对象。

$this->fragment()->asText('title');将返回片段的文本值。

$this->fragment()->asHtml('title');将返回片段的HTML值。

生产环境中的CMS管理错误页面

默认情况下已连接错误处理……如果您正在使用开发中的Whoops错误处理器，则需要禁用开发模式composer development-disable以体验自定义错误和404错误。

404错误

在发生404错误的情况下，默认情况下，Expressive将执行\Zend\Expressive\Handler\NotFoundHandler。此模块在\ExpressivePrismic\Middleware\NotFoundPipe中提供了一个管道，该管道初始化预览和实验，定位Prismic API中的书签错误文档，并将其渲染到模板中。

为了利用漂亮的CMS管理的404错误页面，首先您需要在您的配置中指定仓库中错误文档的书签名称以及用于渲染的模板名称，如下所示

    return [
        'prismic' => [
            'error_handler' => [
                'template_404'   => 'some::template-name',
                'bookmark_404'   => 'some-bookmark',
            ],
        ],
    ];

注意，在开发模式下，在路由匹配后出现的404错误（即无法找到Prismic文档）将导致一个DocumentNotFound异常，从而委托给Whoops错误处理器。

异常

在处理错误和异常时，显示漂亮的错误页面与404错误处理的方式大致相同。同样，您需要配置一个书签和用于渲染内容的模板名称。

    return [
        'prismic' => [
            'error_handler' => [
                'template_error'   => 'some::template-name',
                'bookmark_error'   => 'some-bookmark',
            ],
        ],
    ];

对于异常情况，后备选项（即当无法从API检索错误文档时）是一个简单的纯文本消息，表明发生了错误。此后备选项目前无法配置为比这更复杂的内容。