مرجع واجهات برمجة تطبيقات Artisan

نظرة سريعة

توفّر حزمة ⁨Artisan⁩ (nextpdf/artisan) مجموعتين مترابطتين من واجهات برمجة التطبيقات. واجهة عرض ⁨Chrome⁩ — ChromeRendererConfig، وChromeHtmlRenderer، وChromeSecurityPolicy، وChromeRenderResult، وViewportCalculator، وBrowserPool — تُحوِّل مقتطفًا من لغة ترميز النص التشعبي (⁨HTML⁩) إلى ملف بتنسيق المستندات المحمولة (⁨PDF⁩) يُنتجه ⁨Chrome.⁩ أما واجهة المحلِّل والمستورِد — PdfReader، وPageImporter، وImportedFormXObject، إلى جانب فئات المُحلِّل اللغوي والمراجع المتقاطعة المساندة — فتُضمِّن ذلك المُخرَج المعروض داخل مستند ⁨NextPDF⁩ بوصفه كائن ⁨Form XObject⁩ بنص قابل للتحديد.

ابدأ من هنا: إذا كان كل ما تحتاج إليه هو إنشاء ملف ⁨PDF⁩ من ⁨HTML⁩، فغالبًا لن تستخدم هذه الحزمة مباشرةً. أرفِق ChromeRendererConfig بمستند ⁨NextPDF⁩ Document واستدعِ writeHtmlChrome()؛ راجع البدء السريع. استخدم الفئات أدناه عند تضمين مُصيِّر داخل عامل تشغيل أو عند تشغيل تشخيصات المحلِّل. يوضّح المثال الأول ضمن المهام الشائعة مسار الاستدعاء الواحد.

المهام الشائعة

تغطي المسارات الثلاثة أدناه معظم استخدامات بيئة الإنتاج، من الاستدعاء الأعلى مستوىً إلى سلسلة العرض والاستيراد الصريحة. جرى التحقق من كل عيِّنة مقابل nextpdf-Artisan/src (وملف README.md / ci/tests/ الخاصَّين بالحزمة).

اعرض مقتطفًا من ⁨HTML⁩ في ملف ⁨PDF⁩ بنص قابل للتحديد باستخدام الاستدعاء المعياري.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Artisan\ChromeRendererConfig;

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

$config = new ChromeRendererConfig(chromeBinaryPath: '/usr/bin/chromium');

$doc = Document::createStandalone();
$doc->setChromeRendererConfig($config);
$doc->addPage();
$doc->writeHtmlChrome('<div style="display:flex;gap:20px"><h2>Revenue</h2><p>$124,500</p></div>');
$doc->save('/tmp/report.pdf');

ما الذي يفعله: يتولى ⁨Chrome⁩ تخطيط المقتطف. يُضمِّن الجسر الصفحة 0 بوصفها كائن ⁨Form XObject⁩، بحيث يظل النص قابلًا للتحديد. يضبط writeHtmlChrome(string $html, ?float $width = null, ?float $height = null): static الارتفاع تلقائيًا عندما تكون قيمة $height هي null.

شغِّل المُصيِّر واستورِد الصفحة بنفسك عندما تحتاج إلى السلسلة الصريحة التي تقف وراء writeHtmlChrome()، كما في عوامل التشغيل أو مسارات الإيداع المخصَّصة.

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeHtmlRenderer;
use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\ImportedFormXObject;
use NextPDF\Artisan\PageImporter;
use NextPDF\Parser\PdfReader;

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig(renderTimeout: 30));

try {
    $result = $renderer->render($html, widthPt: 595.28);

    $reader = new PdfReader($result->getPdfData());
    $reader->parse();

    $form = (new PageImporter())->import($reader);
} finally {
    $renderer->close();
}

ما الذي يفعله: يعرض بايتات ⁨PDF⁩ عبر ⁨Chrome⁩، ثم يحلِّلها ويستورد الصفحة 0 إلى كائن ImportedFormXObject يمكنك إيداعه. استدعِ دائمًا close() على المُصيِّر لتحرير عملية ⁨Chrome.⁩

أنشئ التهيئة من مصفوفة بأسلوب أطر العمل لاستخدامها مع config/*.php أو معامِلات الحزمة، بدلًا من وسائط المُنشئ المثبَّتة برمجيًا.

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeRendererConfig;

$config = ChromeRendererConfig::fromArray([
    'chrome_binary'  => '/usr/bin/chromium',
    'render_timeout' => 45,
    'max_html_size'  => 2_000_000,
    'no_sandbox'     => false,
]);

ما الذي يفعله: يُطابِق مصفوفة تهيئة بنمط ⁨snake-case⁩ مع المُنشئ. تستخدم المفاتيح غير المضبوطة القيم الافتراضية، ولا يُطبَّق chrome_binary إلا عندما يكون سلسلة نصية غير فارغة.

مُصيِّر ⁨Chrome⁩

تُشغِّل هذه الأنواع مسار العرض. أنشئ ChromeRendererConfig، ومرِّره إلى ChromeHtmlRenderer، ثم استدعِ render() للحصول على ChromeRenderResult.

الرمز	المعامِلات	السلوك الافتراضي	القيمة المُعادة	يُطلِق استثناءً أو يفشل بسبب	ملاحظات
`new ChromeRendererConfig(?string $chromeBinaryPath = null, int $renderTimeout = 30, string $defaultCss = '', int $maxHtmlSize = 5000000, bool $noSandbox = false)`	مسار الملف الثنائي، والمهلة، وأوراق الأنماط المتتالية (⁨CSS⁩)، والحد الأقصى لحجم ⁨HTML⁩، وعلَم وضع الحماية.	يكتشف ⁨Chrome⁩ تلقائيًا عندما يكون مسار الملف الثنائي `null`؛ ويظل وضع الحماية مُفعَّلًا ما لم يُعطَّل.	`ChromeRendererConfig`	لا شيء متوقَّع.	اضبط `noSandbox` فقط عندما تتطلب بيئة التشغيل ذلك.
`ChromeRendererConfig::fromArray(array $config)`	`chrome_binary`, `render_timeout`, `default_css`, `max_html_size`, `no_sandbox`.	تستخدم القيم المفقودة القيم الافتراضية للمُنشئ.	`ChromeRendererConfig`	تعود حالات عدم تطابق النوع إلى القيم الافتراضية للمفاتيح الاختيارية.	يُطابِق مصفوفات التهيئة بأسلوب أطر العمل.
`new ChromeHtmlRenderer(ChromeRendererConfig $config, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null)`	التهيئة، ومُسجِّل اختياري، وسياسة ⁨HTML⁩ اختيارية على مستوى التحليل.	يستخدم `DefaultHtmlSecurityPolicy` عند عدم تزويده بسياسة.	`ChromeHtmlRenderer`	تظهر أخطاء إعداد ⁨Chrome⁩ عند أول عملية عرض.	يحتفظ المُصيِّر بتجمُّع المتصفِّحات حتى استدعاء `close()`.
`ChromeHtmlRenderer::render(string $html, float $widthPt, float $heightPt = 0)`	`html`: الجزء المُدخَل؛ `widthPt`: عرض الورقة؛ `heightPt`: الارتفاع المستهدَف أو تلقائي.	يحسب ارتفاع المحتوى تلقائيًا عندما تكون `heightPt <= 0`.	`ChromeRenderResult`	`ChromeRenderException`؛ فشل التحقق من حجم ⁨HTML.⁩	يحظر طلبات الشبكة للموارد الفرعية عبر بروتوكول أدوات مطوِّري ⁨Chrome⁩ (⁨CDP⁩).
`ChromeHtmlRenderer::getHtmlSecurityPolicy()`	لا شيء.	يُعيد السياسة المُهيَّأة على مستوى التحليل.	`HtmlSecurityPolicyInterface`	لا شيء متوقَّع.	يُكمِّل عناصر تحكُّم ⁨Chrome⁩ على مستوى النقل.
`ChromeHtmlRenderer::close()`	لا شيء.	يغلق تجمُّع المتصفِّحات ويمسحه.	`void`	قد تظهر أخطاء إيقاف تشغيل المتصفِّح من المكتبة الأساسية.	استدعِه عند إيقاف عامل التشغيل.

سياسة أمان ⁨HTML⁩

استخدم واجهات برمجة التطبيقات هذه عندما تتحقق من ⁨HTML⁩ خارجي وتغلِّفه قبل العرض، بدلًا من استدعاء ChromeHtmlRenderer::render() مباشرةً؛ فهذا الأسلوب يستدعيها بالفعل.

الرمز	المعامِلات	السلوك الافتراضي	القيمة المُعادة	يُطلِق استثناءً أو يفشل بسبب	ملاحظات
`ChromeSecurityPolicy::validate(string $html, int $maxSize)`	مُدخَل ⁨HTML⁩ والحد الأقصى لحجم البايتات.	لا يقبل المُدخَل إلا بعد اجتياز فحوصات الحجم والبُنى غير المسموح بها.	`void`	`ChromeRenderException` أو استثناء تحقُّق.	شغِّله قبل العرض في المتصفِّح عند قبول ⁨HTML⁩ خارجي.
`ChromeSecurityPolicy::wrapHtml(string $html, int $viewportWidth, string $defaultCss = '')`	جزء ⁨HTML⁩، وعرض منطقة العرض، وأوراق أنماط ⁨CSS⁩ افتراضية اختيارية.	يُنتِج مستند عرض كاملًا حول الجزء.	`string`	أخطاء التحقق أو إنشاء السلسلة النصية.	يُبقي أوراق أنماط ⁨CSS⁩ الخاصة بالمُصيِّر منفصلةً عن ⁨HTML⁩ الخاص بالتطبيق.

النتيجة ومساعِدات التحويل

استخدم هذه المساعِدات لقراءة نتيجة العرض (ChromeRenderResult) وللتحويل بين نقاط ⁨PDF⁩ وبكسلات ⁨CSS⁩ الخاصة بـ ⁨Chrome⁩ عند تحديد حجم منطقة العرض أو حساب الارتفاع.

الرمز	المعامِلات	السلوك الافتراضي	القيمة المُعادة	يُطلِق استثناءً أو يفشل بسبب	ملاحظات
`new ChromeRenderResult(string $pdfData, float $widthPt, float $heightPt, float $contentHeightCssPx)`	بايتات ⁨PDF⁩ الخام، والعرض، والارتفاع، وارتفاع المحتوى المقيس.	لا يُجري تحقُّقًا يتجاوز خصائص المُنشئ المُحدَّدة النوع.	`ChromeRenderResult`	لا شيء متوقَّع.	تُعاد عادةً من `ChromeHtmlRenderer::render()`.
`ChromeRenderResult::getPdfData()`	لا شيء.	يُعيد بايتات ⁨PDF⁩ الخام من إنتاج ⁨Chrome.⁩	`string`	لا شيء متوقَّع.	استخدمه مع `PdfReader` و`PageImporter` عند التضمين.
`ChromeRenderResult::getWidthPt()`	لا شيء.	يُعيد العرض المطلوب بالنقاط.	`float`	لا شيء متوقَّع.	يُستخدَم لتحديد حجم كائن النموذج المستورَد.
`ChromeRenderResult::getHeightPt()`	لا شيء.	يُعيد الارتفاع المحسوب أو المطلوب بالنقاط.	`float`	لا شيء متوقَّع.	يتضمَّن الارتفاع التلقائي حيِّزًا احتياطيًا لتخطيط الطباعة.
`ViewportCalculator::pointsToCssPx(float $pt)`	`pt`: نقاط ⁨PDF.⁩	يُحوِّل باستخدام 96 بكسل ⁨CSS⁩ لكل 72 نقطة ⁨PDF.⁩	`int`	لا شيء متوقَّع.	يُقرَّب بما يناسب عرض منطقة عرض ⁨Chrome.⁩
`ViewportCalculator::cssPxToPoints(float $px)`	`px`: بكسلات ⁨CSS.⁩	يُحوِّل باستخدام 72 نقطة ⁨PDF⁩ لكل 96 بكسل ⁨CSS.⁩	`float`	لا شيء متوقَّع.	يُستخدَم لحساب الارتفاع التلقائي.

واجهات الاستيراد والمحلِّل

هذا هو مسار الاستيراد. حلِّل بايتات ⁨PDF⁩ من ⁨Chrome⁩ باستخدام PdfReader، ثم مرِّر القارئ إلى PageImporter::import() للحصول على صفحة قابلة للتضمين؛ وتدعم بقية أساليب PdfReader أغراض التشخيص.

الرمز	المعامِلات	السلوك الافتراضي	القيمة المُعادة	يُطلِق استثناءً أو يفشل بسبب	ملاحظات
`new PdfReader(string $data)`	`data`: بايتات ⁨PDF⁩ كاملة.	لا يُشغَّل المحلِّل حتى استدعاء `parse()`.	`PdfReader`	لا شيء متوقَّع.	مُصمَّم لملفات ⁨PDF⁩ المُولَّدة بواسطة ⁨Chrome.⁩
`PdfReader::parse()`	لا شيء.	يحلِّل سلسلة المراجع المتقاطعة (⁨xref⁩) والمُذيِّل.	`void`	`PdfParseException` لبنية ⁨PDF⁩ غير صالحة.	يجب استدعاؤه قبل الوصول إلى ⁨object/page.⁩
`PdfReader::getObject(int $objNum)`	رقم الكائن.	يحلُّ الكائن المُحلَّل حسب الرقم.	`PdfObject`	`PdfParseException` عند فقدان الكائن أو تلفه.	استخدمه بعد `parse()`.
`PdfReader::getTrailer()`	لا شيء.	يُعيد قاموس المُذيِّل المُحلَّل.	`array`	`PdfParseException` عند عدم توفُّر بيانات المُذيِّل.	يُستخدَم في التشخيصات وتحليل المراجعات.
`PdfReader::getObjectNumbers()`	لا شيء.	يُعيد أرقام الكائنات المُحلَّلة.	`array`	لا شيء متوقَّع بعد التحليل.	مفيد لتشخيصات المستورِد.
`PdfReader::getPage(int $pageIndex)`	`pageIndex`: فهرس صفحة يبدأ من الصفر.	لا يُجري تحليلًا ضمنيًا.	`PdfObject`	`PdfParseException` عند الفقدان أو تجاوز النطاق.	يستخدم المستورِد الصفحة `0` افتراضيًا.
`PdfReader::getPageContentStream(PdfObject $page)`	`page`: كائن صفحة مُحلَّل.	يحلُّ دفق المحتوى.	`string`	`PdfParseException` للأدفاق غير الصالحة.	يتسبَّب الدفق الفارغ في فشل المستورِد.
`PdfReader::getPageResources(PdfObject $page)`	`page`: كائن صفحة مُحلَّل.	يحلُّ موارد الصفحة.	`array`	`PdfParseException` للموارد غير الصالحة.	يُضمَّن قاموس الموارد مع كائن النموذج.
`PdfReader::getPageMediaBox(PdfObject $page)`	`page`: كائن صفحة مُحلَّل.	يعود إلى أبعاد شبيهة بـ ⁨A4⁩ عند غيابها.	`array`	إخفاقات المحلِّل.	يُعيد إحداثيات فضاء ⁨PDF.⁩
`PdfReader::resolveRef(mixed $value)`	قيمة مُحلَّلة.	يحلُّ مراجع الكائنات تكراريًا عند انطباق ذلك.	`mixed`	`PdfParseException` للمراجع غير الصالحة.	مساعِد بأسلوب داخلي يُكشَف عنه لمسارات عمل المستورِد.
`PdfReader::collectPageResources(PdfObject $page)`	`page`: كائن صفحة مُحلَّل.	يجتاز مراجع موارد الصفحة.	`array`	إخفاقات المحلِّل.	يُستخدَم لتضمين الكائنات التابعة مع الصفحات المستورَدة.
`PdfReader::getRevisionCount()`	لا شيء.	يَعُدُّ المراجعات التزايدية المُحلَّلة.	`int`	لا شيء متوقَّع بعد التحليل.	مفيد لملفات ⁨PDF⁩ المُوقَّعة أو المُحدَّثة تزايديًا.
`PdfReader::getRevisionXRef(int $index)`	فهرس مراجعة يبدأ من الصفر.	يُعيد جدول ⁨xref⁩ لمراجعة واحدة.	`RevisionXRefTable`	`PdfParseException` للفهرس غير الصالح.	يُستخدَم لتشخيصات المراجعات منخفضة المستوى.
`PdfReader::getRevisions()`	لا شيء.	يُعيد جميع جداول ⁨xref⁩ للمراجعات المُحلَّلة.	`array`	لا شيء متوقَّع بعد التحليل.	يعرض حالة المحلِّل للقراءة فقط.
`PageImporter::import(PdfReader $reader, int $pageIndex = 0)`	قارئ مُحلَّل وفهرس صفحة يبدأ من الصفر.	يستورد الصفحة الأولى عند الحذف.	`ImportedFormXObject`	`PdfParseException` عند تعذُّر استخراج الصفحة.	يجمع دفق المحتوى، وإطار الوسائط، والموارد، والكائنات المُشار إليها.

كائنات دعم المحلِّل

تُعاد كائنات القيمة والمساعِدات هذه من المحلِّل أو تُستخدَم داخليًا. استخدمها عند فحص الكائنات المستورَدة، أو الموارد، أو الأدفاق، أو جداول المراجعات.

الرمز	المعامِلات	السلوك الافتراضي	القيمة المُعادة	يُطلِق استثناءً أو يفشل بسبب	ملاحظات
`new ImportedFormXObject(string $contentStream, array $mediaBox, array $embeddedObjects, array $resourcesDict)`	دفق المحتوى المُفكَّك، وإطار الوسائط، والكائنات المُضمَّنة، وقاموس الموارد.	يخزِّن حمولة نموذج مستورَد قائمة بذاتها.	`ImportedFormXObject`	لا شيء متوقَّع.	تُعاد عادةً من `PageImporter::import()`.
`ImportedFormXObject::getWidth()`	لا شيء.	يُعيد عرض النموذج المستورَد بالنقاط.	`float`	لا شيء متوقَّع.	استخدمه عند إيداع مُخرَج ⁨Chrome⁩ في صفحة.
`ImportedFormXObject::getHeight()`	لا شيء.	يُعيد ارتفاع النموذج المستورَد بالنقاط.	`float`	لا شيء متوقَّع.	تنتشر نتائج العرض ذات الارتفاع التلقائي عبر هذه القيمة.
`ImportedFormXObject::getEmbeddedObjects()`	لا شيء.	يُعيد الكائنات التي يتطلبها النموذج المستورَد.	`array`	لا شيء متوقَّع.	تستخدم شيفرة الكاتب هذه الكائنات للحفاظ على الموارد.
`ImportedFormXObject::getResourcesDict()`	لا شيء.	يُعيد قاموس الموارد المستورَد.	`array`	لا شيء متوقَّع.	يُستخدَم عند إنشاء كائن ⁨Form XObject.⁩
`ImportedFormXObject::getMediaBox()`	لا شيء.	يُعيد إطار الوسائط المستورَد.	`array`	لا شيء متوقَّع.	يُستخدَم لتشخيصات الإيداع.
`ImportedFormXObject::getContentStream()`	لا شيء.	يُعيد دفق محتوى الصفحة المستورَدة.	`string`	لا شيء متوقَّع.	مُخصَّص لتكامل ⁨writer/import.⁩
`new PdfObject(int $objectNumber, int $generation, array $dictionary, ?string $rawStreamData = null, ?string $decodedStreamData = null, ?string $rawDictionaryBytes = null)`	رقم الكائن، والجيل، والقاموس المُحلَّل، وبايتات الدفق الاختيارية، والدفق المُفكَّك الاختياري، وبايتات القاموس الخام الاختيارية.	يخزِّن حالة الكائن المُحلَّل.	`PdfObject`	لا شيء متوقَّع.	يُنشَأ بواسطة العناصر الداخلية للمحلِّل.
`PdfObject::getRawDictionaryBytes()`	لا شيء.	يُعيد بايتات القاموس الأصلية عند توفُّرها.	`string	null`	لا شيء متوقَّع.
`PdfObject::getRawStreamData()`	لا شيء.	يُعيد بايتات الدفق غير المُفكَّكة عند توفُّرها.	`string	null`	لا شيء متوقَّع.
`PdfObject::getDictionary()`	لا شيء.	يُعيد مُدخَلات القاموس المُحلَّلة.	`array`	لا شيء متوقَّع.	يعرض حالة المحلِّل للقراءة فقط.
`PdfObject::get(string $key)`	مفتاح القاموس.	يُعيد `null` عند غياب المفتاح.	`mixed`	لا شيء متوقَّع.	يُجنِّب المُستدعين تحليل القواميس الخام.
`PdfObject::getRef(string $key)`	مفتاح القاموس.	يُعيد صف مرجع الكائن عندما تكون القيمة مرجعًا.	`array	null`	لا شيء متوقَّع.
`PdfObject::getArray(string $key)`	مفتاح القاموس.	يُعيد قيمة مصفوفة أو مصفوفة فارغة عند عدم التوفُّر.	`array`	لا شيء متوقَّع.	غلاف ملائم لمُدخَلات القاموس ذات القيم المصفوفية.
`PdfObject::hasStream()`	لا شيء.	يتحقق مما إذا كانت بايتات الدفق موجودة.	`bool`	لا شيء متوقَّع.	يميِّز الكائنات ذات القاموس فقط.
`PdfObject::getType()`	لا شيء.	يقرأ `/Type`.	`string	null`	لا شيء متوقَّع.
`PdfObject::getSubtype()`	لا شيء.	يقرأ `/Subtype`.	`string	null`	لا شيء متوقَّع.
`RevisionExtractor::extractRevision(string $pdfData, PdfReader $reader, int $revision)`	بايتات ⁨PDF⁩، وقارئ مُحلَّل، وفهرس المراجعة الذي يبدأ من الصفر.	يستخرج مراجعة تزايدية واحدة.	`string`	`PdfParseException` للحدود غير الصالحة.	يُستخدَم في اختبارات المحلِّل وتشخيصاته.
`RevisionExtractor::getRevisionBoundaries(string $pdfData, PdfReader $reader)`	بايتات ⁨PDF⁩ وقارئ مُحلَّل.	يكتشف نطاقات البايتات للمراجعات التزايدية.	`array`	`PdfParseException` لبنية ⁨xref⁩ المُشوَّهة.	يساعد على تحليل ملفات ⁨PDF⁩ المُوقَّعة أو المُحدَّثة تزايديًا.
`StreamDecoder::decode(string $data, string	array $filter)`	بايتات الدفق ومُرشِّح ⁨PDF⁩ واحد أو أكثر.	يُطبِّق المُرشِّحات بالترتيب.	`string`	`PdfParseException` للمُرشِّحات غير المدعومة أو غير الصالحة.
`new ResourceCollector(PdfReader $reader)`	قارئ مُحلَّل.	يبدأ بمجموعة كائنات مجمَّعة فارغة.	`ResourceCollector`	لا شيء متوقَّع.	يُستخدَم بواسطة `PdfReader::collectPageResources()`.
`ResourceCollector::traverse(mixed $value, int $depth = 0)`	قيمة مُحلَّلة وعمق التكرار.	يجتاز مراجع الموارد حتى حدود العمق الداخلية.	`void`	إخفاقات المحلِّل للمراجع غير الصالحة.	مساعِد داخلي لاستكمال موارد استيراد الصفحة.
`ResourceCollector::getCollected()`	لا شيء.	يُعيد كائنات الموارد المجمَّعة.	`array`	لا شيء متوقَّع.	استدعِه بعد `traverse()`.
`new RevisionXRefTable(int $index, int $xrefOffset, array $xrefEntries, array $trailer, ?int $prevOffset)`	فهرس المراجعة، وإزاحة ⁨xref⁩، ومُدخَلات ⁨xref⁩، والمُذيِّل، والإزاحة السابقة الاختيارية.	لقطة غير قابلة للتغيير لمراجعة تزايدية واحدة.	`RevisionXRefTable`	لا شيء متوقَّع.	يُنشَأ بواسطة العناصر الداخلية للمحلِّل.
`RevisionXRefTable::getObjectNumbers()`	لا شيء.	يُعيد أرقام الكائنات النشطة في جدول المراجعة.	`array`	لا شيء متوقَّع.	واجهة برمجة تطبيقات تشخيصية للمراجعات منخفضة المستوى.
`RevisionXRefTable::getActiveObjectCount()`	لا شيء.	يَعُدُّ الكائنات النشطة.	`int`	لا شيء متوقَّع.	مفيد لتأكيدات المحلِّل.
`RevisionXRefTable::hasRootUpdate()`	لا شيء.	يُبلِّغ عمَّا إذا كانت المراجعة تُحدِّث جذر المستند.	`bool`	لا شيء متوقَّع.	مفيد لتحليل التحديثات التزايدية.
`RevisionXRefTable::getSize()`	لا شيء.	يُعيد قيمة حجم جدول ⁨xref.⁩	`int`	لا شيء متوقَّع.	يعكس البيانات الوصفية لـ ⁨xref⁩ المُحلَّلة من ⁨PDF.⁩

واجهات المُحلِّل اللغوي و⁨xref⁩ منخفضة المستوى

استخدم واجهات برمجة التطبيقات هذه فقط لتشخيصات المحلِّل العميقة أو تقليل المُلحَقات. فهي تكشف آلية المُحلِّل اللغوي والمراجع المتقاطعة الكامنة تحت PdfReader، وليست لازمة للاستيراد المعتاد.

الرمز	المعامِلات	السلوك الافتراضي	القيمة المُعادة	يُطلِق استثناءً أو يفشل بسبب	ملاحظات
`new PdfTokenizer(string $data, int $offset = 0)`	بايتات ⁨PDF⁩ وإزاحة أولية اختيارية.	يبدأ عند الإزاحة صفر.	`PdfTokenizer`	لا شيء متوقَّع.	مُحلِّل لغوي منخفض المستوى.
`PdfTokenizer::getOffset()`	لا شيء.	يُعيد إزاحة البايت الحالية.	`int`	لا شيء متوقَّع.	مساعِد تشخيصي لأخطاء المحلِّل.
`PdfTokenizer::setOffset(int $offset)`	إزاحة البايت.	يحرِّك مؤشِّر المُحلِّل اللغوي.	`void`	`PdfParseException` للإزاحة غير الصالحة.	استخدمه بحذر؛ يدير المُستدعون حالة المحلِّل.
`PdfTokenizer::isEof()`	لا شيء.	يتحقق مما إذا كان المؤشِّر قد بلغ النهاية.	`bool`	لا شيء متوقَّع.	مساعِد لحلقة المحلِّل منخفض المستوى.
`PdfTokenizer::skipWhitespace()`	لا شيء.	يتجاوز المسافات البيضاء والتعليقات في ⁨PDF.⁩	`void`	لا شيء متوقَّع.	يُستخدَم قبل قراءة الرموز.
`PdfTokenizer::readToken()`	لا شيء.	يقرأ الرمز القياسي التالي.	`string	int	float
`PdfTokenizer::readName()`	لا شيء.	يقرأ كائن اسم ⁨PDF.⁩	`string`	`PdfParseException` للاسم المُشوَّه.	يفُكُّ ترميز هروب الاسم.
`PdfTokenizer::readLiteralString()`	لا شيء.	يقرأ سلسلة نصية حرفية.	`string`	`PdfParseException` للسلسلة النصية المُشوَّهة.	يعالج الأقواس المتداخلة وأحرف الهروب.
`PdfTokenizer::readHexString()`	لا شيء.	يقرأ سلسلة نصية ست عشرية.	`string`	`PdfParseException` للنظام الست عشري المُشوَّه.	يُكمِّل الأرقام الست عشرية ذات الطول الفردي وفقًا لقواعد المحلِّل.
`PdfTokenizer::readNumber()`	لا شيء.	يقرأ عددًا صحيحًا أو عددًا عشريًا.	`int	float`	`PdfParseException` للرقم غير الصالح.
`PdfTokenizer::readKeyword()`	لا شيء.	يقرأ كلمة مفتاحية في ⁨PDF.⁩	`string`	`PdfParseException` للكلمة المفتاحية غير الصالحة.	يُبقي تحليل الكلمات المفتاحية مركزيًا.
`PdfTokenizer::readDictionary()`	لا شيء.	يقرأ قاموس ⁨PDF.⁩	`array`	`PdfParseException` للقواميس المُشوَّهة.	يُستخدَم للكائنات والأدفاق والمُذيِّلات.
`PdfTokenizer::readArray()`	لا شيء.	يقرأ مصفوفة ⁨PDF.⁩	`array`	`PdfParseException` للمصفوفات المُشوَّهة.	مساعِد تكراري للمحلِّل.
`PdfTokenizer::readValue()`	لا شيء.	يقرأ أي قيمة ⁨PDF⁩ مدعومة.	`mixed`	`PdfParseException` للقيم المُشوَّهة.	بدائية محلِّل شائعة.
`PdfTokenizer::readStreamData(int $length)`	طول الدفق.	يقرأ بالضبط بايتات الدفق المطلوبة.	`string`	`PdfParseException` لحدود الدفق غير الصالحة.	يُستخدَم بعد حلِّ طول دفق القاموس.
`PdfTokenizer::peek(int $length = 1)`	عدد البايتات.	يقرأ مسبقًا دون التقدُّم.	`string`	لا شيء متوقَّع.	مفيد لتفرُّع المحلِّل.
`PdfTokenizer::searchBackward(string $pattern, int $startFrom = 0)`	نمط وإزاحة بداية اختيارية.	يبحث عكسيًا من النهاية أو من الإزاحة المُقدَّمة.	`int	false`	لا شيء متوقَّع.
`PdfTokenizer::readLine()`	لا شيء.	يقرأ سطرًا من الإزاحة الحالية.	`string`	لا شيء متوقَّع.	مساعِد ماسح منخفض المستوى.
`CrossRefParser::parseXRefTable(string $data, int $offset)`	بايتات ⁨PDF⁩ وإزاحة جدول ⁨xref.⁩	يحلِّل مُدخَلات جدول المراجع المتقاطعة الكلاسيكي.	`array`	`PdfParseException` لبيانات ⁨xref⁩ المُشوَّهة.	واجهة برمجة تطبيقات للمحلِّل منخفضة المستوى.
`CrossRefParser::parseXRefStream(string $data, int $offset)`	بايتات ⁨PDF⁩ وإزاحة دفق ⁨xref.⁩	يحلِّل مُدخَلات دفق المراجع المتقاطعة.	`array`	`PdfParseException` لبيانات الدفق المُشوَّهة.	يدعم أدفاق ⁨xref⁩ الحديثة في ⁨PDF.⁩

المصانع الاختيارية وتجمُّع المتصفِّحات

يحلُّ EInvoiceServiceFactory عقود الفاتورة الإلكترونية الاختيارية في ⁨Premium⁩ بصورة كسولة ويُعيد null عند غيابها. يدير BrowserPool دورة حياة ⁨Chrome⁩ المملوكة للمُصيِّر؛ أدِرْه مباشرةً فقط في عوامل التشغيل طويلة الأمد.

الرمز	المعامِلات	السلوك الافتراضي	القيمة المُعادة	يُطلِق استثناءً أو يفشل بسبب	ملاحظات
`EInvoiceServiceFactory::makeEmbedder()`	لا شيء.	يُعيد `null` ما لم يكن دعم الفاتورة الإلكترونية في ⁨Premium Pro⁩ مُثبَّتًا.	`EmbedderInterface	null`	أخطاء إنشاء الحزمة الاختيارية.
`EInvoiceServiceFactory::makeValidator()`	لا شيء.	يُعيد `null` ما لم يكن دعم التحقق في ⁨Premium Enterprise⁩ مُثبَّتًا.	`ValidatorInterface	null`	أخطاء إنشاء الحزمة الاختيارية.
`EInvoiceServiceFactory::makeDefaultProfile()`	لا شيء.	يُعيد ملف تعريف الفاتورة الإلكترونية الافتراضي عند توفُّره.	`ProfileInterface	null`	أخطاء الحزمة الاختيارية.
`EInvoiceServiceFactory::makeSchematronRunner()`	لا شيء.	يُعيد `null` ما لم يكن دعم ⁨Schematron⁩ في ⁨Premium Enterprise⁩ مُثبَّتًا.	`SchematronRunnerInterface	null`	أخطاء إنشاء الحزمة الاختيارية.
`new BrowserPool(ChromeRendererConfig $config, ?LoggerInterface $logger = null)`	تهيئة المُصيِّر ومُسجِّل اختياري.	يبدأ المتصفِّح بشكل كسول عند أول `getBrowser()`.	`BrowserPool`	لا شيء متوقَّع حتى بدء تشغيل المتصفِّح.	مساعِد دورة حياة مملوك للمُصيِّر.
`BrowserPool::getBrowser()`	لا شيء.	يبدأ نسخة متصفِّح ⁨Chrome⁩ الحالية أو يُعيدها.	`Browser`	أخطاء بدء تشغيل المتصفِّح.	مساعِد دورة حياة مملوك للمُصيِّر.
`BrowserPool::incrementRenderCount()`	لا شيء.	يزيد عدَّاد العرض ويدوِّر عندما تتطلب سياسة التجمُّع ذلك.	`void`	أخطاء دورة حياة المتصفِّح.	يُستخدَم بواسطة عوامل التشغيل طويلة الأمد.
`BrowserPool::close()`	لا شيء.	يغلق نسخة المتصفِّح المُدارة.	`void`	أخطاء إيقاف تشغيل المتصفِّح.	استدعِه أثناء إيقاف تشغيل عامل التشغيل.

ملاحظات التطوير

المُصيِّر ليس وضع حماية متصفِّح لـ ⁨HTML⁩ غير الموثوق. تحقَّق من الحجم وسياسة الموارد وتفويض المُستدعي قبل العرض.
واجهات المحلِّل ضيِّقة عمدًا. استخدمها لاستيراد مُخرَج ⁨Chrome⁩، لا لإصلاح ملفات ⁨PDF⁩ العامة.
أغلق المُصيِّرات صراحةً في عوامل التشغيل طويلة الأمد.