Pdf Bundle Laravel Package

Getting Started

Install (be aware of age):

composer require ticketpark/pdf-bundle

This package was last released in April 2015 and targets Symfony 2.x / PHP 5.x. On a modern Symfony app you will almost certainly need --ignore-platform-reqs or a fork. If you're on Symfony 2.8 LTS it is the intended fit; on Symfony 3/4 it usually needs patching for the DI definition and service config format.

Register the bundle in app/AppKernel.php:

new Ticketpark\PdfBundle\TicketparkPdfBundle(),

Configure your DocRaptor API key in app/config/config.yml:

ticketpark_pdf:
    api_key: "%docraptor_api_key%"

Keep the key in parameters.yml (or, better, an env var) and never commit it — it is a paid, metered API credential.

First use case — render a Twig template to HTML, then hand it to the service:

$html = $this->renderView('AcmeBundle:Invoice:invoice.html.twig', ['invoice' => $invoice]);
$pdf  = $this->get('ticketpark_pdf')->getPdf($html);

return new Response($pdf, 200, [
    'Content-Type'        => 'application/pdf',
    'Content-Disposition' => 'attachment; filename="invoice.pdf"',
]);

Where to look first: open Ticketpark\PdfBundle\Service\PdfService and its getPdf() signature. That is the whole surface area of this bundle — it is a thin wrapper over the DocRaptor HTTP API (Prince XML under the hood). Everything else you need to know lives in DocRaptor's own option documentation, not in the bundle.

Implementation Patterns

Twig → HTML → PDF is the canonical flow. Do not build HTML strings in PHP; the bundle only accepts a string of HTML, so render a Twig template first. This keeps layouts and CSS in the normal Symfony asset pipeline.

Passing options through. getPdf($html, array $options = []) forwards options to DocRaptor. The ones you will use daily:

$pdf = $this->get('ticketpark_pdf')->getPdf($html, [
    'test'          => $this->getParameter('kernel.debug'), // dev/test runs
    'name'          => 'invoice-'.$invoice->getId(),
    'document_type' => 'pdf',
    'javascript'    => true,   // enable if the HTML relies on JS to lay out
    'tag'           => 'invoices', // billable-usage grouping
]);

Resolving relative assets. Prince/DocRaptor fetch CSS, images, and fonts over HTTP. Relative URLs in your HTML will not resolve. Either absolutise them in Twig ({{ absolute_url(asset('css/invoice.css')) }}, {{ app.request.schemeAndHttpHost }}) or set a base URL via Prince options:

$options = [
    'prince_options' => [
        'baseurl'  => $this->getParameter('assets_base_url'),
        'media'    => 'print',
    ],
];

Stream vs. download. Same bytes either way; choose headers. For email attachments or storage, take the returned string and file_put_contents() / attach it with SwiftMailer's Swift_Attachment::fromPath() or new \Swift_Attachment($pdf, 'x.pdf', 'application/pdf').

Inject, don't fetch from the container. In services:

public function __construct(PdfService $pdf) { $this->pdf = $pdf; }

The service id is ticketpark_pdf. This makes mocking trivial in tests.

Use test => true in functional tests. DocRaptor test documents return a watermarked PDF and are free — essential when you have any CI coverage of the PDF endpoint, otherwise every test run spends real credits.

Cache aggressively. The API is network-bound and slow (often 1–5s for complex pages). Persist the resulting PDF to a filesystem/key-value store keyed on the document hash or entity version, and only regenerate on change. This is the single biggest quality-of-life improvement for this bundle.

Wrap it in your own domain service. Expose InvoicePdfGenerator::generate(Invoice $invoice): string around ticketpark_pdf. That isolates the 2015-era dependency so a future swap (Dompdf, WeasyPrint, wkhtmltopdf, or the official docraptor/docraptor SDK) is a one-file change.

Gotchas and Tips

This bundle is effectively abandoned. Last release April 2015, zero stars, zero dependents. Assume no security patches, no Symfony 4+ compatibility, no DocRaptor API updates. If you're picking it today, evaluate the official docraptor/docraptor PHP client instead — it does the same thing with the same options and is maintained. Use this bundle only on legacy Symfony 2 codebases you cannot move.

DocRaptor is a paid, external service. No account → it fails. Test documents are watermarked, so you cannot ship test-mode output. Budget for credits; use tag so you can attribute usage.

javascript => true is required for any HTML that relies on client-side rendering. Prince XML does not run a full browser — no flex/grid quirks, limited JS, and some modern CSS is unsupported. Print-oriented CSS (@page, page-break-inside, @media print) is where it shines.

Relative paths silently produce unstyled PDFs. There is no error — you just get a PDF with missing images or default fonts. If a generated PDF looks wrong, first check asset URLs in the HTML that reaches getPdf().

Errors arrive as exceptions, not status codes. The wrapper throws on non-200 DocRaptor responses. Catch around the call and log the response body — DocRaptor returns useful validation messages (e.g., invalid document_type, missing API key, over-quota) that the exception may or may not surface depending on the client version. A single wrapper that catches, logs, and re-throws a domain exception pays off fast.

Timeouts. Long or JS-heavy documents can exceed the HTTP timeout. For large invoices/reports, generate asynchronously into a queue and store to disk rather than blocking a web request.

API key handling. The config key is ticketpark_pdf.api_key. It ends up in the compiled container — avoid %parameter% interpolation of a secret into files that get committed. Prefer env-provided values (Symfony's parameters.yml or an env var in the container).

Extension point to know: the wrapper is intentionally thin. If you need options DocRaptor exposes that the bundle doesn't forward (async submission, prince_options keys, strict, referrer), pass them in the options array — the bundle forwards the array through, so most DocRaptor features are reachable without patching, as long as the underlying client doesn't filter keys.

Debugging recipe: dump the exact HTML string to a file, open it in a browser to confirm layout, then confirm all assets are absolute URLs, then run the generator. That eliminates 90% of "it renders wrong" reports without burning API calls.