README

废弃

这个库实际上已经废弃，我为了一个新的客户端在netglue/prismic-client上进行了重构。

它与原来的库有一些相似之处，但主要是重新编写，利用了http相关的PSRs，并试图简化事务，进一步提高类型安全性。

如果你正在开始一个新的项目，希望使用一个能够长期使用的客户端，并且不想使用过时的官方客户端，那么请选择那个……

如果你已经在使用这个库，就像我在一些旧项目中一样，那么如果你需要，请随时贡献补丁。

介绍

这个官方Prismic.io库的分支与官方版本在几个方面有所不同，与目前处于beta测试阶段的4.x版本相比，更类似于原始套件的3.x版本。

安装

Composer是唯一的“支持”安装方法

$ composer require netglue/prismic-php-kit

用法

你需要在Prismic.io上设置好并准备好内容存储库，如果你对prismic.io还一无所知，可以查看网站和关于内容建模的文档，并注册账户。

Prismic内容存储库会暴露一个URL，以便将API查询直接指向该URL，形式为https://<REPO-NAME>.prismic.io/api。根据你的设置，你的存储库可能需要或不需要访问令牌。目前内容API有2个版本，分别在不同的URL上提供。API的V1版本可在/api或/api/v1处访问，而V2版本的API则可在/api/v2处访问。此套件试图透明地支持这两个版本的API。V1 API看起来与V2 API相同，除了V1 API的响应更详细。没有关于v1 API废弃的日期，我也不清楚这两个版本之间有任何功能上的差异。

一旦你有了存储库的详细信息，你可以按照以下方式创建API客户端（假设你已经设置了composer自动加载）

use Prismic\Api;
$accessToken = 'AccessTokenString Or null';
$api = Api::get('https://<REPO-NAME>.prismic.io/api/v1', $accessToken); 

API结果

在大多数情况下，你可能会从API检索单个文档或结果集，例如，使用API客户端通过其标识符检索单个文档，如下所示：$api->getById('SomeIdentifier');，而获取特定类型所有文档的查询可能看起来像……

<?php
use Prismic\Predicates;
$query = [
    Predicates::at('document.type', 'blog-post'),
];
$response = $api->query($query);

对于单个文档，您将获得一个 \Prismic\DocumentInterface 实例。结果集将是一个 \Prismic\Response 实例。调用 $response->getResults() 将返回一个文档实例数组。

解析应用程序链接

在大多数情况下，在将内容作为HTML渲染之前，您需要向API客户端提供一个'链接解析器'，以便它知道如何生成内容的URL。您的链接解析器需要实现 \Prismic\LinkResolver 接口。在 \Prismic\LinkResolverAbstract 中有一个抽象类可以继承，这样您只需要实现一个方法，您可以在 ./samples/LinkResolverExample.php 中找到一个具体的链接解析器示例。一旦您有一个链接解析器实例，通过以下方式将其提供给API：

<?php
/** @var \Prismic\LinkResolver $linkResolver **/
$linkResolver = $myDiContainer->get('My-Link-Resolver');
$api->setLinkResolver($linkResolver);

渲染内容

一般来说，一旦您弄清楚如何查询API获取一些数据，您可能希望将其作为HTML或纯文本渲染。调用 $document->asHtml() 将给您一个HTML块，但它可能不会按照您期望的方式结构化，因此您将使用某种模板库。

从API检索到的每个文档都将包含您在Prismic中定义的片段，这些片段将包含在 \Prismic\Document\Fragment\FragmentCollection 中，在该集合中可能包含任意数量的单个或复合 \Prismic\Document\Fragment\FragmentInterface 实例。因为（如果存在的话，除了UID）CMS不需要任何内容字段，您通常在尝试渲染任何内容之前希望在模板中检查非null值。

<?php
/** @var \Prismic\Document\Fragment\RichText|null $titleFragment **/
$titleFragment = $document->get('title');
if ($titleFragment) {
    printf('<div class="page-title-block">%s</div>', $titleFragment->asHtml());
}

将结果填充到具体对象中

默认情况下，该套件将为从API检索到的每个文档创建一个 \Prismic\Document 实例。您可以通过将Prismic文档类型映射到FQCN来更改此行为，例如

<?php
$hydrator = $api->getHydrator();
$hydrator->mapType('blog-post', \My\BlogPostDocument::class);
$response = $api->query([Predicates::at('document.type', 'blog-post')]);
/** @var \My\BlogPostDocument[] $posts */
$posts = $response->getResults();

您定义的任何表示文档的类都必须实现 \Primic\DocumentInterface，但通常，您只需扩展 \Prismic\Document

缓存

在这个分支中，缓存的不同之处在于它消费了任何 \Psr\Cache 实现，这样您就可以为任何适配器从任何Psr兼容的库中进行交换。默认情况下，如果安装了APC，使用Symfony实现和APC适配器；否则，使用内存中的数组缓存。

您需要将自定义缓存提供给Api实例的命名构造函数

<?php
/** @var \Psr\Cache\CacheItemPoolInterface $cache **/
$cache = $myDIContainer->get('SomeRedisCache');
$httpClient = null;
$api = Api::get($repoApiUrl, $accessToken, $httpClient, $cache);

Webhooks

当单个文档或发布发布时，将向您的应用程序/网站发送Webhooks。只是让您知道，以下是一些可能会发布Webhook的其他条件。

此处的文档说，当标签添加、更改和删除时，会触发webhook。这并不准确。在撰写本文时，您无法编辑或删除标签。作为与文档协作的一部分创建的任何新标签都将在下一个有效负载中发布，但前提是有其他触发webhook的事件。

确定版本或文档是否已发布的唯一方法是检查webhook有效负载主体中是否存在masterRef属性。

内置文档探索器

如果您有一个现有的仓库要启动，可以使用一个简单的文档探索器

$ export PRISMIC_API="https://somerepo.prismic.io/api"
$ export PRISMIC_TOKEN="Some-Access-Token"
$ composer serve
> php -S 0.0.0.0:8080 -t samples samples/document-explorer.php

在浏览器中访问http://localhost:8080，您应该会看到仓库中的内容。

测试

测试是用PHPUnit编写的。要本地运行测试

$ composer install
$ vendor/bin/phpunit # or composer check

贡献

……我们非常欢迎拉取请求，但请在适当的情况下运行composer check以确保代码风格得到维护，并包括额外的单元测试。

许可

本软件根据以下Apache 2许可证进行许可。

版权所有2018 Prismic.io (https://prismic.io)。

根据Apache许可证2.0版（“许可证”）进行许可；除非适用法律要求或书面同意，否则不得使用本项目，除非符合许可证规定。您可以在https://apache.ac.cn/licenses/LICENSE-2.0获取许可证副本。

除非适用法律要求或书面同意，否则在许可证下分发的软件按“原样”基础分发，不提供任何明示或暗示的保证或条件。有关许可证的具体语言、权限和限制，请参阅许可证。