Complete reference guide to the Management client library

Complete reference guide to the Management client library

The first thing that needs to be done is initiating an instance of Contentful\Management\Client by giving it an access token. All actions performed using this instance of the Client will be performed with the privileges of the user this token belongs to.

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

When working with space-scoped or environment-scoped resources, you can use proxies. They are lazy-references to a space or an environment, and they allow you to avoid repeating the space and environment ID when making API calls:

// 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();

In the following guide, snippets will be using $environmentProxy and $spaceProxy whenever possible.

Usage

• Api Keys
• Assets
• Content types and content type snapshots
• Editor interfaces
• Entries and entry snapshots
• Environments
• Locales
• Organizations
• Personal access tokens
• Roles
• Spaces
• Space memberships
• Uploads
• UI extensions
• User
• Webhooks

Api Keys

Name	Scope	Fetch one	Fetch collection	Available actions
DeliveryApiKey	Space	$spaceProxy->getDeliveryApiKey($deliveryApiKeyId)	$spaceProxy->getDeliveryApiKeys($query = null)	Create, delete, update
PreviewApiKey	Space	$spaceProxy->getPreviewApiKey($previewApiKeyId)	$spaceProxy->getPreviewApiKeys($query = null)	-

Fetching:

$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();

Creating and modifying:

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

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

$deliveryApiKey->delete();

Assets

Name	Scope	Fetch one	Fetch collection	Available actions
Asset	Environment	$environmentProxy->getAsset($assetId)	$environmentProxy->getAssets($query = null)	Create, delete, update, archive, unarchive, publish, unpublish, process

Fetching:

$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');

Creating and modifying:

$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();

Content types and content type snapshots

Name	Scope	Fetch one	Fetch collection	Available actions
ContentType	Environment	$environmentProxy->getContentType($contentTypeId)	$environmentProxy->getContentTypes($query = null)	Create, delete, update, publish, unpublish
ContentTypeSnapshot	Environment	$environmentProxy->getContentTypeSnapshot($contentTypeId, $snapshotId)	$environmentProxy->getContentTypeSnapshots($contentTypeId, $query = null)	-

Fetching:

$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);

Creating and modifying:

$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();

Field types

use Contentful\Management\Resource\ContentType\Field;

// Arrays of strings (Symbol) or links to either assets or entries
$array = new Field\ArrayField(
  string $id,
  string $name,
  string $itemsType, // Either "Symbol" or "Link"
  string $itemsLinkType = null // If $itemsType is "Link", then either "Asset" or "Entry"
);
// Methods specific to this field
$array->getItemsType();
$array->setItemsType(string $itemsType);
$array->getItemsLinkType();
$array->setItemsLinkType(string $itemsLinkType);
$array->getItemsValidations();
$array->setItemsValidations(ValidationInterface[] $itemsValidations);
$array->addItemsValidation(ValidationInterface $validation);

// Booleans
$boolean = new Field\BooleanField(string $id, string $name);

// Dates, with hours
$date = new Field\DateField(string $id, string $name);

// Integer numbers
$integer = new Field\IntegerField(string $id, string $name);

// Links to either assets or entries
$link = new Field\LinkField(
    string $id,
    string $name,
    string $linkType // Either "Asset" or "Entry"
);
// Methods specific to this field
$array->getLinkType();
$array->setLinkType(string $linkType);

// Location coordinates, with latitude and longitured
$location = new Field\LocationField(string $id, string $name);

// Float numbers
$number = new Field\NumberField(string $id, string $name);

// Any JSON-convertible object
$object = new Field\ObjectField(string $id, string $name);

// Strings
$symbol = new Field\SymbolField(string $id, string $name);

// Long text
$text = new Field\TextField(string $id, string $name);

// Shared methods
$field->getId();
$field->getName();

$field->isRequired();
$field->setRequired(bool $required);

$field->isLocalized();
$field->setLocalized(bool $localized);

$field->isDisabled();
$field->setDisabled(bool $disabled);

$field->isOmitted();
$field->setOmitted(bool $omitted);

$field->getValidations();
$field->setValidations(ValidationInterface[] $validations);
$field->addValidation(ValidationInterface $validation);

Validations

use Contentful\Management\Resource\ContentType\Validation;

// Applicable to:
// - Link (to assets)
$assetFileSize = new Validation\AssetFileSizeValidation($min = null, $max = null);

// Applicable to:
// - Link (to image assets)
$assetImageDimentions = new Validation\AssetImageDimensionsValidation(int $minWidth = null, int $maxWidth = null, int $minHeight = null, int $maxHeight = null);

// Applicable to:
// - Date
$dateRange = new Validation\DateRangeValidation(string $min = null, string $max = null);

// Applicable to:
// - Symbol
// - Text
// - Integer
// - Number
$in = new Validation\InValidation(array $values = []);

// Applicable to:
// - Link (to entries)
$linkContentType = new Validation\LinkContentTypeValidation(array $contentTypes = []);

// Applicable to:
// - Link (to assets)
$linkMimetypeGroup = new Validation\LinkMimetypeGroupValidation(array $mimeTypeGroups = []);

// Applicable to:
// - Integer
// - Number
$range = new Validation\RangeValidation(int $min = null, int $max = null);

// Applicable to:
// - Symbol
// - Text
$regexp = new Validation\RegexpValidation(string $pattern = null, string $flags = null);

// Applicable to:
// - Array
// - Symbol
// - Text
$size = new Validation\SizeValidation($min = null, $max = null);

// Applicable to:
// - Symbol
// - Integer
// - Number
$unique = new Validation\UniqueValidation();

Editor interfaces

Name	Scope	Fetch one	Fetch collection	Available actions
EditorInterface	Environment	$environmentProxy->getEditorInterface($contentTypeId)	-	update

Fetching and updating

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

/** @var \Contentful\Management\Resource\EditorInterface\Control $control */
$control = $editorInterface->getControl('website');
$control->setWidgetId('urlEditor');

$editorInterface->update();

Entries and entry snapshots

Name	Scope	Fetch one	Fetch collection	Available actions
Entry	Environment	$environmentProxy->getEntry($entryId)	$environmentProxy->getEntries($query = null)	create, delete, update, archive, unarchive, publish, unpublish
EntrySnapshot	Environment	$environmentProxy->getEntrySnapshot($entryId, $snapshotId)	$environmentProxy->getEntries($entryId, $query = null)	-

Fetching:

$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);

Creating and modifying:

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

$environmentProxy->create($entry);

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

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

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

$entry->delete();

Environments

Name	Scope	Fetch one	Fetch collection	Available actions
Environment	Space	$spaceProxy->getEnvironment($environmentId)	$spaceProxy->getEnvironments($query = null)	create, delete, update

Fetching:

$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();

Creating and modifying:

$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();

Locales

Name	Scope	Fetch one	Fetch collection	Available actions
Locale	Environment	$environmentProxy->getLocale($localeId)	$environmentProxy->getLocales($query = null)	create, delete, update

Fetching:

$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();

Creating and modifying:

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

$locale->delete();

Organizations

Name	Scope	Fetch one	Fetch collection	Available actions
Organization	-	-	$client->getOrganizations($query = null)	-

Fetching:

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

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

Personal access tokens

Name	Scope	Fetch one	Fetch collection	Available actions
PersonalAccessToken	-	$client->getPersonalAccessToken($personalAccessTokenId)	$spaceProxy->getPersonalAccessTokens($query = null)	create, update, revoke

Fetching:

$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();

Creating and modifying:

$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

Name	Scope	Fetch one	Fetch collection	Available actions
Role	Space	$spaceProxy->getRole($roleId)	$spaceProxy->getRoles($query = null)	create, delete, update

Fetching:

$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();

Creating and modifying:

$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);

$permissions = $policy->getPermissions();
$permissions->setContentDelivery('all')
    ->setContentModel('all')
    ->setSettings('all');

$spaceProxy->create($role);

$policy->delete();

Contraints

use Contentful\Management\Resource\Role\Constraint;

$equality = new Constraint\EqualityConstraint(
    string $doc, // The JSON path of a property, for instance "sys.type"
    mixed $value // The required value, for instance "Entry"
);

// Requires that all constraints be satisfied
$and = new Constraint\AndConstraint(Constraint\ConstraintInterface[] $constraints);

// Requires that only one constraint be satisfied
$or = new Constraint\OrConstraint(Constraint\ConstraintInterface[] $constraints);

// Negates the content of the inner constraint
$not = new Constraint\NotConstraint(Constraint\ConstraintInterface $constraint);

Spaces

Fetching:

$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();

Creating and modifying:

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

$space->delete();

Space memberships

Name	Scope	Fetch one	Fetch collection	Available actions
SpaceMembership	Space	$spaceProxy->getSpaceMembership($environmentId)	$spaceProxy->getSpaceMemberships($query = null)	create, delete, update

Fetching:

$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();

Creating and modifying:

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

$spaceMembership->delete();

Uploads

Name	Scope	Fetch one	Fetch collection	Available actions
Upload	Space	$spaceProxy->getUpload($uplaodId)	-	create, delete

Fetching:

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

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

Creating and modifying:

// 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();
$asset->setFile('en-US', $upload->asAssetFile());

$environmentProxy->create($asset);

$asset->process();

$upload->delete();

UI extensions

Name	Scope	Fetch one	Fetch collection	Available actions
Extension	Environment	$environmentProxy->getExtension($environmentId)	$environmentProxy->getExtensions($query = null)	create, delete, update

Fetching:

$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();

Creating and modifying:

$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();

Users

Name	Scope	Fetch one	Fetch collection	Available actions
User	-	$client->getUserMe()	-	-

Fetching:

$user = $client->getUserMe();

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

Webhooks

Name	Scope	Fetch one	Fetch collection	Available actions
Webhook	Space	$spaceProxy->getWebhook($webhookId)	$spaceProxy->getWebhooks($query = null)	create, delete, update
WebhookCall	Space	$spaceProxy->getWebhookCall($webhookId, $callId)	$spaceProxy->getWebhookCalls($webhookId, $query = null)	-
WebhookHealth	Space	$spaceProxy->getWebhookHealth($webhookId)	-	-

Fetching:

$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();

// Request and response are only available when querying the "single" endpoint,
// not the collection one:
// Psr\Http\Message\RequestInterface
$call->getRequest();
// Psr\Http\Message\ResponseInterface
$call->getResponse();

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

Creating and modifying:

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

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

$webhook->delete();