README

Kontent.ai Delivery SDK for PHP

摘要

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（可选）- 修改Rich文本元素中链接的解析方式，请参阅解析内容项链接。
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 - 原始作品

你愿意成为英雄吗？选择一个问题并发送pull request给我们！

kentico-cloud / delivery-sdk-php

维护者

详情