README

Table of Contents generated with DocToc

Quick Start
Example
Implemented Data Services
Filtering results by fields and with Q Queries
Test client
Logging
Implementing custom mpx fields
- 1. Use the console tool to create initial classes
Related Projects
Overview of main classes
mpx Support
Known issues

Quick Start

PHP >= 7.4
Composer

composer require lullabot/mpx-php

Example

Here is a complete example showing how to load an account and media items from mpx. Most implementations should not contain all of this code in a single class. Instead, create functions, classes, or services to bridge the clients, caches, and locks into your application. For an example of how to do this, see the media_mpx module for Drupal 8.

A runnable version of this code is in a test at \Lullabot\Mpx\Tests\Functional\ReadmeTest::testExample().

<?php

use Lullabot\Mpx\Cache\Adapter\PHPArray\ArrayCachePool;
use GuzzleHttp\Psr7\Uri;
use Lullabot\Mpx\AuthenticatedClient;
use Lullabot\Mpx\Client;
use Lullabot\Mpx\DataService\DataObjectFactory;
use Lullabot\Mpx\DataService\DataServiceManager;
use Lullabot\Mpx\Service\IdentityManagement\User;
use Lullabot\Mpx\Service\IdentityManagement\UserSession;
use Lullabot\Mpx\TokenCachePool;
use Symfony\Component\Lock\Store\FlockStore;

// Only required if your application is not using Composer's autoloader already.
require_once './vendor/autoload.php';

// Create a new mpx client with the default configuration.
$defaults = Client::getDefaultConfiguration();
$client = new Client(new \GuzzleHttp\Client($defaults));

// Replace your username and password here. The username must begin with `mpx/`.
$user = new User('mpx/YOU@EXAMPLE.COM', 'secret');
// The optional lock and cache storage parameters are highly recommended for
// applications with multiple threads or requests.
$session = new UserSession($user, $client);

// This registers the annotation loader.
$dataServiceManager = DataServiceManager::basicDiscovery();

$accountFactory = new DataObjectFactory($dataServiceManager->getDataService('Access Data Service', 'Account', '1.0'), $authenticatedClient);

// Replace the ID with the account ID to load.
$account = $accountFactory->load(new Uri('http://access.auth.theplatform.com/data/Account/12345'))
    ->wait();
print "The loaded account is:\n";
var_dump($account);

$mediaFactory = new DataObjectFactory($dataServiceManager->getDataService('Media Data Service', 'Media', '1.10'), $authenticatedClient);

// Replace the ID to the media item to load. You can find it under "History -> ID" in the mpx console.
$media = $mediaFactory->load(new Uri('http://data.media.theplatform.com/media/data/Media/12345'), $account)
    ->wait();
print "The loaded media is:\n";
var_dump($media);

Implemented Data Services

The mpx API is very broad, and this library only implements a subset of the whole API. However, pull requests with new data services are always welcome. As well, data services are discovered through annotations, so they can be included from other libraries as needed.

Filtering results by fields and with Q Queries

Calls to select() and selectRequest() can be filtered by exact-match fields as well as with more complex searches.

<?php

// This skips the setup from above.
$mediaFactory = new DataObjectFactory($dataServiceManager->getDataService('Media Data Service', 'Media', '1.10'), $authenticatedClient);

// Search for "cats AND dogs" in any field.
$query = new ObjectListQuery();
$cats = new Term('cats');
$termGroup = new TermGroup($cats);
$termGroup->and(new Term('dogs'));
$query->add($termGroup);

// Limit to 10 results per page.
$query->getRange()->setEndIndex(10);
$results = $mediaFactory->select($query, $account);

foreach ($results as $media) {
    var_dump($media);
}

Test client

thePlatform provides a Media Data Service Web Client that can be used for quick testing of Media Data Service APIs. Unfortunately, the client can not be used for other data service APIs. To test those, see the functional tests in tests/src/Functional and the configuration in phpunit.xml.dist.

Logging

This library will log API actions that are transparent to the calling code. For example, calling code should handle logging of invalid credentials, while this library will log if an authentication was automatically refreshed during an API request that resulted in a 401.

If your application does not wish to log these actions at all, use \Psr\Log\NullLogger for any constructors that require a \Psr\Log\LoggerInterface.

Implementing custom mpx fields

mpx data service objects can have up to 100 custom fields defined per account. These fields can contain a variety of data types, with multiple namespaces of custom fields applying to a single object. This library allows for developers to create structured classes in their own application code that are discovered and used automatically.

1. Use the console tool to create initial classes

This CLI tool uses the mpx Field API to generate matching classes. Consider adding descriptions for each custom field in mpx, as these will be used automatically in doc comments. Run bin/console help mpx:create-custom-field for up-to-date documentation on this command.

For example, to generate classes for all custom fields attached to a Media object:

Clone this repository.
$ composer install
$ bin/console mpx:create-custom-field 'Php\Namespace\For\These\Classes' 'Media Data Service' 'Media' '1.10'
Enter your username and password. Progress will be shown for each field that is found.

As the mpx API has no data useful in creating class names, classes for each field namespace will be created with names like CustomFieldClassOne.php. It is highly suggested that these classes are renamed to match the fields they contain.

Each generated class will contain an @CustomField annotation:

/**
 * @CustomField(
 *     namespace="http://access.auth.theplatform.com/data/Account/555555",
 *     service="Media Data Service",
 *     objectType="Media",
 * )
 */

This is what the library uses to determine which class corresponds to a given namespace. Note that custom fields do not have schema versions. Be careful when deleting or changing data types on existing fields.

These custom fields should live in your application code. As such, you will need to provide a way to discover the classes since different applications have different source code structures. If you're using a module for a CMS like Drupal, it should already provide that functionality. If not, see \Lullabot\Mpx\DataService\CustomFieldManager::basicDiscovery for an example that can be adapted in many cases.

Once the classes are available, they will be automatically used when loading mpx objects. For example, to retrieve fields for the above namespace on a Media object, call:

$dof = new DataObjectFactory($manager->getDataService('Media Data Service', 'Media', '1.10'), $this->authenticatedClient);
$media = $dof->load(new Uri('http://data.media.theplatform.com/media/data/Media/12345'))->wait();
$fields = $media->getCustomFields('http://access.auth.theplatform.com/data/Account/555555'):

If a custom field class is not found, a notice will be logged and the empty MissingCustomFieldsClass will be attached in place of each set of fields.

Related Projects

Media mpx for Drupal 8: Integrate mpx assets with your Drupal 8 site.
Drupal Symfony Lock: Use Drupal's lock store as a backend for Symfony's locking library.

Overview of main classes

Lullabot\Mpx\Client

mpx API implementation of GuzzleHttp\ClientInterface. As a Client it doesn’t do anything extra but suppress errors to force a returning HTTP 200 for XML responses. It also handles XML from responses.

Lullabot\Mpx\AuthenticatedClient

Manages authenticated sessions and proxies API calls with a ClientInterface implementation, automatically refreshing expired API tokens as required.

Lullabot\Mpx\Service\IdentityManagement\UserSession

An mpx user. Just username and password getters.

Lullabot\Mpx\Token

mpx authentication token that is returned by the platform after sign in.

Lullabot\Mpx\TokenCachePool

Cache of user authentication tokens. This class is a wrapper around a \Psr\Cache\CacheItemPoolInterface object.

mpx Support

This library is not supported by thePlatform. If you need help with the library, open an issue here in GitHub. If you need help with the mpx service itself, see the mpx support portal to file a support request.

Known issues

#2001 in Guzzle forces processing notifications to load all objects that have been notified. Consider applying that patch with composer-patches until a new release is out.

lullabot / mpx-php

Maintainers

Details