This is a PHP library for wrapping the API calls to the Adobe Digital Publishing Suite Folio Producer API. The goal is to make your life easier and encapsulte the nitty gritty details. Specifically it will:
- automatically handle authentication when making API requests
- cache authentication information for making subsequent calls to the API
- automatically update tokens and API servers when provided by API responses
- reauthenticate and retry failed API requests if they return InvalidTicket errors
This project is a conglomeration between Coffee and Code and Studio Mercury, who have created many customized and engaging experiences together on the DPS platform for a wide variety of clients.
If you're interested in working with us on your own projects, you can reach out to us at thebrothersmueller@smny.us or jon@coffeeandcode.com.
This project requires PHP 5.3.3+.
It uses PHP namespaces
which require version 5.3+. It is highly recommended to use
PHP Sessions as
well so that we can re-use API authentication tokens instead of requesting
a new one for each page request. By simply calling session_start(), this
library will cache authentication information in sessions and sync changes
accordingly.
The project uses Composer for managing dependencies, which only includes PHPUnit for development.
For production, use: composer install --no-dev
For local development, use: composer install
The following code initializes your PHP session to re-use API authentication, loads your API configuration, and initializes the API client for subsequent calls.
<?php
session_start();
require 'vendor/autoload.php';
include 'config.php';
if (!isset($config)) { user_error('Missing configuration.'); }
$client = new DPSFolioProducer\Client($config);
You can then make API calls by issuing one of the following requests like the following retrieval of all folio metadata.
$request = $client->execute('get_folios_metadata');
// $request->response will be non-null if successful
if ($request->response) {
foreach ($request->response->folios as $folio) {
var_dump($folio);
echo '<hr />';
}
} else {
// iterate through all errors, including validation errors done
// without issuing the actual API request
foreach ($request->errors() as $error) {
echo $error->message;
}
}
This will authenticate with DPS and use your credentials on subsequent requests.
Note: You should not have to make this call explicitly as it is automatically called by the library when needed before executing another API call.
$request = $client->execute('create_session');
This will clear out stored credentials and any used session variables if the API call is successsful.
$request = $client->execute('delete_session');
This will update stored credentials to use the returned api and download servers on subsequent API requests.
$request = $client->execute('get_new_servers');
$request = $client->execute('get_folios_metadata');
echo '<h1>Folios</h1>';
if ($request->response) {
foreach ($request->response->folios as $folio) {
print_r($folio);
echo '<hr />';
}
}
$request = $client->execute('get_folio_metadata', array(
'folio_id' => $folio_id
));
$options = array(
'folioName' => 'Test Folio Name',
'folioNumber' => 'folio-'.time(),
'magazineTitle' => 'Magazine Title',
'resolutionHeight' => 240,
'resolutionWidth' => 240
);
$request = $client->execute('create_folio', $options);
$request = $client->execute('delete_folio', array(
'folio_id' => $folio_id
));
$request = $client->execute('duplicate_folio', array(
'folio_id' => $folio_id
));
$request = $client->execute('update_folio', array(
'folio_id' => $folio_id,
'folioName' => 'Updated Folio Name'
));
$request = $client->execute('upload_folio_preview_image', array(
'filepath' => 'images/folio image.jpg',
'folio_id' => $folio_id,
'orientation' => 'landscape' // or 'portrait'
));
$request = $client->execute('download_folio_preview_image', array(
'folio_id' => $folio_id,
'orientation' => 'landscape' // or 'portrait'
));
$request = $client->execute('delete_folio_preview_image', array(
'folio_id' => $folio_id,
'orientation' => 'landscape' // or 'portrait'
));
$request = $client->execute('upload_html_resources', array(
'filepath' => 'data/HTMLResources.zip',
'folio_id' => $folio_id
));
$request = $client->execute('delete_html_resources', array(
'folio_id' => $folio_id
));
$request = $client->execute('create_article', array(
'filepath' => 'data/example.folio',
'folio_id' => $folio_id
));
$request = $client->execute('delete_article', array(
'article_id' => $article_id,
'folio_id' => $folio_id
));
$request = $client->execute('update_article_metadata', array(
'article_id' => $article_id,
'folio_id' => $folio_id,
'description' => 'My new description.'
));
$request = $client->execute('get_articles_metadata', array(
'folio_id' => $folio_id
));
There are three types of errors that may be returned from a request. They
are Error, APIResponseError, and ValidationError. They all have a
message property that describes the error.
APIResponseError also contains the status and httpStatusCode from
the data returned by Adobe's DPS server.
PHPUnit is brought into the project with Composer which requires PHP 5.3.2+ to run.
- change to directory of project
- install Composer - http://getcomposer.org/doc/00-intro.md
- install Composer dependencies with
php composer.phar install - run unit tests with
vendor/bin/phpunit test/
Note: Test files must end in *Test.php and test method names must start with test*.
If you have xdebug installed, you can create an html code coverage report by running:
vendor/bin/phpunit --coverage-html ./coverage
This project used to run on CodeShip with the following config:
# Set php version through phpenv. 5.3, 5.4 and 5.5 available
phpenv local 5.5
# Install dependencies through Composer
composer install --prefer-source --no-interaction
# Install extensions through Pecl
# yes yes | pecl install memcache
phpunit
phpenv local 5.4
phpunit
phpenv local 5.3
phpunit