Invoice PDF — overview

The gap, in one measurement#

dompdf does 8.4 million installs a month and barryvdh/laravel-dompdf does 5.7 million. Neither can join a single Arabic letter.

Arabic is cursive: a letter's shape depends on its neighbours, and Unicode stores the letter once and leaves the choosing to the renderer. dompdf does not choose. It draws the isolated form of every glyph in the order given, left to right. The result contains every character of the invoice and cannot be read.

What exists to fix that, on Packagist, in full:

Against 5.7 million a month for the engine that causes it. The usual answers are to take on mPDF — forty megabytes — or to install Chrome on the server.

What is actually in here#

An Arabic shaper in pure PHP. Every letter's four presentation forms from the Unicode Arabic Presentation Forms-B block; the six letters that never join forwards, which is why دار is three separate shapes; the lam-alef ligature that لا always is and whose absence is the single most visible failure in the field; vowels and shadda carried along without breaking a join; and Urdu's پ چ ٹ ڈ ڑ گ ک ہ ے.

A reordering pass. Right-to-left runs turned around, numbers and Latin words left running the right way inside them, brackets mirrored, per line.

An invoice that knows what a tax authority asks for. problems() returns reason codes rather than a boolean, per jurisdiction. The UAE's Federal Decree-Law No. 8 of 2017, Article 59 — including the exchange rate that an invoice not in dirhams must show, which is forgotten constantly. ZATCA's requirement that the seller be named in Arabic. The distinction between a standard invoice, which must name the customer, and a simplified one, which need not.

Whole minor units. The same rules as Devix VAT Calculator, so the total in the browser and the total on the page are the same number. Tax rates in basis points, because 5% is 500 and not 0.05000000000000000277. Tax summed per line, which is what both authorities specify and which is not the same as taxing the total.

One thing found by looking#

The first rendered page was correct Arabic in the wrong order: the table columns ran description-first from the left, because dompdf lays columns out in source order whatever dir="rtl" says. So an Arabic invoice is emitted with its columns already reversed. That is not in any specification; it came from looking at the page.

What we do not claim#

A full UAX #9. The bidirectional handling here covers right-to-left runs with embedded numbers and Latin, mirrored brackets, and per-line direction. Not explicit embedding characters or nested overrides — an invoice has none, and a word processor would.

Copyable text. Shaping writes presentation forms into the PDF, so copying out of a reader gives shaped characters. Every PHP Arabic invoice makes that trade. Shaper::toPlain() reverses it exactly, and a test proves the round trip.

That mPDF is wrong. If forty megabytes is acceptable, mPDF shapes at the font layer and keeps the text copyable. This is for the far more common case where dompdf is already there and the invoice has to go out in Arabic tomorrow.