Using typeset.sh

Before rendering your first page, take a moment to familiarize yourself with some basic usage concepts.

Allowing external resources

It is important to understand that typeset.sh has strict restrictions on including external resources (such as CSS, fonts, and images) by default. A resolveUri function must be provided to resolve the URL of each external resource. This function receives the requested URL (e.g. ./my-logo.png) and returns the actual path to the file, or an empty string if the resource is not found or not allowed.

To simplify this process, you can use the \Typesetsh\UriResolver class to define resolvers for different schemes (e.g. "http://", "data://", "file://").

$content = "Hello <strong>World</strong>";

$base = getcwd();

$cachePath = __DIR__.'/cache';
$resolveUri = \Typesetsh\UriResolver::all($cachePath, $base);

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

Note that the URI resolver receives a base path and cache path.

The base path is used to resolve relative URIs. For example, in the above example, ./my-logo.png would be resolved to the path of the current working directory.

The cache path is used for HTTP(S) or data URIs. When an external HTTP(S) resource is used, the URI resolver will attempt to download and cache the resource to prevent the need for repeated downloads. If no cache path is provided (null), the URI resolver will try to use the system's default temporary file system as the cache path.

The example above uses the "all()" preset, which allows all paths to be included. Other presets include:

// Only http(s) urls are allowed, no loca files.
\Typesetsh\UriResolver::httpOnly($cachePath);

// http(s) and the current working dir of you application.
\Typesetsh\UriResolver::httpAndCurrentDir($cachePath, $base);

// Local files only within the list of given allowed directories 
\Typesetsh\UriResolver::localOnly($allowedDirectories, $base);

You can create your own presets to further restrict access or even implement your own resolveUri method. To do this, your function must have the following signature: function(string $uri, string $base): string

$base = __DIR__.'/public_html';
$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:./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');

Using typeset.sh

Now that you understand the concept of the $resolveUri method, let's take a quick look at how to render a PDF.

The easiest way is to use the \Typesetsh\createPdf method, which returns a \Typesetsh\Result object. This object allows you to save the PDF to a file or retrieve it as a binary string, specify the version to save the document as, get the number of pages that were created, and retrieve a list of warnings.

$pdf = \Typesetsh\createPdf("Hello World", $resolveUri);

// The version of the PDF file (default 1.6)
$pdf->version = '1.6';

// [Readonly] Number of pages that have been created.
$pdf->pageCount;

// [Readonly] List of \RuntimeException that raised durring rendering.
$pdf->issues;

// Write PDF to a file
$pdf->toFile('test.pdf');

// Return PDF as string
$data = $pdf->asString();

To display a PDF in the browser without saving it, you can use the asString() method and set the appropriate headers.

$data = $pdf->asString();
header('Content-Type: application/pdf');
header('Content-Length: ' . strlen($data));
header("Content-Disposition:inline;filename=hello.pdf");

echo $data;