Рендеринг арабского HTML с направлением справа налево

Коротко о главном

Этот рецепт показывает, как рендерить HTML с направлением справа налево (RTL) в PDF с помощью writeHtml(). Задайте CSS-свойство direction: rtl и зарегистрируйте шрифт с поддержкой арабского. Движок переупорядочивает текст в визуальный порядок по алгоритму двунаправленного письма Unicode (UAX #9) и формирует арабские буквы в контекстные формы. В рецепте рендерится небольшой счёт на арабском. RTL используется для арабского, иврита, персидского и урду. Иврит переупорядочивается без формирования, и для этого письма это корректно.

Установка

composer require nextpdf/core

Также нужен шрифт TrueType или OpenType с поддержкой арабского. Его таблица символов должна покрывать блок Arabic Presentation Forms-B. Noto Naskh Arabic и Amiri — подходящие шрифты с открытыми лицензиями.

Концептуальный обзор

Для рендеринга RTL нужны два условия: CSS-свойство direction: rtl и зарегистрированный арабский шрифт.

direction: rtl указывает механизму компоновки размещать текст справа налево. Затем движок использует алгоритм двунаправленного письма Unicode (UAX #9), чтобы определить визуальный порядок. Смешанное содержимое упорядочивается корректно: латинские слова, арабские слова и цифры сохраняют своё направление. Цифры в числе, следующем за арабским текстом, остаются слева направо.

Арабское письмо — связное, поэтому каждая буква использует разные глифы в зависимости от соседних букв. Движок выбирает для каждой буквы начальную, срединную, конечную или изолированную форму и применяет лигатуру Lam-Alef. Для такого контекстного формирования нужен шрифт, чья таблица символов покрывает блок Arabic Presentation Forms-B. Шрифт, содержащий только латиницу, включая шрифты из стандартных 14, не может отрисовать арабский текст.

В таблице каждая ячейка переупорядочивается и формируется самостоятельно, а затем выравнивается по начальному краю: под direction: rtl это правый край. Логические значения text-align start и end интерпретируются относительно направления, поэтому start сопоставляется с правым краем для содержимого RTL.

Задавайте направление через CSS-свойство direction. HTML-атрибут dir не преобразуется в это свойство. См. RTL — текущие ограничения для текущих границ реализации.

Поверхность API

Символ	Расположение	Роль
Document::writeHtml(string $html): static	NextPDF\Core\Concerns\HasTextOutput	Рендерит фрагмент HTML в текущей позиции курсора.
FontRegistry::register(string $fontFile, string $alias = '', int $fontIndex = 0): FontInfo	NextPDF\Typography\FontRegistry	Регистрирует арабский шрифт под псевдонимом.
DocumentFactory::create(): Document	NextPDF\Core\DocumentFactory	Создаёт документ, использующий заполненный вами реестр.

В примере используются эти CSS-свойства: direction, font-family, text-align. В CSS font-family обращайтесь к зарегистрированному шрифту по его псевдониму в реестре.

Пример кода — Быстрый старт

<?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');

Заголовок рендерится справа налево, а цифры 380.00 остаются слева направо внутри арабского предложения.

Пример кода — Производственный

Этот самодостаточный пример рендерит таблицу счёта на арабском. В каждой ячейке заданы direction: rtl и зарегистрированный арабский шрифт, поэтому движок переупорядочивает и формирует текст в каждой ячейке, а затем выравнивает ячейки по правому краю.

<?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";">