A PHP Client library to consume the Acquia Content Hub API.

3.5.1 2023-12-12 13:25 UTC

This package is auto-updated.

Last update: 2024-04-30 00:29:41 UTC


Build Status

A PHP Client library to consume the Acquia Content Hub API.

Version Information

  • 0.6.x branch: Uses guzzle version ~5.0. Drupal 7 content hub module depends upon builds against this branch.
  • master branch: Uses guzzle version ~6.0. Drupal 8 content hub work, that is in progress at the moment, depends upon builds against this branch.


Install the latest version with Composer:

$ composer require acquia/content-hub-php


Register the application

Applications must register themselves with Content Hub so that they are assigned a unique identifier. The identifier is required by most API endpoints and is used as the "origin" of entities that are created by the application and published to the hub.


use Acquia\ContentHubClient\ContentHub;

// The URL to the Content Hub instance, provided by Acquia. Note that us-east-1
// might be replaced by a region that is within your geographic proximity.
$url = '';

// The API key and secret key provided by Acquia that are used to authenticate
// requests to Content Hub.

// For versions => 1.3, the api key is passed via the HMAC middleware.
$middleware = new MiddlewareHmacV1($apiKey, $secretKey, 'V1');
$client = new ContentHub('', $middleware, ['base_url' => $url]);

// For versions < 1.3, use the following client callback.
$client = new ContentHub($apiKey, $secretKey, '', ['base_url' => $url]);

// Register the application (or client site) with Content Hub. The parameter
// passed to this method is the human-readable name of the application.
$clientSite = $client->register('myclientsite');

// Stores the application's unique identifier that is assigned by Content Hub.
$clientId = $clientSite['uuid'];

Add a webhook receiver endpoint

Content Hub sends push notifications and status messages for asynchronous operations via webhooks. Even if your application doesn't require near-real-time content updates, you should implement a webhook receiver endpoint so that you have visibility into what is happening during asynchronous operations.


// Add the endpoint that received webhooks posted from Content Hub.
$webhook = $client->addWebhook('');

// Deleting the webhook receiver endpoint so that the application will no longer
// receive webhooks.

Creating entities


use Acquia\ContentHubClient\ContentHub;
use Acquia\ContentHubClient\Middleware\MiddlewareHmacV1;
use Acquia\ContentHubClient\Entities;
use Acquia\ContentHubClient\Entity;
use Acquia\ContentHubClient\Attribute;
use Acquia\ContentHubClient\Asset;

$middleware = new MiddlewareHmacV1($apiKey, $secretKey, 'V1');
$client = new ContentHub($clientId, $middleware, ['base_url' => $url]);

// The unique identifier of the entity, usually a randomly generated UUID.
// See to simplify UUID generation in PHP.
$uuid = '00000000-0000-0000-0000-000000000000'

// Build the entity, add required metadata
$entity = new Entity();

// Add attributes
$attribute = new Attribute(Attribute::TYPE_STRING);
$attribute->setValue('nothing', 'en');
$attribute->setValue('nada', 'es');
$entity->setAttribute('name', $attribute);

$attribute = new Attribute(Attribute::TYPE_INTEGER);
$entity->setAttribute('age', $attribute);

// Add references to binary assets, e.g. images.
$attribute = new Attribute(Attribute::TYPE_STRING);
$entity->setAttribute('image', $attribute);

$asset = new Asset();

// Create an entity container, add the entity to it.
$entities = new Entities();

// Render the entities in Common Data Format (CDF). This should be the payload
// returned by requests to $resourceUrl (defined below).
$cdf = $entities->json();

// Queue the entity to be added to Content Hub. An important concept in Content
// Hub is that write operations are asynchronous, meaning that the actions are
// not performed right away. In this example, a URL is passed to Content Hub
// which is expected to render the entities that you want to add to the hub in
// CDF. Content Hub receives the request and immediately returns a 202 which
// signifies that the request was received. In the background, Content Hub then
// makes a request to the URL, reads the CDF, and adds the entities. Success and
// error messages are sent via webhooks, so it is important to implement a
// webhook receiver endpoint so that you know what is going on.
$resourceUrl = '';

Reading entities


// Get the entity from Content Hub.
$entity = $client->readEntity($uuid);

// Get the "name" attribute in English, then Spanish.
$name   = $entity->getAttribute('name')->getValue('en');
$nombre = $entity->getAttribute('name')->getValue('es');

// Get the URL of the image attribute by dereferencing the token.
$token = $entity->getAttribute('image')->getValue();
$url = $entity->getAsset($token)->getUrl();

Updating entities


// Update the value of the "age" attribute from 4 to 5.
$attribute = new Attribute(Attribute::TYPE_INTEGER);
$entity->setAttribute('age', $attribute);

// Updating entities is also an asynchronous operation, so it may take a couple
// of seconds for the changes to be reflected in the hub.
$client->updateEntity($resourceUrl, $uuid);

Deleting entities


// Delete the entity by passing it's UUID. Delete operations are asynchronous,
// so it may take a couple of seconds for entities to be purged from the hub.

Running Tests

To better facilitate running tests, this library is now equipped with a Makefile with the following targets: (running make help also shows this information)

  • install: To install the dependencies
    • example: make install
  • method_test file=path/to/test/file: To run a specific test
    • example: make method_test method=testFromJSONStringCreation file=test/CDFObjectTest.php
  • file_test file=path/to/test/file: To run a specific test
    • example: make file_test file=test/CDFObjectTest.php
  • dir_tests dir=path/to/test-directory: To run all the tests inside a directory
    • example: make dir_tests test
  • all_tests: To run all Unit Tests
    • example: make all_tests
  • coverage: To create test coverage for the Unit Tests
    • example: make coverage
  • infection: To run infection on the existing tests
    • example: make infection