README

摘要

Kontent.ai Delivery PHP SDK 是一个用于从 Kontent.ai 获取内容的客户端库。最佳使用 SDK 的方式是将其作为 Packagist 软件包使用。该库目前仅支持 PHP 8 及以上版本。

示例网站

在此处查看运行 Laravel 并使用此 SDK 的示例网站： https://github.com/kontent-ai/sample-app-php

安装

最佳安装客户端的方式是通过名为 Composer 的依赖管理器

composer require kontent-ai/delivery-sdk-php

或调整你的 composer.json 文件

{
    "require": {
        "kontent-ai/delivery-sdk-php": "^6.0.0"
    }
}

自动加载

编写面向对象的程序需要为每个类定义创建一个 PHP 源文件。最大的烦恼之一是在每个脚本的开始处（每个类一个）编写一个需要包含的长期列表。

由于 SDK 使用 Composer 依赖管理器并指定自动加载信息，Composer 会生成一个 vendor/autoload.php 文件。您可以简单地包含此文件，然后开始使用这些库提供的命名空间，而无需任何额外工作。

require __DIR__ . '/vendor/autoload.php';

使用 DeliveryClient

DeliveryClient 类是 SDK 的主要类。使用此类，您可以检索 Kontent.ai 项目的内容。

要创建类的实例，您需要提供一个项目 ID。

use Kontent\Ai\Delivery\DeliveryClient;

// Initializes an instance of the DeliveryClient client
$client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3');

在 DeliveryClient 实例化期间，您还可以使用一些其他可选参数。

$previewApiKey – 设置 Delivery 预览 API 密钥。客户端将自动开始使用查询的预览端点。请参阅预览未发布内容。
$securedProductionApiKey – 设置生产 Delivery API 密钥（不要与 Delivery 预览 API 密钥结合使用）
$waitForLoadingNewContent – 使客户端实例在获取更新内容时等待，当对 webhook 调用进行操作时很有用。
$debugRequests – 将 HTTP 客户端切换到调试模式
$retryAttempts – 客户端将重试连接到 Kontent.ai API 的次数（每次请求失败时）

创建 DeliveryClient 后，您可以通过调用客户端实例上的方法开始查询您的项目存储库。请参阅基本查询获取详细信息。

基本查询

一旦您有了 DeliveryClient 实例，您就可以通过调用实例上的方法开始查询您的项目存储库。

// Retrieves a single content item
$item = $client->getItem('about_us');

// Retrieves a list of all content items
$items = $client->getItems();

过滤检索的数据

SDK 支持与 API 查询和过滤能力完全相同的范围，如 API 参考中所述。

use Kontent\Ai\Delivery\QueryParams;

// Retrieves a list of the specified elements from the first 10 content items of
// the 'brewer' content type, ordered by the 'product_name' element value
$response = $client->getItems((new QueryParams())
  ->equals('system.type', 'brewer')
  ->elements(array('image', 'price', 'product_status','processing'))
  ->limit(10)
  ->orderAsc('elements.product_name'));

获取本地化项

语言选择只是向查询指定一个额外的过滤参数的问题。

use Kontent\Ai\Delivery\QueryParams;

// Retrieves a list of the specified elements from the first 10 content items of
// the 'brewer' content type, ordered by the 'product_name' element value
$response = $client->getItems((new QueryParams())
  ->language('es-ES')
  ->equals('system.type', 'brewer')
  ->elements(array('image', 'price', 'product_status','processing'))
  ->limit(10)
  ->orderAsc('elements.product_name'));

处理分类

要获取有关您的分类信息，您可以使用getTaxonomy和getTaxonomies方法。此外，您还可以指定查询参数。

use Kontent\Ai\Delivery\QueryParams;

// Retrieves a list of the specified taxonomy groups.
$response = $client->getTaxonomies((new QueryParams())
  ->limit(3);

// Retrieves a specific taxonomy group.
$response = $client->getTaxonomy('persona');

预览未发布的内容

要获取未发布的内容，您需要创建一个带有项目ID和预览API密钥的DeliveryClient。每个Kontent.ai项目都有自己的预览API密钥。

// Note: Within a single project, we recommend that you work with only
// either the production or preview Delivery API, not both.
$client = new DeliveryClient('YOUR_PROJECT_ID', 'YOUR_PREVIEW_API_KEY');

有关详细信息，请参阅使用Delivery API预览未发布内容。

响应结构

有关单个和多个内容项JSON响应格式的完整描述，请参阅我们的API参考。

单个内容项响应

当检索单个内容项时，您将获得一个ContentItem类的实例。此类包含一个'system'属性（包含有关内容项的元数据，例如代码名称、显示名称、类型、集合或站点地图位置），以及相应内容项的元素作为骆驼峰命名法属性。

多个内容项响应

当检索内容项列表时，您将获得一个ContentItemsResponse类的实例。此类表示Delivery API端点的JSON响应，并包含

Pagination属性，其中包含以下信息
- Skip：要跳过的请求内容项数
- Limit：请求的页面大小
- Count：检索到的内容项总数
- NextPageUrl：下一页的URL
所需内容项的数组

属性及其类型

所有属性均使用骆驼峰命名法命名。
如果属性包含对象集合，则它被类型化为一个数组，该数组按
- 代码名称索引，如果包含的实体具有代码名称
- 数字，如果它们没有代码名称。我们使用基于零的索引。
如果属性引用链接项（属性是链接项类型），则将这些引用替换为相应的内容项。
如果属性是资产、多选选项或分类组类型，则将其解析为来自Kontent\Ai\Delivery\Models\Items命名空间的相应知名模型。
所有时间戳都类型化为\DateTime。
所有数字都类型化为float。

映射自定义模型

可以指示SDK填充并返回您自己的预定义模型。为此，您必须实现

TypeMapperInterface（必需）- 将Kontent.ai内容类型映射到您的模型
PropertyMapperInterface（可选）- 更改属性映射的默认行为（默认属性翻译方式如下：'content_type' -> 'contentType'）
ValueConverterInterface（可选）- 更改内容元素类型映射到PHP类型的方式
ContentLinkUrlResolverInterface（可选）- 更改解析富文本元素中链接的方式，请参阅解析到内容项的链接。
InlineLinkedItemsResolverInterface（可选）- 更改解析富文本元素中的内容项的方式，请参阅解析富文本中的内容项和组件。

所有接口的默认实现可以在名为 DefaultMapper 的类中找到。

示例

class TetsMapper extends DefaultMapper
{
    public function getTypeClass($typeName)
    {
        switch ($typeName) {
            case 'home':
                return \Kontent\Ai\Tests\E2E\HomeModel::class;
            case 'article':
                return \Kontent\Ai\Tests\E2E\ArticleModel::class;
        }

        return parent::getTypeClass($typeName);
    }
}
...

public function testMethod()
{
    $client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3');
    $client->typeMapper = new TetsMapper();
    $item = $client->getItem('on_roasts');
    $this->assertInstanceOf(\Kontent\Ai\Tests\E2E\ArticleModel::class, $item); // Passes
}

然后 ArticleModel 可以看起来像这样（并且仅包含您需要工作的属性）

class ArticleModel
{
    public $system = null;
    public $title = null;
    public $urlPattern = null;
}

反馈 & 贡献

查看贡献页面，了解最佳的问题报告位置、开始讨论和开始贡献。

克隆仓库
运行 composer install 安装依赖
运行 phpunit 以验证一切是否按预期工作

在 Windows 上开发

查看我们关于在 Windows 上使用 Visual Studio Code 开发 PHP 的教程！

在 Linux 上开发

您更喜欢企鹅吗？查看我们在 Linux 上使用 PhpStorm 开发 PHP 的教程！

名人墙

我们想感谢以下为项目的成功做出贡献的人

Stephen Rushing - eSiteful - 原始工作

您也想成为英雄吗？选择一个问题并向我们发送 pull request！

kontent-ai / delivery-sdk-php

维护者

详细信息