Renderizar HTML árabe da direita para a esquerda

Visão geral

Renderize HTML da direita para a esquerda (RTL) em PDF com writeHtml(). Defina a propriedade CSS direction: rtl e registre uma fonte com suporte a árabe. O motor reordena o texto para a ordem visual com o Algoritmo Bidirecional Unicode (UAX #9) e molda as letras árabes em formas contextuais. Esta receita renderiza uma pequena fatura em árabe. RTL é usado em árabe, hebraico, persa e urdu. O hebraico é reordenado, mas não moldado, o que é correto para essa escrita.

Instalação

composer require nextpdf/core

Você também precisa de uma fonte TrueType ou OpenType com suporte a árabe. O mapa de caracteres dela deve cobrir o bloco Arabic Presentation Forms-B. Noto Naskh Arabic e Amiri são fontes adequadas com licença aberta.

Visão geral conceitual

Você precisa de dois elementos para a renderização RTL: a propriedade CSS direction: rtl e uma fonte árabe registrada.

direction: rtl indica ao layout que posicione o texto da direita para a esquerda. O motor então usa o Algoritmo Bidirecional Unicode (UAX #9) para resolver a ordem visual. Conteúdo misto é ordenado corretamente: palavras em latim, palavras em árabe e dígitos preservam suas próprias direções. Um número que segue texto em árabe mantém os dígitos da esquerda para a direita.

O árabe é uma escrita cursiva, portanto cada letra usa um glifo diferente conforme seus vizinhos. O motor seleciona a forma inicial, medial, final ou isolada de cada letra e aplica a ligadura Lam-Alef. Essa moldagem contextual precisa de uma fonte cujo mapa de caracteres cubra o bloco Arabic Presentation Forms-B. Uma fonte apenas latina, incluindo as fontes standard-14, não consegue renderizar árabe.

Em uma tabela, cada célula é reordenada e moldada de forma independente, e as células se alinham à borda inicial: a borda direita sob direction: rtl. Os valores lógicos de text-align start e end são resolvidos em relação à direção; portanto, start mapeia para a borda direita em conteúdo RTL.

Defina a direção com a propriedade CSS direction. O atributo HTML dir não é mapeado para ela. Consulte RTL — limitações atuais para conhecer os limites atuais da implementação.

Superfície da API

Símbolo	Localização	Função
Document::writeHtml(string $html): static	NextPDF\Core\Concerns\HasTextOutput	Renderiza o fragmento HTML na posição atual do cursor.
FontRegistry::register(string $fontFile, string $alias = '', int $fontIndex = 0): FontInfo	NextPDF\Typography\FontRegistry	Registra a fonte árabe sob um alias.
DocumentFactory::create(): Document	NextPDF\Core\DocumentFactory	Cria um documento que lê seu registro preenchido.

O exemplo usa estas propriedades CSS: direction, font-family, text-align. Referencie a fonte registrada no CSS font-family pelo alias de registro.

Exemplo de código — Início rápido

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

O título é renderizado da direita para a esquerda, e os dígitos 380.00 permanecem da esquerda para a direita dentro da frase em árabe.

Exemplo de código — Produção

Este exemplo autossuficiente renderiza uma tabela de fatura em árabe. Cada célula define direction: rtl e a fonte árabe registrada; com isso, o motor reordena e molda cada linha e, em seguida, alinha as células à borda direita.

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