BooXtreamClient
A client class in PHP for use with the BooXtream webservice., (*1)
- Has the ability to upload an epub file to the BooXtream webservice
- Alternatively specify an epub file stored on the BooXtream storage servers
- Can return an epub file, a (converted) mobi file or an xml containing one or more downloadlinks
Installing via Composer
BooXtreamClient is available in Packagist, just add it to your composer.json, (*2)
composer require icontact/booxtreamclient
or, (*3)
{
"require": {
"icontact/booxtreamclient": "~2.0"
}
}
Alternatively you can just download the package and run composer install to get the requirements., (*4)
The only requirements at the moment are PHP 7.2.5 and up and Guzzle., (*5)
If you do not wish to use Composer you will need to fulfill the dependencies on your own., (*6)
Usage
You will need:
- a username and API key for the service
- an array of options (refer to the BooXtream web service API documentation)
- an epub file or a file stored on the BooXtream service, (*7)
The type parameter can be either 'epub', 'mobi' or 'xml'. In the first two cases a file will be returned by the service, in the case of 'xml' you will receive one or two downloadlinks, depending on your settings (aka delivery platform)., (*8)
require('vendor/autoload.php');
use \Icontact\BooXtreamClient\BooXtreamClient;
use \Icontact\BooXtreamClient\Options;
use \GuzzleHttp\Client;
// a guzzle client
$guzzle = new Client();
// an options object, refer to the documentation for more information on the options
$options = new Options([
'customername' => 'Foo Bar',
'referenceid' => 'bazdibzimgir12345',
'languagecode' => 1033
]);
// create the BooXtream Client
$type = 'xml'; // returns downloadlinks
$credentials = ['username', 'apikey']; // you will need a username and an API key
$BooXtream = new BooXtreamClient($type, $options, $credentials, $guzzle);
We're now going to send the request., (*9)
// add a file location to the epub file you want to watermark
$BooXtream->setEpubFile('/path/to/your/file.epub');
// and send
$Response = $BooXtream->send();
A request with a stored file is slightly different. Instead of adding an epubfile you just need to provide the name of the file (with or without .epub extension):, (*10)
$BooXtream->setStoredEpubFile('filename');
Options
The available options are as follows. Refer to the API Documentation for details:, (*11)
required:
- customername (string)
- customeremailaddress (string)
- referenceid (string)
- languagecode (int)
- expirydays (int)
- downloadlimit (int)
optional:
- exlibrisfont (string), this should contain either 'sans', 'serif' or 'script'
- exlibris (bool), default: false
- chapterfooter (bool), default: false
- disclaimer (bool), default: false
- showdate (bool), default: false
- epub (bool), default: true
- kf8mobi (bool), default: false
custom ex libris
It is also possible to set a custom ex libris file according to the specifications in the API Documentation., (*12)
$BooXtream->setExlibrisFile('filename');
Response
The BooXtreamClient returns an object of the type of GuzzleHttp\Psr7\Response, (*13)
The response always contains a statuscode ($Response->getStatusCode();). If the request was successful this will be 200. Any other status code is an error and will throw an Exception of the type of GuzzleHttp\Exception\ClientException. You can retrieve a Response object as follows:, (*14)
try {
$Response = $BooXtream->send();
} catch (ClientException $e) {
$Response = $e->getResponse();
}
Check the HTTP Reason ($Response->getReasonPhrase();) for more information., (*15)
Epub/Mobi
If you requested an epub or mobi file this can be accessed by reading the body ($Response->getBody();). The body is a stream, refer to the PHP Documentation for more information on how to access it. Furthermore you can access the file's content-type with $Response->getHeader('content-type');., (*16)
XML or error
If you requested xml (aka delivery platform) or if an error occurred more information can be found by accessing the body ($Response->getBody();). The body is a stream, refer to the PHP Documentation for more information on how to access it., (*17)
The XML looks like this:
- Request, containing information about the request you made (options, etc)
- Response, containing either a set of downloadlinks or more information on an error, (*18)
Wallogit.com
