#PHP-DocRaptor

PHP-DocRaptor is a simple API wrapper for DocRaptor.com. You will need a DocRaptor account before you can use this library, as it requires a valid API key.

##Dependencies This wrapper requires PHP 5.4 or newer. PHP 5.4 support will be dropped when it reaches EOL. We strongly advise to migrate your projects to PHP 5.6. Other than that, only the PHP curl extension is needed.

At the moment, this library still works with PHP 5.3, but we don't guarantee that for any future releases.

##Installation

This library is PSR-4 autoloading compliant and you can install it via composer. Just require it in your composer.json.

"require": {
    "expectedbehavior/php-docraptor": "1.2.0"
}

Then run composer update resp. composer install.

##Usage ###Simple

$docRaptor = new DocRaptor\ApiWrapper("YOUR_API_KEY_HERE"); // Or omit the API key and pass it in via setter
$docRaptor->setDocumentContent('<h1>Hello!</h1>')->setDocumentType('pdf')->setTest(true)->setName('output.pdf');
$file = $docRaptor->fetchDocument();

fetchDocument() returns document contents by default. You can optionally provide a file path to the fetchDocument() method, and the wrapper will attempt to write the returned value to that file path.

###Advanced

####Setting Prince Specific Options The API wrapper has the ability to set prince_options that is noted in the API documentation, where available keys are listed.

Example of setting prince version and PDF profile:

$docRaptor = new DocRaptor\ApiWrapper("YOUR_API_KEY_HERE");
$docRaptor
    ->setDocumentContent('<h1>Hello!</h1>')
    ->setDocumentType('pdf')
    ->setTest(true)
    ->setName('output.pdf')
    ->setDocumentPrinceOptions(array(
        'version' => '10',
        'profile' => 'PDF/A-1b',
    ));
$file = $docRaptor->fetchDocument();

Alternate HTTP Implementation

Since we're injecting a HttpTransferInterface interface into the ApiWrapper you can either inject the provided HttpClient or inject your own implementation of the interface.

$httpClient = new DocRaptor\HttpClient();
$docRaptor  = new DocRaptor\ApiWrapper("YOUR_API_KEY_HERE", $httpClient);

The provided HttpClient is a very simple domain specific curl wrapper that extracts all curl functions from the ApiWrapper which makes it possible to inject a mock client for testing.

Privacy

By default this library will report usage statistics - the api wrapper version and PHP version - to the DocRaptor service by way of a user agent string. You can disable this by providing a config object to the ApiWrapper constructor or the HttpClient constructor.

$config     = new DocRaptor\Config(false);
$httpClient = new DocRaptor\HttpClient($config);
$docRaptor  = new DocRaptor\ApiWrapper("YOUR_API_KEY_HERE", $httpClient, $config);
// or
$config    = new DocRaptor\Config(false);
$docRaptor = new DocRaptor\ApiWrapper("YOUR_API_KEY_HERE", null, $config); // will use HttpClient by default

##Options

###HTTPS or HTTP By default, PHP-DocRaptor submits requests over https. You can choose to submit via http by passing an argument to the setSecure() method (true for https, false for http):

$docRaptor->setSecure(false);

NB! It IS not secure, you're basically broadcasting your api key over the network.

###Async By default, PHP-DocRaptor submits requests by synchronous. However, if you are trying to process large files you will need to make an asynchronous request. You can choose to do this by passing an argument to the setAsync() method (true for asynchronous, false for synchronous request):

$docRaptor->setAsync(true);

Synchronous requests will return the file contents where as asynchronous requests will return a json response. Examples of the response can be found in the API documentation

###Async Callback URL If setAsync() is true and you want DocRaptor to do a POST request to your system when an asynchronous job has generated you can set the callback url via setCallbackUrl():

$docRaptor->setCallbackUrl('http://your-url.com');

Details on the POST request can be found in the API documentation

Contributing

If you find a bug, please make a new GitHub issue. If you know how to solve it, make a branch and once you're done make a new pull request.

When submitting a PR, you will need to install composer to run the tests. Once you have it installed, in the project root, run composer install. To run the tests from the project root, run vendor/bin/phpunit. They should all pass! Also we have travis and scrutinizer integration, so you can check those in your PR for things that could be better or don't work.