Render right-to-left Arabic HTML

At a glance

Render right-to-left (RTL) HTML to PDF with writeHtml(). Set the CSS direction: rtl property and register an Arabic-capable font. The engine reorders text to visual order with the Unicode Bidirectional Algorithm (UAX #9) and shapes Arabic letters into contextual forms. This recipe renders a small Arabic invoice. RTL applies to Arabic, Hebrew, Persian, and Urdu. Hebrew is reordered but not shaped, which is correct for that script.

Install

composer require nextpdf/core

You also need an Arabic-capable TrueType or OpenType font. Its character map must cover the Arabic Presentation Forms-B block. Noto Naskh Arabic and Amiri are suitable open-licensed faces.

Conceptual overview

You need two inputs for RTL rendering: the CSS direction: rtl property and a registered Arabic font.

direction: rtl tells the layout to place text from right to left. The engine then uses the Unicode Bidirectional Algorithm (UAX #9) to resolve visual order. Mixed content orders correctly: Latin words, Arabic words, and digits each keep their own direction. A number that follows Arabic text keeps its digits left to right.

Arabic is a cursive script, so each letter uses a different glyph based on its neighbors. The engine selects the initial, medial, final, or isolated form for each letter and applies the Lam-Alef ligature. This contextual shaping needs a font whose character map covers the Arabic Presentation Forms-B block. A Latin-only font, including the standard-14 faces, cannot draw Arabic.

In a table, each cell is reordered and shaped on its own, and cells align to the start edge: the right edge under direction: rtl. The logical text-align values start and end resolve against the direction, so start maps to the right edge for RTL content.

Set direction with the CSS direction property. The HTML dir attribute does not map to it. See RTL — current limitations for the current implementation boundaries.

API surface

Symbol	Location	Role
Document::writeHtml(string $html): static	NextPDF\Core\Concerns\HasTextOutput	Render the HTML fragment at the current cursor position.
FontRegistry::register(string $fontFile, string $alias = '', int $fontIndex = 0): FontInfo	NextPDF\Typography\FontRegistry	Register the Arabic face under an alias.
DocumentFactory::create(): Document	NextPDF\Core\DocumentFactory	Create a document that reads your populated registry.

The example uses these CSS properties: direction, font-family, text-align. Reference the registered font in CSS font-family by its registry alias.

Code sample — Quick start

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\DocumentFactory;
use NextPDF\Graphics\ImageRegistry;
use NextPDF\Typography\FontRegistry;

$fontRegistry = new FontRegistry();
$fontRegistry->register(__DIR__ . '/NotoNaskhArabic-Regular.ttf', alias: 'ArabicFont');

$documentFactory = new DocumentFactory($fontRegistry, new ImageRegistry(maxCacheBytes: 0));
$doc = $documentFactory->create();
$doc->addPage();

$doc->writeHtml(
    '<div style="direction: rtl; font-family: \'ArabicFont\';">'
    . '<h1>فاتورة</h1>'
    . '<p>المبلغ الإجمالي 380.00</p>'
    . '</div>'
);

$doc->save(__DIR__ . '/rtl-arabic.pdf');

The heading renders right to left, and the digits 380.00 stay left to right inside the Arabic sentence.

Code sample — Production

This self-contained example renders an Arabic invoice table. Each cell carries direction: rtl and the registered Arabic font, so the engine reorders and shapes every line, then aligns the cells to the right edge.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\DocumentFactory;
use NextPDF\Graphics\ImageRegistry;
use NextPDF\Typography\FontRegistry;

// Supply an Arabic-capable face whose cmap covers Arabic Presentation Forms-B.
// Embed only fonts you are licensed to embed.
$fontPath = __DIR__ . '/NotoNaskhArabic-Regular.ttf';
if (!is_file($fontPath)) {
    fwrite(STDERR, "Arabic font not found at {$fontPath}\n");
    exit(1);
}

$fontRegistry = new FontRegistry();
$fontRegistry->register($fontPath, alias: 'ArabicFont');

$documentFactory = new DocumentFactory($fontRegistry, new ImageRegistry(maxCacheBytes: 0));
$doc = $documentFactory->create();
$doc->setTitle('Arabic invoice');
$doc->addPage();

$html = <<<'HTML'
<div style="direction: rtl; font-family: 'ArabicFont'; font-size: 12pt;">
  <h1>فاتورة</h1>
  <table style="width: 100%; border-collapse: collapse;">
    <tr>
      <th style="border: 1px solid #333; padding: 6px;">الوصف</th>
      <th style="border: 1px solid #333; padding: 6px;">المبلغ</th>
    </tr>
    <tr>
      <td style="border: 1px solid #333; padding: 6px;">خدمات استشارية</td>
      <td style="border: 1px solid #333; padding: 6px;">380.00</td>
    </tr>
    <tr>
      <td style="border: 1px solid #333; padding: 6px;">الإجمالي</td>
      <td style="border: 1px solid #333; padding: 6px;">380.00</td>
    </tr>
  </table>
</div>
HTML;

$doc->writeHtml($html);

$out = getenv('NEXTPDF_OUT');
$doc->save($out !== false ? $out : __DIR__ . '/render-rtl-arabic-html.pdf');

echo "Wrote the Arabic invoice PDF\n";

  الوصف المبلغ   خدمات استشارية 380.00   الإجمالي 380.00  

HTML;$doc->writeHtml($html);$out = getenv('NEXTPDF_OUT');$doc->save($out !== false ? $out : __DIR__ . '/render-rtl-arabic-html.pdf');echo "Wrote the Arabic invoice PDF\n";">