Complete reference guide to the Management SDK

Complete reference guide to the Management SDK

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

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