PHP SDK Tutorial With Composer

PHP applications use ReportingCloud through the PHP SDK textcontrol/textcontrol-reportingcloud, which Text Control publishes on Packagist and which wraps the Web API in the class ReportingCloud. With Composer and one script, you merge the demo template sample_invoice.tx of your template storage with invoice data and save the result as a PDF file from the command line. A second variant of the script sends a template file from your disk with the request instead of naming a stored one.

Prerequisites

A ReportingCloud account and an API key. A trial account is enough, and it has sample_invoice.tx in its template storage. Creating an Account shows how to sign up, and API Keys how to create a key in the ReportingCloud portal.
PHP 8.3 or later with the extensions dom, json and libxml. The current version of the SDK, 4.0.5, requires them.
Composer, the dependency manager for PHP, which installs the SDK and the libraries it uses.

Check Your PHP Version

Open a terminal and print the version of the PHP command-line interpreter:

php --version

The first line of the output names the version. With PHP 8.3 or higher, Composer installs the current version of the SDK. On PHP 8.1 or 8.2, it reports that it cannot use version 4.0.5 and installs version 4.0.2 instead, whose mergeDocument method takes the same parameters; on an older PHP version, the installation fails.

Create the Project

Create a directory for the project and change to it:
```
mkdir my-application && cd my-application
```

Install the SDK with Composer:

composer require textcontrol/textcontrol-reportingcloud

Composer creates composer.json with the requirement ^4.0 and downloads the SDK and its dependencies, among them the HTTP client Guzzle, into the vendor directory. It also writes vendor/autoload.php, the file that loads their classes.

Set the API Key

The script reads the API key from the environment variable REPORTINGCLOUD_API_KEY, which keeps it out of your source code. Set it in the terminal in which you run the script:

export REPORTINGCLOUD_API_KEY="<API key>"

In PowerShell, the command is $env:REPORTINGCLOUD_API_KEY = "<API key>". Replace <API key> with a key from the Manage Account page of the portal.

Write the Script

Create a file merge.php in the project directory with the following code:

<?php
declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use TextControl\ReportingCloud\ReportingCloud;

// Read the API key from the environment, never from source code
$apiKey = getenv('REPORTINGCLOUD_API_KEY');

if (!is_string($apiKey) || '' === $apiKey) {
    exit("Set the environment variable REPORTINGCLOUD_API_KEY.\n");
}

$reportingCloud = new ReportingCloud([
    'api_key' => $apiKey,
]);

// One record: the fields of the invoice and the line items of the item block
$mergeData = [
    [
        'yourcompany_companyname' => 'Text Control, LLC',
        'invoice_no'              => '778723',
        'billto_name'             => 'Joey Montana',
        'billto_companyname'      => 'Montana, LLC',
        'billto_street'           => '1 Washington Dr',
        'billto_zip'              => '27878',
        'billto_city'             => 'Charlotte',
        'payment_due'             => '20/1/2016',
        'item'                    => [
            [
                'qty'              => '1',
                'item_no'          => '1',
                'item_description' => 'Item description 1',
                'item_unitprice'   => '2663',
                'item_discount'    => '20',
                'item_total'       => '2130.40',
            ],
            [
                'qty'              => '1',
                'item_no'          => '2',
                'item_description' => 'Item description 2',
                'item_unitprice'   => '5543',
                'item_discount'    => '0',
                'item_total'       => '5543',
            ],
        ],
        'total_sub'               => '7673.4',
        'total_tax'               => '537.138',
        'total'                   => '8210.538',
    ],
];

// Merge the template of the template storage and receive one PDF per record
$documents = $reportingCloud->mergeDocument(
    $mergeData,
    ReportingCloud::FILE_FORMAT_PDF,
    'sample_invoice.tx'
);

file_put_contents(__DIR__ . '/invoice.pdf', $documents[0]);

echo "Written to invoice.pdf\n";

What the Code Does

declare(strict_types=1) makes PHP enforce the parameter types of the SDK's methods, and vendor/autoload.php loads the classes that Composer installed.
ReportingCloud, in the namespace TextControl\ReportingCloud, has a method for each endpoint of the Web API except GET /v1/document/share. The constructor takes an array of options: api_key is sent with every request in the header Authorization: ReportingCloud-APIKey <key>. Other options set the request timeout in seconds (timeout, 120 by default) and test mode (test), whose documents carry a "TEST MODE" watermark and which a Free account can't use. The options for user name and password still exist but are deprecated in favor of API keys.
$mergeData is a list of records, the data of one document each. The keys of a record are the names of the merge fields in the template, placeholders such as invoice_no, and the list item fills the merge block item, which repeats a table row for each line item. The SDK sends the arrays as JSON. Merge fields without data are removed from the document, the default of the merge setting removeEmptyFields.
mergeDocument sends the request POST /v1/document/merge and returns an array with one string of binary data per created document, already decoded from Base64. Its parameters are the data, the return format, the name of a stored template, the file name of a template on your disk, whether to append all records into one document and the merge settings.
ReportingCloud::FILE_FORMAT_PDF is the return format PDF. The merge endpoint also returns FILE_FORMAT_PDFA, FILE_FORMAT_RTF, FILE_FORMAT_DOC, FILE_FORMAT_DOCX, FILE_FORMAT_HTML, FILE_FORMAT_TX and FILE_FORMAT_TXT; a trial account creates no PDF/A.
file_put_contents writes the first and only document to invoice.pdf.

Run the Script

Run the script in the terminal in which you set the API key:

php merge.php

The script prints Written to invoice.pdf. Open the file in a PDF viewer to see the merged invoice; a trial account adds the ReportingCloud logo to every document. Each run is a merge request and counts 1 against the monthly document quota of your plan.

Send the Template With the Request

A template doesn't have to be in your storage. mergeDocument also takes the file name of a template on your disk, reads the file and sends it Base64-encoded in the template property of the request, which the Web API merges without storing it. The SDK accepts the extensions .doc, .docx, .rtf and .tx.

The SDK comes with a small Word template, test_template.docx, whose merge fields are name and age. In merge.php, replace everything from the line // One record: ... to the end with:

// A template with the merge fields name and age, shipped with the SDK
$templateFilename = __DIR__ . '/vendor/textcontrol/textcontrol-reportingcloud/resource/test_template.docx';

$mergeData = [
    [
        'name' => 'Jemima Puddle-Duck',
        'age'  => 7,
    ],
];

// Send the template with the data instead of naming a stored template
$documents = $reportingCloud->mergeDocument(
    $mergeData,
    ReportingCloud::FILE_FORMAT_PDF,
    '',
    $templateFilename
);

file_put_contents(__DIR__ . '/test_template_merged.pdf', $documents[0]);

echo "Written to test_template_merged.pdf\n";

The empty string in place of the template name says that no stored template is used. The parameter is a string: passing null, as samples for older versions of the SDK do, stops the script with a TypeError. Run php merge.php again and open test_template_merged.pdf.

Troubleshooting

The SDK reports an error of the Web API as a TextControl\ReportingCloud\Exception\RuntimeException whose message names the request and the status code, followed by the response body, cut off after 120 characters:

PHP Fatal error:  Uncaught TextControl\ReportingCloud\Exception\RuntimeException: Client error: `POST https://api.reporting.cloud/v1/document/merge?returnFormat=PDF&templateName=sample_invoice.tx` resulted in a `403 Forbidden` response:

403 Forbidden. The API key is wrong or deleted, the document quota of the month is used up or more than two requests of your account arrived at the same time. Compare the key with the list on Manage Account in the portal and check the quota on the dashboard.
400 Bad Request. The template is not in your template storage, or the request holds no data. Check the template name on the My Templates page of the portal.
TypeError for $templateName. The script passes null as the third argument of mergeDocument. Pass an empty string '' instead.
Composer cannot install the SDK. Your PHP version is older than 8.1, the oldest version that SDK 4.0 supports. Install PHP 8.3 or later; Check Your PHP Version shows which version of the SDK each PHP version gets.

Next Steps

Web API: the request of this script with curl, with the complete invoice data.
Merge Data: how arrays and objects map to merge fields and merge blocks.
Merge Settings: the settings that the last parameter of mergeDocument passes.
PHP: every method of the PHP SDK and the demo scripts in its demo directory.