back

PHP documentation

Please make sure your target environment runs at least PHP7.4 and that the phar extension is installed. The following extensions are required as well:

ext-curl
ext-dom
ext-exif
ext-fileinfo
ext-gd
ext-iconv
ext-libxml
ext-simplexml
ext-zlib

There are two ways to use typeset.sh in your php project: you can use the phar file or use composer.

Using phar file

Once you have signed up and bought a license, you can download the phar file from your project page.

You will then include the phar file in your own php script, simply including it in your code. From there, you can use any typeset.sh functions and classes.


        <?php
        require_once 'typeset.sh.lib.phar';

        $html = file_get_contents('invoice.html');

        $pdf = \Typesetsh\createPdf($html);
        $pdf->toFile('invoice.pdf');

Composer access

You first need to add the repository to your project. This process is simple: run the following command in your composer project, turn adding packages.typeset.sh to your composer.json.


composer config repositories.typesetsh composer https://packages.typeset.sh

You now need to tell composer how it can authenticate, using the project id and a token. You can create more than one token for each developer or deployment setup if you want. The following command will add the token to your global composer configuration.


composer config -g http-basic.packages.typeset.sh "{PUBLIC_ID}" "{TOKEN}"

Now all that is left to do; require the typesetsh lib.


        composer require typesetsh/typesetsh

Additional information

External resources

Always make sure you only allow access to a set of allowed files or directories. This will make your project secure, preventing any sensitive data leaks. Through typeset.sh, you can define a callable function (uri-resolver) or object to validate and modify any external resource.

The most simple uri-resolver could just stop the rendering by throwing an exception.


        <?php

        $resolveUri = function(string $uri, string $base = null) {
            throw new \RuntimeException("File not allowed");
        }

        $pdf = \Typesetsh\createPdf($content, $resolveUri);
        $pdf->toFile('test.pdf');

To make life easier, you can simple use the available \Typesetsh\UriResolver class which allows to define resolvers for different schemes (http, data, file).


        <?php

        $base = getcwd();
        $cachePath = __DIR__.'/cache';
        $allowedDirectories = [
            __DIR__.'/public_html'
        ];

        // e.g. https://example.org/test.css
        $http = new \Typesetsh\UriResolver\Http($cachePath);

        // e.g. data:image/png;base64,iVBORw0KGgoAA...
        $data = new \Typesetsh\UriResolver\Data($cachePath);

        // e.g. file:/var/http/logo.png
        $file = new \Typesetsh\UriResolver\File($allowedDirectories);

        $resolveUri = new \Typesetsh\UriResolver(
            [
                'file' => $file,
                'http' => $http,
                'https' => $http,
                'data' => $data,
            ],
            $base
        );

        $pdf = \Typesetsh\createPdf($content, $resolveUri);
        $pdf->toFile('test.pdf');

There also some simple static UriResolver instantiation methods you can use:


        <?php
        \Typesetsh\UriResolver::httpOnly($cachePath);
        \Typesetsh\UriResolver::all($cachePath, $base);
        \Typesetsh\UriResolver::httpAndCurrentDir($cachePath, $base);
        \Typesetsh\UriResolver::localOnly($allowedDirectories, $base);

By default, any error such as file not found or access not allowed will trigger a runtime exception which is caught by the resolver and append to the \Typesetsh\UriResolver::$error property. Rendering can then continue by simply ignoring that resource.

You can monitor the exceptions in $resolveUri->errors, they are a great help when identifying issues when images etc are not loaded correctly.

Error handling

Rending HTML into a PDF is quite complex and errors can happen. Typeset.sh can recover from quite a few errors. So things like invalid CSS or HTML syntax may break your layout but not necessarily the rending process. Any runtime exceptions are store in the \Typesetsh\Result::$issues . You can monitor this issue property for any issues.

Wrap your your pdf process in a try{...} block if you want to check to make sure the rending was successful.


        <?php
        $base = getcwd();
        $cachePath = __DIR__.'/cache';

        $resolveUri = \Typesetsh\UriResolver::all($cachePath, $base);

        try {
            $pdf = \Typesetsh\createPdf($content, $resolveUri);
            $pdf->toFile('test.pdf');

            foreach ($pdf->issues as $error) {
                printf("Warning: %s\n", $error->getMessage());
            }
            foreach ($resolveUri->errors as $error) {
                printf("Warning: %s\n", $error->getMessage());
            }
        } catch (\Exception $e) {
            printf("Snap!: %s\n", $e->getMessage());
        }

PDF/X-4 conform.

You can save a PDF/X-4 conform PDF by adding a save handler. Typeset.sh can not convert your images into a CMYK, this must be done beforehand. We also recommend to define all your CSS colors using the cmyk() function.

By default, the handler will use the PSO Coated v3 (ECI) color profile. Custom or other profiles can be used as well by simply following the provided example in Pdf\HtmlToPdf\X4.

If you have any question, please don't hesitate to ask.


        <?php
        $html = "Hello World, I am a pdf/x-4 conform pdf!";

        $service = new \Typesetsh\HtmlToPdf();
        $service->saveHandler['pdf_x4'] = new \Typesetsh\HtmlToPdf\X4();

        $result = $service->render($html, \Typesetsh\UriResolver::all(null, __DIR__));
        $result->toFile(__DIR__.'/hello.x4.pdf');

PDF/A-1B conform.

Another save handler can be used to save a PDF/A-1B conform PDF. Certain features are not supported then and must be avoided. For instance, you should not use a color-alpha value or opacity property, as transparency is not allowed.


        <?php
        $html = "Hello World, I am a pdf/a-1b conform pdf!";

        $service = new \Typesetsh\HtmlToPdf();
        $service->saveHandler['pdf_a'] = new \Typesetsh\HtmlToPdf\A_1B_Web();

        $result = $service->render($html, \Typesetsh\UriResolver::all(null, __DIR__));
        $result->toFile(__DIR__.'/hello.a1b.pdf');

Signing a PDF

Pdfs can also be digital signed using a certificate that you provide. This process is quite simple. All you need to provide is a certificate and an optional private key if stored separately.

You can simple create a self signed certificate for testing.


        openssl req -x509 -nodes -days 365000 -newkey rsa:2048 -keyout my-certificate.crt -out my-certificate.crt

Then all you need to do, is adding the signature to your HtmlToPdf service.


        <?php
        $html = "Hello World!";

        $signature = new \Typesetsh\HtmlToPdf\Signature('file://'.__DIR__.'/my-certificate.crt');
        $signature->ContactInfo = 'contact@typeset.sh';
        $signature->Location = 'DE';
        $signature->Name = 'FooBar';
        $signature->Reason = 'Testing';


        $service = new \Typesetsh\HtmlToPdf();
        $service->saveHandler['signature'] = $signature;
        $service->saveHandler['pdf_a'] = new \Typesetsh\HtmlToPdf\A_1B_Web();

        $result = $service->render($html, \Typesetsh\UriResolver::all(null, __DIR__));
        $result->toFile(__DIR__.'/hello.signed.pdf');

What is a save handler?

A save handler is just a simple class that allows to validate or manipulate the PDF document before it gets saved. More than one save handler can be defined, the document and all its content is already generated by the time the save handler gets called. It only allows you to change the PDF document structure.

Performance

We try our best to ensure optimal performance. From the very start, performance was a key concern, driving many of our architectural design decisions. PHP is not C, but it can still be fast. Of course, rendering is a complex process, and it does require some work. While you can render small documents with a couple of pages within a few hundred milliseconds, big documents with lots of text can eat up significant time and memory.

Please feel free to get in touch with us if you are not sure if typeset.sh is the right tool for your needs.

CSS API PHP CMD QR