PHP Quickstart Tutorial

PHP is a first class citizen of the ReportingCloud ecosystem. Text Control GmbH — the author of ReportingCloud — actively develops and supports their PHP SDK to simplify access to the ReportingCloud Web API. Using only a few lines of code, you can create beautiful reports in all supported formats (DOC, DOCX, HTML, PDF, PDFA, RTF and TXT).

This quickstart tutorial shows how to create your first ReportingCloud application using the PHP SDK.

Prerequisites

1. In order to use the PHP SDK, you will need at least a free trial account for ReportingCloud.
   Please refer to Sign up for your Free Trial Account.

   Create Trial Account

2. Create an API Key for the API calls.
   Please refer to Manage API Keys.

Check Your PHP Version

Since all versions of PHPs prior to 8.1 have reached end-of-life and consequently, no further security updates will be released for them, the PHP SDK only supports PHP 8.1 or newer. Check you are running PHP 8.1 or newer, by opening your terminal and executing:

php --version

The output should be something like this:

PHP 8.1.22 (cli) (built: Aug 29 2023 10:48:28) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.22, Copyright (c) Zend Technologies
with Zend OPcache v8.1.22, Copyright (c), by Zend Technologies

The PHP version number in this case is 8.1.22, which is compatible to the PHP SDK.

Create a New Project

Next, we need to create a new project, by executing the following in the terminal:

mkdir my-application && cd my-application

We have created a new directory, into which we will install the PHP SDK.

To install the PHP SDK, we use Composer. If you do not already have Composer installed on your system, please refer to the Composer documentation. In the terminal, execute:

composer require textcontrol/textcontrol-reportingcloud:^4.0

The output should be something like this:

./composer.json has been created
Running composer update textcontrol/textcontrol-reportingcloud
Loading composer repositories with package information
Updating dependencies
Lock file operations: 12 installs, 0 updates, 0 removals
- Locking ctw/ctw-http (3.0.24)
- Locking fig/http-message-util (1.1.5)
- Locking guzzlehttp/guzzle (7.8.0)
- Locking guzzlehttp/promises (2.0.1)
- Locking guzzlehttp/psr7 (2.6.1)
- Locking psr/container (2.0.2)
- Locking psr/http-client (1.0.2)
- Locking psr/http-factory (1.0.2)
- Locking psr/http-message (2.0)
- Locking ralouphie/getallheaders (3.0.3)
- Locking symfony/deprecation-contracts (v3.3.0)
- Locking textcontrol/textcontrol-reportingcloud (4.0.1)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 12 installs, 0 updates, 0 removals
- Installing fig/http-message-util (1.1.5): Extracting archive
- Installing guzzlehttp/promises (2.0.1): Extracting archive
- Installing ralouphie/getallheaders (3.0.3): Extracting archive
- Installing psr/http-message (2.0): Extracting archive
- Installing psr/http-factory (1.0.2): Extracting archive
- Installing guzzlehttp/psr7 (2.6.1): Extracting archive
- Installing psr/http-client (1.0.2): Extracting archive
- Installing symfony/deprecation-contracts (v3.3.0): Extracting archive
- Installing psr/container (2.0.2): Extracting archive
- Installing guzzlehttp/guzzle (7.8.0): Extracting archive
- Installing ctw/ctw-http (3.0.24): Extracting archive
- Installing textcontrol/textcontrol-reportingcloud (4.0.1): Extracting archive
2 package suggestions were added by new dependencies, use `composer suggest` to see details.
Generating optimized autoload files
4 packages you are using are looking for funding.
Use the `composer fund` command to find out more!
No security vulnerability advisories found

Congratulations! You now have successfully installed the PHP SDK.

Create Your First PDF Document

Open your favorite IDE or text editor, and enter the following, adding your API key to the api_key key of the constructor's options array (line 11):

Save the file with the filename demo.php and execute in the terminal:

php demo.php

The output should be something like this:

Written to "test_template_merged.pdf".

You can now open the PDF file in your favorite PDF viewer.

So, what is going on in the above code snippet?

1. On line 2, we turn on strict_types, to ensure that types are enforced by PHP.

2. On line 4, we include Composer's autoloader file, so that the PHP SDK and dependencies are correctly autoloaded.

3. On lines 6 to 8, we import the PHP SDK.

4. On lines 10 to 12, we instantiate the main ReportingCloud component. Ensure to add your API key to the api_key key of the constructor's options array (line 11).

5. On line 14, we define the filename of the template file. This is a very simple template that ships with the PHP SDK for demonstration purposes. See directory /vendor/textcontrol/textcontrol-reportingcloud/resource on your file system or in the GitHub repository.

6. On line 15, we define the filename of the output PDF file.

7. On lines 17 to 20, we define the merge data -- that is the data that will be inserted into the template.

8. On lines 22 to 27, we send all the above to the ReportingCloud service, and are returned with an array of binary data.

9. On line 29, we write the binary data to disk.

Congratulations! You have now completed your very first mail-merge operation using ReportingCloud.

What Comes Next?

The PHP SDK ships with a number of demo applications, which illustrate all parts of ReportingCloud. To view these demos, please take a look at directory /vendor/textcontrol/textcontrol-reportingcloud/demo, either on your file system, or in the GitHub repository.

Getting Support

If you need help using the PHP SDK in your own application, please get in touch. The Getting Support section of the documentation details the support channels that are at your disposal.