README

PHP SDK for Contentful的 内容管理API。该SDK需要至少PHP 7.2或PHP 8.0及以上版本。

设置

使用Composer将此软件包添加到您的应用程序中，并执行以下命令

composer require contentful/contentful-management

然后，如果尚未添加，请包含Composer自动加载器

require_once 'vendor/autoload.php';

基本概念

首先需要执行的操作是使用访问令牌初始化Contentful\Management\Client的实例。使用此Client实例执行的所有操作都将使用此令牌所属用户的权限执行。

$client = new \Contentful\Management\Client('access-token');

当处理空间范围或环境范围资源时，可以使用代理。它们是对空间或环境的懒引用，并且允许您在调用API时避免重复空间和环境ID。

// Without space proxy
$deliveryApiKeys = $client->getDeliveryApiKeys($spaceId);
$roles = $client->getRoles($spaceId);
// With space proxy
$spaceProxy = $client->getSpaceProxy($spaceId);
$deliveryApiKeys = $spaceProxy->getDeliveryApiKeys();
$roles = $spaceProxy->getRoles();

// Without environment proxy
$assets = $client->getAssets($spaceId, $environmentId);
$entries = $client->getEntries($spaceId, $environmentId);
// With environment proxy
$environmentProxy = $client->getEnvironmentProxy($spaceId, $environmentId);
$assets = $environmentProxy->getAssets();
$entries = $environmentProxy->getEntries();

用法

• API密钥
• 资产
• 内容类型和内容类型快照
• 编辑器界面
• 条目和条目快照
• 环境
• 地区
• 组织
• 个人访问令牌
• 角色
• 空间
• 空间成员
• 上传
• UI扩展
• 用户
• 网络钩子
• 速率限制和重试

API密钥

获取

$deliveryApiKeys = $spaceProxy->getDeliveryApiKeys();
$deliveryApiKey = $spaceProxy->getDeliveryApiKey($deliveryApiKeyId);

echo $deliveryApiKey->getSystemProperties()->getId();
echo $deliveryApiKey->getName();
echo $deliveryApiKey->getAccessToken();
$previewApiKeyLink = $deliveryApiKey->getPreviewApiKey();

$previewApiKey = $spaceProxy->resolveLink($previewApiKeyLink);
echo $previewApiKey->getAccessToken();

创建和修改

$deliveryApiKey = new \Contentful\Management\Resource\DeliveryApiKey('Mobile');

$spaceProxy->create($deliveryApiKey);
echo $deliveryApiKey->getSystemProperties()->getId();
echo $deliveryApiKey->getAccessToken();

$deliveryApiKey->delete();

资产

获取

$assets = $environmentProxy->getAssets();
// Optionally, pass a query object
$query = (new \Contentful\Management\Query())
    ->setLimit(5);
$assets = $environmentProxy->getAssets($query);

$asset = $environmentProxy->getAsset($assetId);

echo $asset->getSystemProperties()->getId();
echo $asset->getTitle('en-US');

创建和修改

$asset = new \Contentful\Management\Resource\Asset();
$file = new \Contentful\Core\File\RemoteUploadFile('Contentful.svg', 'image/svg+xml', $url);
$asset->setTitle('en-US', 'My asset')
    ->setDescription('en-US', 'My description')
    ->setFile('en-US', $file);

$environmentProxy->create($asset);

// Omit the locale to process the files for all locales
$asset->process('en-US');

$asset->setDescription('en-US', 'An even better description');
$asset->update();

$asset->archive();
$asset->unarchive();

$asset->publish();
$asset->unpublish();

$asset->delete();

内容类型和内容类型快照

获取

$contentTypes = $environmentProxy->getContentTypes();
// Optionally, pass a query object
$query = (new \Contentful\Management\Query())
    ->setLimit(5);
$contentTypes = $environmentProxy->getContentTypes($query);

$contentType = $environmentProxy->getContentType($contentTypeId);

echo $contentType->getSystemProperties()->getId();
echo $contentType->getName();

// Fetch the published version of content types
$contentTypes = $environmentProxy->getPublishedContentTypes($query);
$contentType = $environmentProxy->getPublishedContentType($contentTypeId);

// Fetch snapshots from a content type, or from an environment proxy
$snapshots = $contentType->getSnapshots();
$snapshot = $contentTy->getSnapshot($snapshotId);

$snapshots = $environmentProxy->getContentTypeSnapshots($contentTypeId);
$snapshot = $environmentProxy->getContentTypeSnapshot($contentTypeId, $snapshotId);

创建和修改

$contentType = new \Contentful\Management\Resource\ContentType('Blog Post');
$contentType->setDescription('My description');
$contentType->addNewField('Symbol', 'title', 'Title');
$contentType->addNewField('Text', 'body', 'Body');

$customContentTypeId = 'blogPost';
$environmentProxy->create($contentType, $customContentTypeId);

$contentType->addNewField('Date', 'publishedAt', 'Published At');
$contentType->update();

$contentType->publish();
$contentType->unpublish();

$contentType->delete();

编辑器界面

获取和更新

$editorInterface = $environmentProxy->getEditorInterface($contentTypeId);

$control = $editorInterface->getControl('website');
$control->setWidgetId('urlEditor');

$editorInterface->update();

条目和条目快照

获取

$entries = $environmentProxy->getEntries();
// Optionally, pass a query object
$query = (new \Contentful\Management\Query())
    ->setLimit(5);
$entries = $environmentProxy->getEntries($query);

$entry = $environmentProxy->getEntry($entryId);

echo $entry->getSystemProperties()->getId();
echo $entry->getField('title', 'en-US');

// Fetch snapshots from an entry, or from an environment proxy
$snapshots = $entry->getSnapshots();
$snapshot = $entry->getSnapshot($snapshotId);

$snapshots = $environmentProxy->getEntrySnapshots($contentTypeId);
$snapshot = $environmentProxy->getEntrySnapshot($entryId, $snapshotId);

创建和修改

$entry = new \Contentful\Management\Resource\Entry($contentTypeId);
$entry->setField('title', 'en-US', 'My awesome blog post');
$entry->setField('body', 'en-US', 'Something something...');

//Add existing assets
$images = [
    new \Contentful\Core\Api\Link('Example-existing-asset-id', 'Asset'),
    new \Contentful\Core\Api\Link('Example-existing-asset-id-2', 'Asset'),
];
$entry->setField('productImages', 'en-US', $images);

$environmentProxy->create($entry);

$entry->setField('body', 'en-US', 'Updated body');
$entry->update();

$entry->archive();
$entry->unarchive();

$entry->publish();
$entry->unpublish();

$entry->delete();

环境

获取

$environments = $spaceProxy->getEnvironments();
// Optionally, pass a query object
$query = (new \Contentful\Management\Query())
    ->setLimit(5);
$environments = $spaceProxy->getEnvironments($query);

$environment = $spaceProxy->getEnvironment($environmentId);

echo $environment->getSystemProperties()->getId();
echo $environment->getName();

创建和修改

$environment = new \Contentful\Management\Resource\Environment('QA');
$spaceProxy->create($environment);

$environmentId = $environment->getSystemProperties()->getId();

// An environment might take a while to create,
// depending on the size of the master environment,
// so it might be a good idea to poll it until it's ready.
do {
    $environment = $spaceProxy->getEnvironment($environmentId);
    $status = $environment->getSystemProperties()->getStatus()->getId();
} while ($status !== 'ready');

$environment->delete();

使用不同源创建环境

$environment = new \Contentful\Management\Resource\Environment('QA','source-env-id');
$spaceProxy->create($environment);

// An environment might take a while to create,
// depending on the size of the master environment,
// so it might be a good idea to poll it until it's ready.
do {
    $environment = $spaceProxy->getEnvironment($environmentId);
    $status = $environment->getSystemProperties()->getStatus()->getId();
} while ($status !== 'ready');

$environment->delete();

地区

获取

$locales = $environmentProxy->getLocales();
// Optionally, pass a query object
$query = (new \Contentful\Management\Query())
    ->setLimit(5);
$locales = $environmentProxy->getLocales($query);

$locale = $environmentProxy->getLocale($localeId);

echo $locale->getSystemProperties()->getId();
echo $locale->getName();
echo $locale->getCode();

创建和修改

$locale = new \Contentful\Management\Resource\Locale('English (United States)', 'en-US');
$environmentProxy->create($locale);

$locale->delete();

组织

获取

$organizations = $client->getOrganizations();
$organization = $organizations[0];

echo $organization->getSystemProperties()->getId();
echo $organization->getName();

个人访问令牌

获取

$personalAccessTokens = $client->getPersonalAccessTokens();
// Optionally, pass a query object
$personalAccessTokens = (new \Contentful\Management\Query())
    ->setLimit(5);
$personalAccessTokens = $client->getPersonalAccessTokens($query);

$personalAccessToken = $client->getPersonalAccessToken($personalAccessTokenId);

echo $personalAccessToken->getSystemProperties()->getId();
echo $personalAccessToken->getName();

创建和修改

$readOnly = false;
$personalAccessToken = new \Contentful\Management\Resource\PersonalAccessToken('Development access token', $readOnly);
$client->create($personalAccessToken);

// For security reasons, the actual token will only be available after creation.
echo $personalAccessToken->getToken();

$personalAccessToken->revoke();

角色

获取

$roles = $spaceProxy->getRoles();
// Optionally, pass a query object
$query = (new \Contentful\Management\Query())
    ->setLimit(5);
$roles = $spaceProxy->getRoles($query);

$role = $spaceProxy->getRole($roleId);

echo $role->getSystemProperties()->getId();
echo $role->getName();

创建和修改

$role = new \Contentful\Management\Resource\Role('Publisher');

$policy = new \Contentful\Management\Resource\Policy('allow', 'publish');
$role->addPolicy($policy);

$constraint = new \Contentful\Management\Resource\Role\Constraint\AndConstraint([
    new \Contentful\Management\Resource\Role\Constraint\EqualityConstraint('sys.type', 'Entry'),
    new \Contentful\Management\Resource\Role\Constraint\EqualityConstraint('sys.type', 'Asset'),
]);
$policy->setConstraint($constraint);

$spaceProxy->create($role);

$policy->delete();

空间

获取

$spaces = $client->getSpaces();
// Optionally, pass a query object
$query = (new \Contentful\Management\Query())
    ->setLimit(5);
$spaces = $client->getSpaces($query);

$space = $client->getSpace($spaceId);

echo $space->getSystemProperties()->getId();
echo $space->getName();

创建和修改

$space = new \Contentful\Management\Resource\Space('Website', $organizationId, $defaultLocaleCode);
$client->create($space);

$space->delete();

空间成员

获取

$spaceMemberships = $spaceProxy->getSpaceMemberships();
// Optionally, pass a query object
$query = (new \Contentful\Management\Query())
    ->setLimit(5);
$spaceMemberships = $spaceProxy->getSpaceMemberships($query);

$spaceMembership = $spaceProxy->getSpaceMembership($spaceMembershipId);

echo $spaceMembership->getSystemProperties()->getId();
echo $spaceMembership->getUser()->getId();

创建和修改

$spaceMembership = new \Contentful\Management\Resource\SpaceMembership();
$spaceMembership->setEmail($userEmail)
    ->setAdmin(false)
    ->addRoleLink($roleId);
$spaceProxy->create($spaceMembership);

$spaceMembership->delete();

上传

获取

$upload = $spaceProxy->getUpload($uploadId);

echo $upload->getSystemProperties()->getId();

创建和修改

// You can pass as argument an fopen resource, an actual string, or a PSR-7 compatible stream
$upload = new \Contentful\Management\Resource\Upload(\fopen($myFile, 'r'));
$spaceProxy->create($upload);

$asset = new \Contentful\Management\Resource\Asset();
// To use the upload as an asset, you need to supply an asset name and a mime type
$asset->setFile('en-US', $upload->asAssetFile('my-asset-name.png', 'image/png'));

$environmentProxy->create($asset);

$asset->process();

$upload->delete();

UI扩展

获取

$extensions = $environmentProxy->getExtensions();
// Optionally, pass a query object
$query = (new \Contentful\Management\Query())
    ->setLimit(5);
$extensions = $environmentProxy->getExtensions($query);

$extension = $environmentProxy->getExtension($extensionId);

echo $extension->getSystemProperties()->getId();
echo $extension->getName();

创建和修改

$extension = new \Contentful\Management\Resource\Extension('My awesome extension');
$extension->setSource('https://www.example.com/extension-source')
    ->addNewFieldType('Symbol');

$environmentProxy->create($extension);

$extension->addNewFieldType('Link', ['Entry']);
$extension->update();

$extension->delete();

用户

获取

$user = $client->getUserMe();

echo $user->getSystemProperties()->getId();
echo $user->getEmail();

网络钩子

获取

$webhooks = $spaceProxy->getWebhooks();
// Optionally, pass a query object
$query = (new \Contentful\Management\Query())
    ->setLimit(5);
$webhooks = $spaceProxy->getWebhooks($query);

$webhook = $spaceProxy->getWebhook($webhookId);

echo $webhook->getSystemProperties()->getId();
echo $webhook->getName();

// You can get calls and health from a webhook or from a space proxy
$calls = $webhook->getCalls();
$call = $webhook->getCall($callId);
$health = $webhook->getHealth();

$calls = $spaceProxy->getWebhookCalls($webhookId);
$call = $spaceProxy->getWebhookCall($webhookId, $callId);
$health = $spaceProxy->getWebhookHealth($webhookId);

echo $call->getStatusCode();
echo $call->getUrl();
echo $call->getEventType();

echo $health->getTotal();
echo $health->getHealthy();

创建和修改

$webhook = new \Contentful\Management\Resource\Webhook('Publish webhook', $url, ['Entry.publish']);
$spaceProxy->create($webhook);

$webhook->addTopic('Asset.publish');
$webhook->update();

$webhook->delete();

速率限制和重试

某些API调用受速率限制，具体请参阅此处。SDK可以通过max_rate_limit_retries选项指示重试调用次数。

$client = new \Contentful\Management\Client('KEY',['max_rate_limit_retries' => 2]);
$proxy = $client->getSpaceProxy('SPACE_ID');
$envName = uniqid();
$env = new \Contentful\Management\Resource\Environment($envName);
$proxy->create($env); //this call will retry two times (so three calls couting the original one), before throwing an exception

如果重试应该在60秒以上（如X-Contentful-RateLimit-Second-Remaining标头此处所述）发生，则调用将抛出RateWaitTooLongException异常。这是为了确保您的脚本不会运行时间过长。

贡献

欢迎提交PR！但是，如果您想在本地开发，则需要使用--ignore-platform-reqs安装，因为目前用于测试的一个库尚未官方支持PHP8。

关于Contentful

Contentful是一个面向Web应用程序、移动应用程序和连接设备的托管内容管理平台。它允许您在云中创建、编辑和管理内容，并通过强大的API在任何地方发布。Contentful提供用于管理编辑团队并促进组织之间合作的工具。

许可证

版权所有 (c) 2015-2019 Contentful GmbH。代码在MIT许可证下发布。有关更多信息，请参阅LICENSE。