الترحيل من ⁨FPDF⁩ إلى ⁨NextPDF⁩

لمحة سريعة

يساعدك هذا الدليل على نقل شيفرةٍ مبنيّةٍ على F⁨PDF⁩ إلى نواة ⁨NextPDF⁩. و⁨FPDF⁩ من أكثر مكتبات صيغة المستند المحمول (‏⁨PDF⁩) القديمة بلغة ⁨PHP⁩ انتشارًا، وسطح رسمه — ‏AddPage وSetFont وCell وMultiCell وWrite وText وImage وOutput مدفوعًا بمؤشّر x/y يدوي — يُعيَّن نظيفًا على واجهة الخلية/النصّ الخاصّة بـ⁨NextPDF⁩، لأنّ توابع الرسم منخفضة المستوى في ⁨NextPDF⁩ تتبع نسب ⁨FPDF⁩/⁨TCPDF⁩ نفسه. و⁨NextPDF⁩ ليس نسخة ⁨FPDF⁩ تُدرَج كبديلٍ مباشر، مع ذلك: فهو محرّك ⁨PDF 2.0⁩ حديث بأنواعٍ صارمة، وتقسيم الخطوط إلى مجموعاتٍ فرعية، والتوقيع، و⁨PDF/A⁩، والوصولية (‏Tagged ⁨PDF⁩). والتحوّلان الحقيقيّان هما نموذج الوحدة (يعمل ⁨NextPDF⁩ بنقاط ⁨PDF⁩؛ ويفترض ⁨FPDF⁩ المليمترات) وأفعال الإخراج (تعداد ‏OutputDestination مُحدَّد النوع بدلًا من محارف ⁨FPDF⁩ ‏'I'/'D'/'F'/'S').

لا يوجد بديلُ صنف FPDF في النواة. أعد كتابة كلّ موضع استدعاءٍ مستخدمًا مخطّط الأفعال. وإن أردت أصغر تغييرٍ أوّلي لشيفرة ⁨TCPDF 6.x⁩ بدلًا من ذلك، فانظر مُهيّئ التوافق مع ⁨TCPDF⁩، الذي يشحن مسار إدراجٍ بديلٍ شبه متوافقٍ مصدريًّا؛ ولا مُهيّئ كهذا لـ⁨FPDF⁩.

التثبيت

composer require nextpdf/core:^3

أبقِ setasign/fpdf (أو fpdf/fpdf لديك) مُثبَّتًا أثناء الترحيل. أزِله بعد التحويل النهائي (انظر تسلسل الترحيل الآمن).

نظرة مفاهيمية عامّة

يتشارك ⁨FPDF⁩ و⁨NextPDF⁩ النموذج الذهني نفسه: مستندٌ مكوَّنٌ من صفحات، ومؤشّر (موضع x/y الحالي)، وأفعالٌ ترسم عند ذلك المؤشّر أو تُقدّمه. ويقرأ SetXY وCell وLn وMultiCell كلّها المؤشّر وتغيّره في كلتا المكتبتين، فتُترجَم معظم شيفرة ⁨FPDF⁩ الإجرائية سطرًا بسطر.

الفروق متعمَّدة، لا عرضية:

• الوحدات. يفترض مُنشئ ⁨FPDF⁩ (‏new FPDF($orientation, $unit, $size)) المليمترات. ويعمل ⁨NextPDF⁩ بنقاط ⁨PDF⁩ (‏1 pt = 1/72 بوصة، ⁨ISO 32000-2⁩ §7). ولا مفتاح وحدةٍ على مستوى المستند — حوّل المليمترات إلى نقاطٍ مرّةً (‏pt = mm * 72 / 25.4).
• اتّجاه Y يبقى نفسه بالنسبة لك. كـ⁨FPDF⁩، تضع إحداثيات المستخدم في ⁨NextPDF⁩ y = 0 عند أعلى الصفحة وتزداد نزولًا، فيُنقَل حساب المؤشّر مباشرةً. ويحوّل ⁨NextPDF⁩ داخليًّا إلى أصل ⁨PDF⁩ الأصلي أسفل اليسار.
• الإنشاء صريح. يطوي ⁨FPDF⁩ الاتّجاه والوحدة والحجم في المُنشئ؛ ويأخذ ⁨NextPDF⁩ كائن القيمة غير القابل للتغيير NextPDF\Core\Config (حجم الصفحة، الهوامش، دليل الخطوط) وaddPage() صريحًا.
• دائمًا ⁨Unicode⁩، دائمًا مجموعةٌ فرعية. بناء ⁨FPDF⁩ الأساسي ⁨Latin-1⁩ ويحتاج متغيّر tF⁨PDF⁩/UTF-8 لـ⁨Unicode⁩. و⁨NextPDF⁩ ⁨UTF-8⁩ كلّه ودائمًا يضمّن الخطوط بوصفها برامج مجموعةٍ فرعية (‏⁨ISO 32000-2⁩ §9). ولا نظير لملفّات AddFont/متريّات خطوط ⁨FPDF⁩؛ سجّل دليل خطوط ⁨TrueType⁩/⁨OpenType⁩ واختر العائلة بالاسم.

سطح واجهة ⁨API⁩

نقاط الدخول الأساسية المستخدَمة أدناه هي Document::createStandalone()، وDocument::addPage()، وDocument::setFont()، وDocument::cell()، وDocument::multiCell()، وDocument::text()، وDocument::write()، وDocument::ln()، وDocument::image()، ومُوصِّلات المؤشّر (setXY/setX/ setY/getX/getY)، وDocument::output(?string, OutputDestination)، وDocument::save(string $path): void، وDocument::getPdfData(): string، وكائن القيمة NextPDF\Core\Config. والمرجع الكامل لتوابع الرسم والنصّ والإخراج الأساسية هذه يعيش في الوحدات الأساسية وفهرس المرجع، مولَّدًا تلقائيًّا من ⁨PHPDoc⁩. ووحدة Html قراءةٌ ذات صلة لتحويل ⁨HTML⁩ إلى ⁨PDF⁩، لا المرجع لأفعال هذه الصفحة.

مخطّط أفعال واجهة ⁨API⁩

أسماء توابع ⁨FPDF⁩ العامة عريقةٌ ومعروفةٌ جيّدًا. وعمود ⁨NextPDF⁩ أدناه مُؤكَّدٌ على توقيعات مصدر النواة (انظر الأدلّة / إمكانية التتبّع).

FPDF	NextPDF	ملاحظات
new FPDF($orient, $unit, $size)	Document::createStandalone($config)	تصير وسائط مُنشئ الاتّجاه/الوحدة/الحجم NextPDF\Core\Config (pageSize، margins، fontsDirectory). لا $unit — اعمل بالنقاط. صفحة createStandalone() الافتراضية A4 عمودية.
$pdf->AddPage($orient, $size)	$doc->addPage($size, $orientation)	تعيين مباشر. $size كائن قيمة PageSize؛ و$orientation تعداد Orientation (Portrait/Landscape).
$pdf->SetFont($family, $style, $size)	$doc->setFont($family, $style, $size)	تعيين مباشر. يستخدم $style رموز ''/'B'/'I'/'BI' نفسها (زائد 'U' للتسطير).
$pdf->Cell($w, $h, $txt, $border, $ln, $align, $fill)	$doc->cell($w, $h, $txt, $border, $newLine, $align, $fill)	تعيين مباشر. $align تعداد Alignment (Left/Center/Right/Justify)؛ و$border يقبل bool أو سلسلة 'LTRB'؛ و$ln يصير bool $newLine.
$pdf->MultiCell($w, $h, $txt, $border, $align, $fill)	$doc->multiCell($w, $h, $txt, $border, $align)	يلفّ الكلمات على متريّات الخطّ الفعلية. لا وسيطة $fill؛ ارسم rect() مملوءًا أوّلًا إن احتجت خلفية.
$pdf->Write($h, $txt, $link)	$doc->write($h, $txt, $link)	نصٌّ متدفّق من المؤشّر؛ و$link يُرفِق تعليق رابط ⁨URL⁩.
$pdf->Text($x, $y, $txt)	$doc->text($x, $y, $txt)	نصٌّ بموضعٍ مطلق. تعيين مباشر.
$pdf->Ln($h)	$doc->ln($h)	كسر سطرٍ إلى الهامش الأيسر؛ 0 = ارتفاع السطر الافتراضي.
$pdf->Image($file, $x, $y, $w, $h)	$doc->image($file, $x, $y, $w, $h)	تعيين مباشر؛ $x/$y/$w/$h قابلةٌ للقيمة الفارغة (null = المؤشّر الحالي / الحجم الذاتي).
$pdf->SetXY($x, $y) / SetX / SetY	$doc->setXY($x, $y) / setX / setY	تعيين مباشر. getX()/getY() يقرآن المؤشّر.
$pdf->SetMargins($l, $t, $r)	$doc->setMargins(new Margin($t, $r, $bottom, $l))	كائن قيمة Margin واحد؛ ترتيب المُنشئ (top, right, bottom, left) — ليس (left, top, right) كـ⁨FPDF⁩. ولـ⁨FPDF⁩ SetMargins لا وسيطة سفلية (هامشه السفلي من SetAutoPageBreak($auto, $margin))، فاختر $bottom بنفسك — عادةً مساويًا للهامش العلوي، أو مرّر هامش كسر الصفحة التلقائي.
$pdf->SetAutoPageBreak($auto, $margin)	$doc->setAutoPageBreak($auto, $margin)	تعيين مباشر.
$pdf->SetDrawColor / SetFillColor / SetTextColor	$doc->setDrawColor / setFillColor / setTextColor	RGB ‏(r, g, b)، أو قيمةٌ واحدة للتدرّج الرمادي.
$pdf->Line / Rect / SetLineWidth	$doc->line / rect / setLineWidth	تعيين مباشر. rect() يأخذ سلسلة نمطٍ ('S'/'F'/'DF').
$pdf->SetTitle/SetAuthor/SetSubject/SetKeywords/SetCreator	$doc->setTitle/setAuthor/setSubject/setKeywords/setCreator	تعيين مباشر. يَحُلّ في قاموس معلومات ⁨ISO 32000-2⁩ §14 / منصّة البيانات الوصفية القابلة للتوسيع (‏XMP).
$pdf->Output($dest, $name)	$doc->output($name, OutputDestination::…)	تُعيَّن محارف وجهة ⁨FPDF⁩ (I/D/F/S) على تعداد OutputDestination؛ لاحظ أنّ ترتيب الوسائط يتبدّل (الاسم أوّلًا في ⁨NextPDF⁩).
$pdf->Output('S')	$doc->getPdfData()	يُرجِع بايتات ⁨PDF⁩.
$pdf->Output('F', $path)	$doc->save($path)	يكتب إلى مسار ملفّ.
$pdf->GetStringWidth($s)	(no public method)	يُحسَب عرض السلسلة داخليًّا أثناء لفّ cell()/multiCell()؛ ولا فعلَ قياسٍ عامٌّ لكلّ سلسلة. أدِر اللفّ عبر multiCell() بدلًا من القياس يدويًّا.

عيّنة شيفرة — بداية سريعة

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;

// FPDF:
//   $pdf = new FPDF();           // mm, A4 portrait
//   $pdf->AddPage();
//   $pdf->SetFont('Arial', 'B', 16);
//   $pdf->Cell(40, 10, 'Invoice');
//   $pdf->Output('F', 'out.pdf');

// NextPDF — points, default page is A4 portrait:
$doc = Document::createStandalone();
$doc->setTitle('Invoice');
$doc->addPage();
$doc->setFont('Helvetica', 'B', 16.0);
$doc->cell(113.4, 28.3, 'Invoice', false, true, Alignment::Left); // ~40mm x ~10mm in points
$doc->save(__DIR__ . '/out.pdf');

echo "Wrote out.pdf\n";

عيّنة شيفرة — إنتاجية

يتوافق هذا المثال مع examples/04-text-and-fonts.php. يستخدم حجم صفحةٍ صريحًا، وهوامش، ودليل خطوطٍ مُسجَّلًا، ونموذج الخلية المدفوع بالمؤشّر الذي تستخدمه شيفرة ⁨FPDF⁩ أصلًا.

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

// Equivalent of: new FPDF('P', 'mm', 'A4') + SetMargins(20, 16, 20)
// i.e. FPDF left=20mm, top=16mm, right=20mm. FPDF SetMargins has no bottom
// argument, so we pick bottom = top = 16mm. Convert each mm to points
// (pt = mm * 72 / 25.4): 16mm = 45.354pt, 20mm = 56.693pt.
// Margin constructor order is (top, right, bottom, left) — NOT FPDF's (L, T, R).
$config = new Config(
    pageSize: new PageSize(595.276, 841.890, 'A4'),
    margins: new Margin(45.354, 56.693, 45.354, 56.693), // top,right,bottom,left in points
    fontsDirectory: __DIR__ . '/fonts',
);

$doc = Document::createStandalone($config);
$doc->setTitle('Quarterly Report');
$doc->setAuthor('Finance');
$doc->addPage();

// SetFont + Cell, the FPDF way — but in points and with a real Unicode font.
$doc->setFont('DejaVuSans', 'B', 18.0);
$doc->setTextColor(30, 58, 138);
$doc->cell(0, 24.0, 'Quarterly Report', false, true, Alignment::Left);

$doc->setFont('DejaVuSans', '', 11.0);
$doc->setTextColor(0, 0, 0);
$doc->multiCell(0, 16.0, "Body text wraps on real font metrics. Unicode is "
    . "native, so accented and non-Latin characters need no tFPDF variant — "
    . "register the family in the fonts directory and select it by name.");

// Equivalent of $pdf->Output('D', 'report.pdf'):
$doc->output('report.pdf', OutputDestination::Download);

الحالات الحدّية والمزالق

• الوحدات. كلّ إحداثيٍّ عددي، وعرض، وارتفاع، وهامش تنسخه من ⁨FPDF⁩ بالمليمترات افتراضيًّا. اضرب في 72 / 25.4 للحصول على النقاط، مرّةً، أثناء النقل. وخلطهما يُخطئ في تحجيم كلّ شيءٍ بصمت.
• ترتيب وسائط Output(). ⁨FPDF⁩ هو Output($dest, $name)؛ و⁨NextPDF⁩ هو output($name, $dest). والوجهة تعداد OutputDestination، لا محرف. فضّل save() / getPdfData() لإخراج الملفّ / السلسلة.
• ترتيب SetMargins. ⁨FPDF⁩ هو (left, top, right)؛ وكائن قيمة Margin في ⁨NextPDF⁩ هو (top, right, bottom, left). أعد الترتيب، لا تنسخ حرفيًّا.
• الخطوط. لا نظير لـAddFont() + ملفّات متريّات .php في ⁨FPDF⁩. ضع ملفّ ⁨TrueType⁩/⁨OpenType⁩ في دليل الخطوط واستدعِ setFont() باسم العائلة. وتُحَلّ أسماء ⁨Base14⁩ الأساسية (Helvetica، Times، Courier) دون ملفّ؛ وتحت ⁨PDF/A⁩ أو ⁨Tagged PDF⁩ تُستبدَل تلقائيًّا بخطٍّ قابلٍ للتضمين.
• GetStringWidth. لا تابعَ قياس سلسلةٍ عامًّا. إن قاست شيفرة ⁨FPDF⁩ لديك السلاسل لتخطيط أعمدةٍ يدويًّا، فبدّل تلك الكتلة إلى multiCell() (الذي يلفّ على المتريّات) أو استدعاءات cell() ثابتة العرض.

الأداء

يُصدِر ⁨NextPDF⁩ المحتوى بتمريرةٍ متدفّقةٍ واحدة (سجلّ قرار معماري ⁨ADR-001⁩)؛ وتتبع ذروة الذاكرة حجم المستند، لا شجرة كائناتٍ محتفظًا بها. وميزانية مثال هذا الدليل wall_ms: 2000, peak_mb: 128. وللمستندات الطويلة، أدِر المحتوى عبر استدعاءات addPage() — شكل الحلقة نفسه الذي يستخدمه تقرير ⁨FPDF⁩ أصلًا.

ملاحظات أمنية

• البيانات الوصفية. SetTitle()/SetAuthor() تُعيَّن على ضوابط مُحدَّدة النوع تكتب قاموس معلومات ⁨ISO 32000-2⁩ §14 / ⁨XMP⁩. لا تخزّن أسرارًا هناك أبدًا.
• مسارات الصور. يرفض image() مخطّطات أغلفة المجاري وبايتات ⁨NUL⁩ المضمَّنة قبل القراءة. مرّر مساراتٍ يتحكّم بها التطبيق.
• لا شيفرة داخل المستند. لا ينفّذ ⁨NextPDF⁩ أيّ نصوصٍ داخل المستند؛ ولا شيء في ⁨FPDF⁩ يغيّر ذلك.

المطابقة

البيان	المواصفة	البند
يُعيَّن تنسيق/اتّجاه الصفحة على صندوق حدّ الصفحة.	ISO 32000-2	§7
تُكتَب الخطوط بوصفها برامج خطٍّ مضمَّنة/مجموعةٍ فرعية.	ISO 32000-2	§9
يَحُلّ العنوان / البيانات الوصفية في قاموس المعلومات / ⁨XMP⁩.	ISO 32000-2	§14
الخطوط والمستطيلات والصور رسمٌ في مجرى المحتوى.	ISO 32000-2	§8

يُنتِج ⁨NextPDF⁩ محتوى ⁨ISO 32000-2⁩؛ ولا يؤكّد تطابقًا بصريًّا مع ⁨FPDF⁩. أعد مراجعة الإخراج كلّما غيّرت العارض.

السياق التجاري

غير منطبق. تغطّي نواة ⁨NextPDF⁩ مسار ترحيل ⁨FPDF⁩ الموصوف هنا.

انظر أيضًا

• فهرس الترحيل
• الترحيل من ⁨mPDF⁩
• الترحيل من ⁨Dompdf⁩
• مُهيّئ التوافق مع ⁨TCPDF⁩
• وحدة Html

---

تفاصيل الترحيل (أقسام ⁨R6⁩ المطلوبة)

لمن هذا الدليل

الفِرق التي تشغّل ⁨FPDF⁩ (أو tF⁨PDF⁩) لتوليد ⁨PDF⁩ إجرائيٍّ من جانب الخادم. إن كانت شيفرتك سلسلةً من استدعاءات AddPage / SetFont / Cell / MultiCell / Image / Output مدفوعةً بـSetXY وLn، فإنّ مخطّط الأفعال يغطّي سطحك كلّه.

النطاق

في النطاق: أفعال رسم ⁨FPDF⁩، ونموذج المؤشّر، والخطوط، والألوان، والخطوط والمستطيلات، والبيانات الوصفية، والإخراج. وخارج النطاق: أدوات ملفّ متريّات AddFont في ⁨FPDF⁩ وتوسيعات نصوص ⁨FPDF⁩ الطرفية الثالثة (الباركود، الدوران، الإشارات المرجعية) — عيّن تلك على وحدات ⁨NextPDF⁩ المقابلة (‏Barcode، Transforms، Navigation)، وهي غير مغطّاةٍ هنا.

خريطة التوافق

توافقٌ سلوكي، لا بديلٌ يُدرَج مباشرةً: لا توفّر النواة بديلَ صنف FPDF. أعد كتابة كلّ موضع استدعاء. وتتراصّ الأفعال على نحوٍ وثيق لأنّ واجهة الخلية/النصّ في ⁨NextPDF⁩ تتشارك نسب ⁨FPDF⁩/⁨TCPDF⁩، لكنّ نموذج الوحدة، وترتيب وسائط Output، وأنواع Margin/التعداد تختلف — فالنسخ الحرفي خطأ، والترجمة صواب.

مخطّط الوحدة والإعداد

بنية FPDF	NextPDF	ملاحظات
$unit ('mm' default)	(no equivalent)	اعمل بنقاط ⁨PDF⁩. حوّل الأبعاد بـpt = mm * 72 / 25.4 مرّةً أثناء النقل.
$orientation ('P'/'L')	Orientation enum on addPage(), or swap PageSize width/height	أفقية = العرض > الارتفاع.
$size ('A4', [w,h])	Config->pageSize (PageSize value object)	تصير التنسيقات المسمّاة أبعاد نقاطٍ صريحة؛ ومصانع PageSize::A4()…A0() وLetter/Legal موجودة.
SetMargins($l, $t, $r)	Config->margins (Margin VO)	ترتيب المُنشئ (top, right, bottom, left).
AddFont($family, $style, $file)	fonts directory + setFont() by name	أسقِط ملفّ المتريّات؛ ضع ملفّ ⁨TTF⁩/⁨OTF⁩ في Config->fontsDirectory.

اختلاف معالجة الخطوط

• أدلّة الخطوط. ينهار تسجيل AddFont لكلّ خطٍّ في ⁨FPDF⁩ إلى دليل خطوطٍ زائد مطابقة عائلة setFont(). ابدأ بـConfig->fontsDirectory (مسار البحث الافتراضي)؛ وسجّل أدلّةً إضافيةً عبر FontRegistry::addFontDirectory() أو Document::addFontDirectory() حين تعيش الخطوط في أكثر من مكان.
• دائمًا ⁨Unicode⁩. لا افتراضَ ⁨Latin-1⁩ ولا بناءَ tF⁨PDF⁩ منفصل؛ ومدخل ⁨UTF-8⁩ هو العُرف.
• دائمًا مجموعةٌ فرعية. يُقسِّم ⁨NextPDF⁩ الخطوط المضمَّنة إلى مجموعاتٍ فرعية دائمًا (‏⁨ISO 32000-2⁩ §9)؛ ولا نظير لخيارات تضمين خطوط ⁨FPDF⁩ وهي غير لازمة.
• أعد ضبط أساس المحارف. مطابقة الخطوط والاحتياط منها خاصّان بالمحرّك؛ وقد يحتاج اسمٌ بديلٌ لخطّ ⁨FPDF⁩ إلى اسم عائلةٍ دقيق. وفروق الاستبدال متوقَّعة، لا عيوب.

الفروق السلوكية

• تحويل الوحدة (مليمتر ← نقطة) — أكثر أخطاء النقل شيوعًا؛ انظر أعلاه.
• يتبدّل ترتيب وسائط Output وتصير الوجهة تعدادًا.
• Margin / Alignment / Orientation كائنات/تعدادات مُحدَّدة النوع، لا محارف ولا ثلاثيّات (l, t, r) موضعية.
• لا GetStringWidth عام — أدِر اللفّ عبر multiCell().
• تنقيطٌ مستقل — قد يختلف لفّ السطر وترقيم الصفحات على المحتوى الكثيف؛ أعد ضبط أساس الفروق البصرية.

هذه فروقٌ سلوكيةٌ موثَّقة، لا عيوبٌ في أيٍّ من المحرّكين.

غير مدعوم / لا نظير مباشر

• مُحدِّد $unit في ⁨FPDF⁩ — غير مُنمذَج (دائمًا نقاط).
• AddFont() + ملفّات متريّات .php/.z — يُستبدَل بدليل خطوط.
• GetStringWidth() — لا فعلَ قياس سلسلةٍ عام.
• محارف وجهة ⁨FPDF⁩ 'I'/'D'/'F'/'S' — يُستبدَل بتعداد OutputDestination + save()/getPdfData().

الشيفرة التي تعتمد على هذه لا “تُرحَّل” حرفيًّا. أعد التعبير عنها بالصفوف أعلاه.

تسلسل الترحيل الآمن

1. أضِف nextpdf/core جنبًا إلى جنبٍ مع ⁨FPDF⁩؛ وأبقِ ⁨FPDF⁩ مُثبَّتًا الآن.
2. اختر مستندًا واحدًا منخفض المخاطر. حوّل المُنشئ عبر خريطة الوحدة، ثمّ انقل كلّ فعلٍ بـ خريطة الأفعال. حوّل كلّ إحداثيِّ مليمترٍ إلى نقاط.
3. ضع خطوط المستند في Config->fontsDirectory واخترها باسم العائلة؛ وأسقِط استدعاءات AddFont.
4. ولّد كلا الـ⁨PDF⁩ للمدخل نفسه وقارنهما بصريًّا. والفروق (استبدال الخطّ، لفّ السطر) متوقَّعةٌ لمحرّكين مستقلّين — اقبلها لكلّ مستند.
5. استبدل أيّ تخطيطٍ يدويٍّ قائمٍ على GetStringWidth بـmultiCell() أو استدعاءات cell() ثابتة العرض.
6. كرّر لكلّ مستند، الأقلّ خطرًا أوّلًا؛ وأبقِ ⁨FPDF⁩ مُثبَّتًا حتى التحويل الأخير.
7. أزِل ⁨FPDF⁩ من composer.json بعد التحويل النهائي.

اختبار الترحيل

• التقط لقطة إخراج ⁨FPDF⁩ للمستندات التمثيلية قبل تغيير الشيفرة (مدخلاتٌ ذهبية؛ وستختلف البايتات).
• لكلّ مستندٍ مُرحَّل، أكّد القبول بفحصك أنت (فرقٌ بصري + استخراج نصّ). ويُمارَس سلوك الخلية/الخطّ في ⁨NextPDF⁩ بـexamples/04-text-and-fonts.php زائد مجموعتَي ‏tests/ الأساسيتين للخطوط وإخراج النصّ. وقبول الترحيل خاصٌّ بالمستند ويبقى مسؤوليّتك.
• أضِف اختبار انحدارٍ لكلّ مستندٍ مُرحَّل.

الأدلّة / إمكانية التتبّع

كلّ بيانٍ سلوكيٍّ عن ⁨NextPDF⁩ في هذه الصفحة مدعومٌ بتوقيع مصدرٍ أو مثالٍ أو سجلّ قرارٍ معماري (‏ADR) داخل المستودع، أو، لخصائص صيغة ⁨PDF⁩، ببنود ⁨ISO 32000-2⁩ في citations: في المقدّمة الأمامية وجدول المطابقة. ويُؤكَّد سلوك ⁨FPDF⁩ فقط بوصفه “محرّكًا مستقلًّا — توقّع فروقًا موثَّقة”؛ ولا تدّعي هذه الصفحة أيّ تكافؤٍ لا يُثبِته أثرٌ داخل المستودع.

ادّعاء ⁨NextPDF⁩ السلوكي	دليلٌ داخل المستودع (المسار)
AddPage maps to addPage(?PageSize, Orientation): static.	src/Core/Concerns/HasPages.php (addPage()).
SetFont($family, $style, $size) maps to setFont(string, string, float): static; ''/'B'/'I'/'BI'/'U' styles.	src/Core/Concerns/HasTypography.php (setFont()).
Cell maps to cell($w, $h, $txt, $border, $newLine, $align, $fill): static.	src/Core/Concerns/HasTextOutput.php (cell()).
MultiCell maps to multiCell($w, $h, $txt, $border, $align): static (metric-based wrap).	src/Core/Concerns/HasTextOutput.php (multiCell(), wrapText()).
Write/Text/Ln map to write()/text()/ln().	src/Core/Concerns/HasTextOutput.php (write(), text(), ln()).
SetXY/SetX/SetY/GetX/GetY map directly; SetMargins takes a Margin VO.	src/Core/Concerns/HasPages.php (setXY(), getX(), setMargins()); src/ValueObjects/Margin.php ((top, right, bottom, left)).
Image maps to image($file, ?$x, ?$y, ?$w, ?$h): static; rejects scheme/NUL paths.	src/Core/Concerns/HasImages.php (image(), assertImageFilePath()).
Line/Rect/SetLineWidth/SetDrawColor/SetFillColor/SetTextColor map directly.	src/Core/Concerns/HasDrawing.php (line(), rect(), setLineWidth()); src/Core/Concerns/HasColors.php (setDrawColor(), setFillColor(), setTextColor()).
createStandalone() default page is A4 portrait (595.276 × 841.890 pt).	src/Core/Document.php (createStandalone()); src/ValueObjects/PageSize.php (A4()).
Output destination is the OutputDestination enum (Inline/Download/File/String); Output('S') → getPdfData(), Output('F', $p) → save($p).	src/Contracts/OutputDestination.php; src/Core/Concerns/HasOutput.php (output()).
SetTitle/SetAuthor/… map to typed metadata setters; land in the info dictionary / XMP.	src/Core/Concerns/HasMetadata.php (setTitle(), setAuthor()); ISO 32000-2 §14 (frontmatter citations:).
Fonts are always embedded as subset programs.	src/Core/Concerns/HasTypography.php (buildFontData()); ISO 32000-2 §9 (frontmatter citations:).
Content is emitted single-pass.	docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md.

التراجع

تبقى كلتا الحزمتين مُثبَّتتين حتى التحويل النهائي، فالتراجع لكلّ موضع استدعاءٍ يعني إرجاع ذلك الموضع إلى مسار ⁨FPDF⁩. وبعد التحويل النهائي، يعني التراجع استعادة ⁨FPDF⁩ والشيفرة السابقة من التحكّم بالإصدارات. ولا ترحيل بياناتٍ متضمَّن.

اعتبارات الأداء

انظر الأداء. يزيل نموذج التمريرة الواحدة أيّ كلفة مخزَّنٍ مؤقّتٍ محتفظٍ به. والكلفة الجديدة لكلّ مستندٍ هي حلّ الخطوط الفوري (الخطوة 3)، وهو قابلٌ للتخزين المؤقّت عبر دليل الخطوط.

المزالق الشائعة

• نسخ إحداثيّات المليمتر بوصفها نقاطًا دون تحويل * 72 / 25.4.
• ترك Output() بترتيب ⁨FPDF⁩ ($dest, $name)، أو تمرير محرفٍ بدلًا من تعداد OutputDestination.
• نسخ SetMargins($l, $t, $r) مباشرةً إلى Margin (الذي ترتيبه top, right, bottom, left).
• توقّع نقل ملفّات متريّات AddFont؛ ضع ملفّ ⁨TTF⁩/⁨OTF⁩ في دليل الخطوط بدلًا من ذلك.
• اللجوء إلى نظير GetStringWidth؛ استخدم multiCell() للفّ.
• توقّع إخراجٍ متطابقٍ بايتًا/بكسلًا (محرّكان مستقلّان — لا تدّعي هذه الصفحة أبدًا إدراجًا مباشرًا أو توافقًا 100%).