gyselroth/document-engine-client

PHP client for the document engine web service

gyselroth Document Engine Client

Client library for the gyselroth Document Engine webservice, _(*1)

Minimum Requirements

• PHP7.1 with extensions: json
• Build-tools: git, composer

Installation

• Install via composer

composer require gyselroth/document-engine-client:dev-trunk

Usage

• Creating a minimal client

$client = new Gyselroth\DocumentEngine\Client([
    'baseUrl' => 'https://docengine.example.com'
]);

• Creating a client using HTTP basic authentication

$client = new Gyselroth\DocumentEngine\Client([
    'baseUrl' => 'https://docengine.example.com',
    'authenticationType' => 'basic',
    'username'    => 'foo',
    'password'    => 'bar'
]);

• Creating a client using Bearer authentication (e.g. oauth2, openid connect etc.)

$client = new Gyselroth\DocumentEngine\Client([
    'baseUrl' => 'https://docengine.example.com',
    'authenticationType' => 'bearer',
    'token'    => 'aBCdeFGHIJKlmnOpq1RsTu',
    'password'    => 'bar'
]);

• The Document Engine Client lets you use own http client implementations. Any chosen implementation must implements the GuzzleHttp\ClientInterface interface.

$client = new Gyselroth\DocumentEngine\Client([
    'baseUrl' => 'https://docengine.example.com'
], new MyHttpClient());

Validate template

$template = new \SplFileObject('template.docx');
$validity = $client->validateTemplate($template);

Get merge-fields from template

$template = new \SplFileObject('template.docx');
$mergefields = $client->getMergefields($template);

Generate DOCX or PDF from template with given merge-data in a synchronous manner

$template = new \SplFileObject('template.docx');
$mergeData = [
        'field1' => 'value1',
        'field2' => 'value2',
];
$docxStream = $client->generateDocx($template, $mergeData);
$pdfStream = $client->generatePdf($template, $mergeData);

Note: The document generation methods return instances of Psr\Http\Message\StreamInterface. To read the stream into a file one can use a snippet like:, _(*2)

fwrite(fopen('result.pdf', 'w+'), $pdfStream->read($pdfStream->getSize()));

Generate Docx or PDF from template with given merge-data in an asynchronous manner

$template = new \SplFileObject('template.docx');
$mergeData = [
        'field1' => 'value1',
        'field2' => 'value2',
];
$jobId = $client->generateDocxAsync($template, $mergeData);
$jobId = $client->generatePdfAsync($template, $mergeData);

Check current status of a job

Note: Gyselroth\DocumentEngine\Client::getJobStatus will - in every case, except for the annotated exceptions - return a string which equals to a constant from Gyselroth\DocumentEngine\JobStatus, _(*3)

$jobStatus = $client->getJobStatus($jobId);

Get an asynchronously generated document

$documentStream = $client->getDocument($jobId);

Exceptions

All public methods of the client can throw one of the following exceptions: * Gyselroth\DocumentEngine\Client\Auth\AuthException * failed authorization (HTTP 401 Unauthorized), e.g. missing authentication * Gyselroth\DocumentEngine\Client\ClientException * client side error (HTTP 4xx, but not HTTP 401 Unauthorized), e.g. HTTP 400 Bad Request * Gyselroth\DocumentEngine\Client\ServerException * server side error (HTTP 5xx), e.g. HTTP 500 Internal Server Error * Gyselroth\DocumentEngine\Client\ConnectionException * Networking error, e.g. server not reachable, _(*4)

Development Notes

Installation after checkout

composer update

Running Tests

• Unit tests

composer unittest

• System tests

export DOCENG_CLIENT_TEST_BASEURL=http://example.com
export DOCENG_CLIENT_TEST_AUTH_TYPE=basic
export DOCENG_CLIENT_TEST_BASIC_USER=test
export DOCENG_CLIENT_TEST_BASIC_PASSWORD=secret
composer systemtest

• All tests

export DOCENG_CLIENT_TEST_BASEURL=http://example.com
export DOCENG_CLIENT_TEST_AUTH_TYPE=basic
export DOCENG_CLIENT_TEST_BASIC_USER=test
export DOCENG_CLIENT_TEST_BASIC_PASSWORD=secret
composer test

History

See CHANGELOG.md, _(*5)

Author and License

Copyright 2017-2018 gyselroth™ (http://www.gyselroth.com), _(*6)

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at, _(*7)

http://www.apache.org/licenses/LICENSE-2.0":http://www.apache.org/licenses/LICENSE-2.0, _(*8)

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License., _(*9)

Used Open Source Software

Open source packages used by the gyselroth Document Engine Client are copyright of their vendors, see related licenses within the vendor packages., _(*10)