Release notes — 3.0
BestPDF 3.0 is a complete rewrite. This page covers what changed, what it means for an existing 2.x installation, and how to bring your old layout across. For the step-by-step procedure, see Upgrade; for the running list of fixes and smaller changes, see the Changelog.
What's new in 3.0
A visual designer instead of a settings screen. v2 was configured through a long series of forms — 266 settings in total, each controlling one measurement, colour or toggle. 3.0 replaces them with a drag-and-drop editor: you place components on a page, arrange them in the content flow or as overlays, and see what you are building.
Named designs instead of one global configuration. v2 had exactly one invoice layout and one quote layout, and changing them meant editing the live thing. 3.0 keeps as many designs as you like, with one active for invoices and one for quotes, so you can build a replacement alongside the one your customers are receiving and switch when it's ready. Designs export and import as portable bundles.
Reusable styles. Colours, typography and table styling are defined once, by name, in the design's style palette and referenced everywhere. Changing a brand colour is one edit rather than a search through dozens of fields.
Twig instead of Smarty. Text on the document is rendered with the full Twig template engine — filters, conditionals and loops — in a sandbox.
Breaking changes
Your layout migration needs to be triggered manually
The moment the new files are in place and the upgrade has run, your invoices are drawn by a bundled default design, not by your v2 layout.
Getting your layout back is a deliberate step you take afterwards — see Importing your v2 configuration below. Between the two, customers who download an invoice get a correct but differently styled document.
Plan accordingly: upgrade at a quiet time, or rehearse on a staging copy first.
We recommend putting WHMCS in maintenance mode during the upgrade
Upgrade Pingen Post and Billing Booster before BestPDF
If you also use Billing Booster, make sure to upgrade to version 2 first. BestPDF v3 does not support Billing Booster version 1. The order matters: the v2 conversion reads your configured payment codes out of Billing Booster and ensures your layout gets migrated smoothly.
Likewise, if you use Pingen, make sure to upgrade to version 7 first. BestPDF v3 does not support previous versions of Pingen.
The SwissQR and SEPA QR modules are not supported
BestPDF v2 could take its payment slip from the standalone BlueRabbIT SwissQR and SEPA QR addons. BestPDF 3.0 no longer supports those modules.
Their direct replacement is Billing Booster 2.0, which covers both standards in a single module, and is what the Payment Code component reads its configured codes from. If you are still running SwissQR or SEPA QR, move to Billing Booster 2.0 first: that is the "upgrade Billing Booster before BestPDF" step above, and skipping it means the v2 conversion finds no payment codes to build components from.
Preview thumbnails need the Imagick PHP extension
v2 shelled out to an external binary to rasterise a PDF page, and let you pick which one: ImageMagick, GraphicsMagick or Poppler.
3.0 generates previews in-process through the imagick PHP extension, and support for GraphicsMagick and Poppler is dropped along with the setting that chose between them. imagick is no longer optional — it is a requirement, and BestPDF names it on the addon's page and in the log if it is missing.
Servers whose ImageMagick policy blocks PDF rasterisation need that policy relaxed; see Troubleshooting.
Twig replaces Smarty in every text field
v2 ran its text through Smarty. 3.0 renders it with Twig, and no Smarty is executed anywhere — so every piece of text you wrote yourself is affected, not just the ones with merge fields in them.
The v2 conversion rewrites what it can, and the renderer is forgiving about the rest: plain placeholders in the old {$invoice_num} or {invoice_num} form are still understood and converted on the fly. Anything beyond a plain placeholder — Smarty control blocks and modifiers, or a v2 field with no 3.0 counterpart — may not come across intact. Those are left visible in the text and named in the conversion report rather than silently dropped, precisely so you can find them.
So treat the converted text as needing review. Open each migrated design, preview an invoice and a quote, and read the text components. A template Twig can't parse doesn't break the render — the field prints unrendered — which means raw {{ ... }} or { ... } in the preview is your list of things to rewrite before a customer sees them. Merge fields & Twig syntax lists the fields, tags and filters BestPDF exposes; the official Twig documentation covers the language itself.
Border widths are now stated in millimetres
v2's border thickness field was labelled "px" but the engine wrote it into CSS as 0.{value}pt, so a "1" was really a tenth of a point. 3.0 states border widths in millimetres like every other measurement on a design, and the conversion converts rather than copies: v2's 1 becomes 0.035mm, which strokes identically.
If you had hand-tuned border thicknesses, the numbers you see after conversion will look nothing like the ones you typed. The lines on the page are the same.
Importing your v2 configuration
It is not part of the upgrade
The upgrade itself carries across only the handful of install-wide settings that have a direct 3.0 equivalent — error handling, date format mode, and the four invoice/quote admin-notification and auto-fix toggles. It writes no designs.
Rebuilding a 266-setting layout as a design means approximating in places, and some v2 merge fields have no 3.0 equivalent at all. That is worth doing with someone at the keyboard to read the result, which is why it runs on request rather than silently during an upgrade.
Running it
An install that still has a v2 configuration and has never converted it gets a banner on the Designs tab offering the import. Running it creates two designs, Invoice (migrated) and Quote (migrated).
It only ever writes designs — never settings, never your existing designs — so it is safe to re-run. Re-run it after installing Billing Booster, or after a first attempt you weren't happy with; you'll get another pair of designs and can delete the ones you don't want.
Your v2 configuration is never deleted, so nothing about this is one-way.
What it carries, and what it tells you
Everything that has a home in a 3.0 design: margins and page geometry, the address block, the details box, the status badge, item and transaction and summary tables with their colours and fonts, the addendum, logos and stationery PDFs, and your text blocks.
Two things are reported rather than silently handled:
- Text that was Smarty. v2's text fields are rewritten to Twig automatically. A v2 merge field with no 3.0 equivalent is left visible in the text and named in the report, so you can see exactly what needs rewording rather than discovering a blank space on a customer's invoice.
- Custom fonts whose file is missing. Fonts you uploaded in v2 are carried over from the v2's data directory. If the font can't be found in the v2 data directory anymore, it can't be migrated, and every typography style pointing at it quietly falls back to the base font. That is logged as a warning rather than passed over.
Both end up in the log as well as in the report on screen.
Activating the result
The import dialog carries a checkbox, Use them for my documents straight away, ticked by default. Leave it ticked and the imported designs become the active invoice and quote designs as soon as the run finishes, replacing the bundled defaults the upgrade put there — which is what you want if the point of the exercise was to get your own layout back.
Untick it if you would rather look first. The designs are still created; they just sit alongside your current ones until you activate them yourself from the Designs tab.
Either way, preview the result and work through whatever the report flagged before you consider the upgrade finished. If you activated on import, that preview is what your customers are already receiving.