README

Kontent.ai Delivery SDK for PHP

摘要

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

示例网站

在此处查看使用此 SDK 运行的 Laravel 示例网站： 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 上开发

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

在 Linux 上开发

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

名人墙

我们想对以下贡献者表示感谢，他们使项目成为可能

Stephen Rushing - eSiteful - 原始工作

你想成为英雄吗？选择一个问题并向我们发送拉取请求！

kentico / kontent-delivery-sdk-php

维护者

详细信息