Download the PHP package picsi/sideolclient without Composer

Sideol PHP Client

A PHP client for interacting with Sideol Engine

This package is a PHP client for Sideol, API to interact with powerful tools like Chromium and LibreOffice for converting numerous document formats (HTML, Markdown, Word, Excel, etc.) into PDF files, and more!

Quick Examples

You may convert a target URL to PDF and save it to a given directory:

You may also convert Office documents and merge them:

Requirement

This packages requires Sideol, a Docker-powered stateless API for PDF files:

• Docker
• Docker Compose
• Kubernetes
• Cloud Run

Installation

This package can not be installed with Composer, it's private repository. Once you download the repo you could install it using composer with setting below.

I use PSR-7 HTTP message interfaces (i.e., RequestInterface and ResponseInterface) and the PSR-18 HTTP client interface (i.e., ClientInterface). For the latter, you may need an adapter in order to use your favorite client library. Check the available adapters:

• https://docs.php-http.org/en/latest/clients.html

If you're not sure which adapter you should use, consider using the php-http/guzzle7-adapter:

Usage

• Send a request to the API
• Chromium
• LibreOffice
• PDF Engines
• Webhook

Send a request to the API

After having created the HTTP request (see below), you have two options:

1. Get the response from the API and handle it according to your need.
2. Save the resulting file to a given directory.

In the following examples, we assume the Sideol Engine API is available at http://localhost:3000.

Get a response

You may use any HTTP client that is able to handle a PSR-7 RequestInterface to call the API:

If you have a PSR-18 compatible HTTP client (see Installation), you may also use Sideol::send:

This helper will parse the response and if it is not 2xx, it will throw an exception. That's especially useful if you wish to return the response directly to the browser.

You may also explicitly set the HTTP client:

Save the resulting file

If you have a PSR-18 compatible HTTP client (see Installation), you may use Sideol::save:

It returns the filename of the resulting file. By default, Sideol creates a UUID filename (i.e., 36a1558b-02a5-4a45-a950-2f8f8fd7f644) with either a .zip or a .pdf file extension.

You may also explicitly set the HTTP client:

Filename

You may override the output filename with:

Sideol will automatically add the correct file extension.

Trace or request ID

By default, Sideol creates a UUID trace that identifies a request in its logs. You may override its value thanks to:

It will set the header Sideol-Trace with your value. You may also override the default header name:

Please note that it should be the same value as defined by the --api-trace-header Sideol's property.

The response from Sideol will also contain the trace header. In case of error, both the Sideol::send and Sideol::save methods throw a SideolApiError exception that provides the following method for retrieving the trace:

Chromium

The Chromium module interacts with the Chromium browser to convert HTML documents to PDF.

Convert a target URL to PDF

See https://khairu-aqsara.net/sideol/docs/modules/chromium#url.

Converting a target URL to PDF is as simple as:

You may inject <link> and <script> HTML elements thanks to the $extraLinkTags and $extraScriptTags arguments:

Please note that Sideol will add the <link> and <script> elements based on the order of the arguments.

Convert an HTML document to PDF

See https://khairu-aqsara.net/sideol/docs/modules/chromium#html.

You may convert an HTML document with:

Or with an HTML string:

Please note that it automatically sets the filename to index.html, as required by Sideol, whatever the value you're using with the Stream class.

You may also send additional files, like images, fonts, stylesheets, and so on. The only requirement is that their paths in the HTML DOM are on the root level.

Convert one or more markdown files to PDF

See https://khairu-aqsara.net/sideol/docs/modules/chromium#markdown.

The first argument is a Stream with HTML content, for instance:

Here, there is a Go template function toHTML. Sideol will use it to convert a markdown file's content to HTML.

Like the HTML conversion, you may also send additional files, like images, fonts, stylesheets, and so on. The only requirement is that their paths in the HTML DOM are on the root level.

Paper size

You may override the default paper size with:

Examples of paper size (width x height, in inches):

• Letter - 8.5 x 11 (default)
• Legal - 8.5 x 14
• Tabloid - 11 x 17
• Ledger - 17 x 11
• A0 - 33.1 x 46.8
• A1 - 23.4 x 33.1
• A2 - 16.54 x 23.4
• A3 - 11.7 x 16.54
• A4 - 8.27 x 11.7
• A5 - 5.83 x 8.27
• A6 - 4.13 x 5.83

Margins

You may override the default margins (i.e., 0.39, in inches):

Prefer CSS page size

You may force page size as defined by CSS:

Print the background graphics

You may also hide the default white background and allow generating PDFs with transparency with:

The rules regarding the printBackground and omitBackground form fields are the following:

• If printBackground is set to false, no background is printed.
• If printBackground is set to true:
  • If the HTML document has a background, that background is used.
  • If not:
    • If omitBackground is set to true, the default background is transparent.
    • If not, the default white background is used.

Landscape orientation

You may override the default portrait orientation with:

Scale

You may override the default scale of the page rendering (i.e., 1.0) with:

Page ranges

You may set the page ranges to print, e.g., 1-5, 8, 11-13. Empty means all pages.

Header and footer

You may add a header and/or a footer to each page of the PDF:

Please note that it automatically sets the filenames to header.html and footer.html, as required by Sideol, whatever the value you're using with the Stream class. Each of them has to be a complete HTML document:

The following classes allow you to inject printing values:

• date - formatted print date.
• title - document title.
• url - document location.
• pageNumber - current page number.
• totalPages - total pages in the document.

⚠️ Make sure that:

1. Margins top and bottom are large enough (i.e., ->margins(1, 1, 0.39, 0.39))
2. The font size is big enough.

⚠️ There are some limitations:

• No JavaScript.
• The CSS properties are independent of the ones from the HTML document.
• The footer CSS properties override the ones from the header;
• Only fonts installed in the Docker image are loaded - see the Fonts chapter.
• Images only work using a base64 encoded source - i.e., data:image/png;base64, iVBORw0K....
• background-color and color CSS properties require an additional -webkit-print-color-adjust: exact CSS property in order to work.
• Assets are not loaded (i.e., CSS files, scripts, fonts, etc.).
• Background form fields do not apply.

Wait delay

When the page relies on JavaScript for rendering, and you don't have access to the page's code, you may want to wait a certain amount of time (i.e., 1s, 2ms, etc.) to make sure Chromium has fully rendered the page you're trying to generate.

Wait for expression

You may also wait until a given JavaScript expression returns true:

User agent

You may override the default User-Agent header used by Sideol:

Extra HTTP headers

You may add HTTP headers that Chromium will send when loading the HTML document:

Fail on console exceptions

You may force Sideol to return a 409 Conflict response if there are exceptions in the Chromium console:

Emulate media type

Some websites have dedicated CSS rules for print. Using screen allows you to force the "standard" CSS rules:

You may also force the print media type with:

PDF Format

See https://khairu-aqsara.net/sidoel/docs/modules/pdf-engines#engines.

You may set the PDF format of the resulting PDF with:

LibreOffice

The LibreOffice module interacts with LibreOffice to convert documents to PDF, thanks to unoconv.

Convert documents to PDF

See https://khairu-aqsara.net/sideol/docs/modules/libreoffice#route. Converting a document to PDF is as simple as:

If you send many documents, Sideol will return a ZIP archive with the PDFs:

You may also merge them into one unique PDF:

Please note that the merging order is determined by the order of the arguments.

Landscape orientation

You may override the default portrait orientation with:

Page ranges

You may set the page ranges to print, e.g., 1-4. Empty means all pages.

⚠️ The page ranges are applied to all files independently.

PDF format

See https://khairu-aqsara.net/sideol/docs/modules/pdf-engines#engines.

You may set the PDF format of the resulting PDF(s) with:

You may also explicitly tell Sideol to use unoconv to convert the resulting PDF(s) to a PDF format:

⚠️ You cannot set both property, otherwise Sideol will return 400 Bad Request response.

PDF Engines

The PDF Engines module gathers all engines that can manipulate PDF files.

Merge PDFs

See https://khairu-aqsara.net/sideol/docs/modules/pdf-engines#merge.

Merging PDFs is as simple as:

Please note that the merging order is determined by the order of the arguments.

You may also set the PDF format of the resulting PDF(s) with:

Convert to a specific PDF format

See https://khairu-aqsara.net/sideol/docs/modules/pdf-engines#convert.

You may convert a PDF to a specific PDF format with:

If you send many PDFs, Sideol will return a ZIP archive with the PDFs:

Webhook

The Webhook module is a Sideol middleware that sends the API responses to callbacks.

⚠️ You cannot use the Sideol::save method if you're using the webhook feature. For instance:

You may also override the default HTTP method (POST) that Sideol will use to call the webhooks:

You may also tell Sideol to add extra HTTP headers that it will send alongside the request to the webhooks: