Download the PHP package tobento/app-pdf without Composer

App PDF

PDF support for the application, built on top of the PDF Service.

Table of Contents

• Getting Started
  • Requirements
• Documentation
  • App
  • PDF Boot
    • PDF Config
    • Basic Usage
    • Using PDF Handler
      • Storing
      • Downloading
      • Webhook
      • Queueing
• Credits

  ---

Getting Started

Add the latest version of the app pdf project running this command.

Requirements

• PHP 8.4 or greater

Documentation

App

Check out the App Skeleton if you are using the skeleton.

You may also check out the App to learn more about the app in general.

PDF Boot

The Pdf boot integrates the Tobento PDF Service into your application and registers all PDF-related handlers. It provides:

• loading of the pdf.php configuration
• binding of all App-PDF interfaces
• binding of all Service-PDF interfaces
• automatic setup of PDF generators, renderers, and handlers

PDF Config

The configuration for the pdf is located in the file at the default App Skeleton config location where you can specify the pdf generators for your application.

Basic Usage

If you're new to working with PDFs in Tobento, start with the
Basic Usage section of the PDF Service.
It explains how to create PDF definitions using views, HTML, or raw content, and provides the foundation for how App-PDF builds on top of the underlying service.

Using PDF Handler

The PDF handler coordinates everything that happens after you define a PDF.
By attaching parameters to the Pdf object, you can instruct the handler to:

• store the rendered PDF
• trigger a file download
• send the PDF to a webhook
• queue the PDF for asynchronous processing

These parameters can be used individually or combined.
When queueing is enabled, the handler prepares a queue job and then executes only the immediate actions (such as download).
All deferred actions - like storing the PDF or sending it to a webhook - are performed later inside the queue job.
The PDF is rendered only once, even when multiple actions are defined.

The Pdf object offers a fluent API, allowing you to define content and attach parameters in a clean and expressive way.

Example

The example below shows how to define a PDF, attach multiple parameters, and let the handler orchestrate the workflow:

Storing

The store() parameter instructs the handler to save the rendered PDF to a specific storage and path.
If queueing is enabled, storing is not performed during the request. Instead, it is executed later inside the queue job.

This feature is powered by the application's app-file-storage system, which provides unified storage handling, directory creation, and driver-based file operations.

The storage name must refer to a configured storage in your application
(for example via your file storage configuration).
The path may include folders and will be created automatically if supported by the storage driver.

Events

When storing is used, the following events may be dispatched:

• PdfGenerated
  Fired before the PDF is written to storage. Useful for logging, validation, or modifying metadata.

• PdfStored
  Fired after the PDF has been successfully written to storage. Useful for notifications, indexing, or triggering follow‑up processes.

• PdfQueued
  Fired when the PDF has been queued for later processing. Useful for monitoring background jobs or triggering follow-up actions.

These events allow you to hook into the storage lifecycle and extend the behavior as needed.

Downloading

The download() parameter instructs the handler to emit the rendered PDF as an HTTP response.
Downloading is always an immediate action and is executed during the request, even when queueing is enabled.

When a download parameter is present, the download handler:

• creates a PDF stream from the generated content
• builds a PSR-7 response with Content-Type: application/pdf
• sets the Content-Disposition header as either attachment or inline based on the inline flag
• applies any custom headers defined on the parameter
• emits the response using the configured SimpleResponseEmitterInterface
• throws a PdfException if the response cannot be emitted

If inline is set to true, the PDF is displayed in the browser (if supported); otherwise, the browser will treat it as a file download.

Events

When downloading is used, the following events may be dispatched:

• PdfGenerated
  Fired after the PDF has been rendered and before it is emitted as an HTTP response. Useful for logging or modifying metadata.

• PdfDownloaded
  Fired after the PDF has been successfully emitted as a response. Useful for auditing, monitoring, or triggering follow-up processes.

These events allow you to hook into the download lifecycle and extend the behavior as needed.

Webhook

The webhook() parameter instructs the handler to send the generated PDF to a remote endpoint.
Webhook delivery is always an immediate action and is executed during the request, even when queueing is enabled.

When a webhook parameter is present, the webhook handler:

• sends a POST request to the configured endpoint
• builds a JSON payload from the provided data
• attaches the generated PDF as a Base64‑encoded string if attachPdf is enabled
• applies any custom headers
• throws a PdfException if the endpoint responds with an error

If the remote endpoint responds with an error or cannot be reached, a PdfException may be thrown depending on your configuration.

Example Webhook Payload

When a webhook is configured, the handler sends a JSON payload to the specified endpoint.

If attachPdf is true (default), the generated PDF is included as a Base64‑encoded string:

Notes

• The PDF is always Base64‑encoded when attached.
• Any array passed as $payload is merged directly into the JSON body.
• If the endpoint returns an HTTP status ≥ 400, a PdfException is thrown.

Events

When a webhook is used, the following events may be dispatched:

• PdfGenerated
  Fired after the PDF has been rendered and before the webhook request is sent. Useful for logging, validation, or modifying metadata.

• PdfWebhookSent
  Fired after the webhook has been successfully delivered. Useful for auditing, monitoring, or triggering follow-up processes.

These events allow you to hook into the webhook lifecycle and extend the behavior as needed.

Queueing

Queueing allows PDF generation and its associated actions (such as storing or sending a webhook)
to be executed asynchronously in a background worker instead of during the HTTP request.

This is useful when generating large PDFs or when performing slow operations such as storage or webhook delivery.

This feature is powered by the application's app-queue system, which handles job dispatching, retry logic, delays, and worker execution.

When queueing is enabled:

• the PDF is not generated during the request
• the job is pushed onto the configured queue
• a worker later generates the PDF in the background
• any additional actions (store, webhook, etc.) are executed inside the queued job
• the HTTP response remains fast and unaffected by PDF processing time

Queueing does not change the behavior of the individual handlers - it only defers their execution.

Example Workflow

If you combine queueing with storing and a webhook:

The worker will:

• generate the PDF
• store it
• send the webhook
• dispatch the corresponding events

All outside the original HTTP request.

Events

When queueing is used, the following events may be dispatched:

• PdfQueued
  Fired when the PDF job has been successfully pushed onto the queue. Useful for monitoring background processing or triggering follow-up actions.

• PdfGenerated
  Fired inside the queue worker after the PDF has been rendered. Useful for logging, validation, or modifying metadata before any actions are executed.

• PdfStored
  Fired after the PDF has been successfully written to storage by the queue worker. Useful for notifications, indexing, or triggering follow-up processes.

• PdfWebhookSent
  Fired after the webhook has been successfully delivered by the queue worker. Useful for auditing, monitoring, or chaining external processes.

These events allow you to hook into the queue lifecycle and extend the behavior as needed.

Credits

• Tobias Strub
• All Contributors