README

此库根据媒体管理核心数据模型抽象化了与 PBS 媒体管理 API 的交互。

安装

使用 composer 安装

composer require openpublicmedia/pbs-media-manager-php

使用

此库提供的主要类是 OpenPublicMedia\PbsMediaManager\Client。可以使用 Client 实例以各种方式查询 API，基于核心数据模型。客户端需要 PBS 提供的 API 密钥和密钥。

响应数据结构

Client 类的响应将返回生成器，用于复数获取器（例如 getFranchises、getShows、getSeasons 等），或对象用于单数获取器（例如 getEpisode、getCollection 等）。搜索方法（例如 searchShows、searchEpisodes 等）也返回生成器。

在所有情况下，表示 API 数据的对象都遵循以下属性的标准结构

• id: 对象的 guid。
• type: 对象类型的字符串（例如 "franchise"、"show"、"season" 等）。
• links: 对象相关 API 端点的链接。
• attributes: 关于对象的元数据。

示例

创建客户端

use OpenPublicMedia\PbsMediaManager\Client;

$api_key = 'xxxxxxxxxxxxxx';
$api_secret = 'xxxxxxxxxxx';

$client = new Client($api_key, $api_secret);

获取所有品牌

$franchises = $client->getFranchises();

foreach ($franchises as $franchise) {
    var_dump($franchise);
    class stdClass#45 (4) {
        public $links => class stdClass#40 (4) { ... }
        public $attributes => class stdClass#39 (18) { ... }
        public $type => string(9) "franchise"
        public $id => string(36) "e08bf78d-e6a3-44b9-b356-8753d01c7327"
      }
}

获取单个剧集

$episode = $client->getEpisode('08e7ee9c-800a-406f-86f0-bf0bb77fe42b');

var_dump($episode);
class stdClass#80 (3) {
    public $attributes => class stdClass#38 (20) { ... }
    public $id => string(36) "08e7ee9c-800a-406f-86f0-bf0bb77fe42b"
    public $type => string(7) "episode"
}

搜索（品牌、剧集、特别节目和剧集）

$results = $client->searchEpisodes('Seattle');

foreach ($results as $result) {
    var_dump($result);
    class stdClass#45 (4) {
        public $links => class stdClass#40 (4) { ... }
        public $attributes => class stdClass#39 (18) { ... }
        public $type => string(9) "episode"
        public $id => string(36) "bb053151-7d3f-42bd-ac69-d0c19f040b27"
      }
}

搜索（资产）

资产具有更高级的搜索选项，必须直接作为查询参数传递给方法。以下示例搜索所有属于标题中包含 "Mossback" 的剧集的资产，其中 "Seattle" 和 "came" 出现在 *剧集* 标题中。

有关可用的搜索筛选器的详细文档，请参阅 搜索资产。

$results = $client->searchAssets([
    'show-title' => 'Mossback',
    'episode-title' => ['Seattle', 'came'],
]);

var_dump(count($results));
int(4)

foreach ($results as $r) {
    print "{$r->id}\t{$r->attributes->title}\r\n";
}

4eb40f99-cd4f-4582-9e8a-1ef0a99b8293    When Camelot Came to the Seattle World's Fair
e96d66c4-aa8e-4a83-a060-bd712178ff6b    The Music Festival That Came Before Woodstock
884e4401-de5e-4423-8cab-1c611dd6e624    When Mark Twain Came to Seattle
73d7b2fe-111b-4318-8721-e93937bf22ea    When the ‘American Hitler’ Came to Washington

处理异常

大多数复数 Client 获取器（例如 Client::getShows）可以抛出 OpenPublicMedia\PbsMediaManager\Exception\BadRequestException。此异常将包含一个 JSON 编码的消息，可用于确定后续操作。单数获取器（例如 Client::getShow）通常对于无效 ID 返回 null。

try {
    $shows = $client->getShows(['page' => 100000]);
} catch (BadRequestException $e) {
    $message = json_decode($e->getMessage());
    var_dump($message);
    class stdClass#17 (1) {
      public $detail =>
      string(13) "Invalid page."
    }
}

开发目标

有关向此项目贡献的信息，请参阅 CONTRIBUTING。

v1

• API 身份验证 (OpenPublicMedia\PbsMediaManager\Client)
• API 直接查询 ($client->request())
• 结果/错误处理
• 核心数据对象的 GET 包装器 ($client->getXXX())
• 透明分页响应处理 (OpenPublicMedia\PbsMediaManager\Response\PagesResponse)

v1.x

• POST 支持 (OpenPublicMedia\PbsMediaManager\Client::post)
  • 资产 (OpenPublicMedia\PbsMediaManager\Client::addAsset)
  • 剧集 (OpenPublicMedia\PbsMediaManager\Client::addEpisode)
  • 特别节目 (OpenPublicMedia\PbsMediaManager\Client::addSpecial)
  • 季 (OpenPublicMedia\PbsMediaManager\Client::addSeason)
• PATCH 支持 (OpenPublicMedia\PbsMediaManager\Client::patch)
  • 资产 (OpenPublicMedia\PbsMediaManager\Client::updateAsset)
  • 剧集 (OpenPublicMedia\PbsMediaManager\Client::updateEpisode)
  • 特别节目 (OpenPublicMedia\PbsMediaManager\Client::updateSpecial)
  • 季（API 不支持）
  • 剧集（API 不支持）
• 删除支持（《OpenPublicMedia\PbsMediaManager\Client::delete》）
  • 资产（《OpenPublicMedia\PbsMediaManager\Client::deleteAsset》）
  • 剧集（《OpenPublicMedia\PbsMediaManager\Client::deleteEpisode》）
  • 特别节目（《OpenPublicMedia\PbsMediaManager\Client::deleteSpecial》）
  • 季（API 不支持）
• 资产导入/替换状态处理

v2

• PHP 8 支持

v3.x

• 核心数据对象实体
• 高级资产可用性处理
• 高级变更日志端点操作
• 链式查询参数构建（主要针对资产搜索）