Pro الإصدار

‏⁨Webview⁩ — مرجع متعمّق

لمحة سريعة

توثّق هذه الصفحة سطح NextPDF\Pro\Webview العام، ونموذج طلب/استجابة نطاق البايتات، وأنماط الفشل بالضبط على نحو يتجاوز صفحة الوصول العامة.

التوفّر والترخيص

تُشحَن هذه القدرة في ‏⁨NextPDF Pro⁩ (nextpdf/pro) وتُفعَّل بمظروف ترخيص من فئة ⁨Pro⁩. والنشر دون ذلك الاستحقاق لا يحمّل أصناف هذه القدرة. قارن الإصدارات واحصل على ترخيص.

لا توجد علامة ترخيص لكل ميزة؛ فالشيفرة تُشحَن مع إصدار ⁨Pro⁩. وResponseFactoryInterface / StreamFactoryInterface بنمط ⁨PSR-17⁩ ونوعُ وسيط الجسم هي وسائط بنّاء في وقت التشغيل، لا ضوابط ترخيص.

سطح واجهة برمجة التطبيقات العامة

composer require nextpdf/pro

الأنواع العامة تحت NextPDF\Pro\Webview:

LinearizedDocument — ملفّ ⁨PDF⁩ مُخطَّط خطّيًا ومُتحقَّق منه ومُهيَّأ للتسليم.
ByteRangeResponder — مُجيب ⁨HTTP⁩ لنطاق البايتات وفق ⁨RFC 9110⁩.
ByteRange — نطاق بايتات شامل واحد قابل للإرضاء على تمثيل.
FirstPageProber — برهان «الصفحة الأولى قبل التنزيل الكامل» البنيوي.

أنواع الاستثناءات تحت NextPDF\Pro\Webview\Exception:

WebviewException (واجهة علامة)، وUnsupportedDocumentException، وRangeNotSatisfiableException.

`LinearizedDocument`

صنف final readonly ذو بنّاء خاصّ؛ أنشئه عبر البنّاء المُسمّى.

static fromBytes(string $bytes): self — يحلّل البايتات عبر LinearizationView::fromPdf() القرائية في النواة. ويرمي UnsupportedDocumentException حين لا يكون المستند مُخطَّطًا خطّيًا، أو حين لا يطابق /L المُعلَن طولَ البايتات الفعلي، أو حين لا تكون إزاحة نهاية الصفحة الأولى /E إزاحة موجبة داخل الملفّ.
length(): int — طول المستند بالبايتات.
firstPagePrefixLength(): int — البادئة الأمامية الدنيا التي تحتوي الصفحة الأولى كاملةً: إزاحة /E، مُثبَّتة عند طول الملفّ.
firstPageByteRange(): ByteRange — النطاق الشامل [0, /E - 1] الذي يسلّم الصفحة الأولى. ويرمي RangeNotSatisfiableException فقط إن كانت البادئة فارغة (دفاع متعمّق؛ يضمن fromBytes() أصلًا 0 < /E <= length).
slice(int $firstByte, int $lastByte): string — تقطيع برمجيّ صارم بإزاحات شاملة؛ يرمي RangeNotSatisfiableException حين يخرج عن الحدود.
etag(): string — وسم كيان ⁨SHA-256⁩ قويّ حتميّ للبايتات، يُحفَظ مرّةً واحدةً عند الإنشاء.

الخصائص العامة للقراءة فقط: bytes (بايتات ⁨PDF⁩ الخام) وview (الـLinearizationView في النواة).

`ByteRangeResponder`

صنف final readonly مُنفَّذ مقابل ⁨PSR-7⁩ / ⁨PSR-17⁩ فقط.

__construct(ResponseFactoryInterface $responses, StreamFactoryInterface $streams, string $contentType = 'application/pdf') — يرمي InvalidArgumentException حين يحتوي $contentType على محارف تحكُّم (يُدمَج في ترويسات الاستجابة والأجزاء متعدّدة الأجزاء؛ وتُرفَض ⁨CR/LF⁩ وسائر بايتات التحكُّم لمنع حقن الترويسات).
respond(LinearizedDocument $document, ServerRequestInterface $request): ResponseInterface — يجيب على طلب نطاق لمستند مُخطَّط خطّيًا، مستخدمًا ETag المستند نفسه.
respondToBytes(string $bytes, ServerRequestInterface $request, ?string $etag = null): ResponseInterface — يجيب على طلب نطاق لبايتات اعتباطية (تمثيل ينبغي أن يدعم النطاقات من دون أن يكون مُخطَّطًا خطّيًا). ويُشتقّ ETag من البايتات حين يكون null.
firstPageResponse(LinearizedDocument $document): ResponseInterface — يبني 206 تحمل بالضبط نطاق بايتات الصفحة الأولى؛ شكل الدفع من الخادم لـ«الصفحة الأولى قبل التنزيل الكامل».

`ByteRange`

كائن قيمة final readonly لنطاق بايتات شامل واحد قابل للإرضاء (‏⁨RFC 9110 §14.1.2⁩).

__construct(int $firstByte, int $lastByte, int $contentLength) — يفرض قابلية الإرضاء 0 <= firstByte <= lastByte <= contentLength - 1؛ ويرمي RangeNotSatisfiableException فيما عدا ذلك.
length(): int — المدى الشامل (lastByte - firstByte + 1)، دائمًا >= 1.
contentRange(): string — قيمة حقل Content-Range وفق ⁨RFC 9110 §14.4⁩ bytes first-last/length.

الخصائص العامة للقراءة فقط: firstByte، وlastByte، وcontentLength.

`FirstPageProber`

صنف final readonly مُنشأ من LinearizedDocument.

prefixLength(): int — أدنى عدد بايتات أمامية لازم لتصيير الصفحة الأولى.
prefixFraction(): float — كسر الملفّ كاملًا (⁨0.0⁩–⁨1.0⁩) الذي تمثّله البادئة؛ ويُرجِع 1.0 لملفّ صفريّ الطول.
hintStreamWithinPrefix(): bool — ما إذا كان كائن تدفّق التلميح الأساسي يقع بالكامل داخل بادئة الصفحة الأولى (فتتيح البادئة وحدها للقارئ تحديد موقع كائنات الصفحة 1). ويجب أن يكون لتدفّق التلميح طول موجب.
isFirstPageSelfContained(): bool — البرهان البنيوي المُركَّب: بادئة موجبة تتّسع داخل الملفّ وتحتوي تدفّق التلميح بالكامل.

نموذج طلب/استجابة نطاق البايتات

يتبع ByteRangeResponder ⁨RFC 9110 §14⁩. وبعد حساب الطول وETag قويّ بصيغة ⁨SHA-256⁩، يقرأ ترويستَي Range وIf-Range ويقرّر:

الشرط	الحالة	ملاحظات
لا `Range` منطبق، أو `If-Range` لا يطابق `ETag` القويّ الحالي	`200 OK`	الجسم الكامل. ولا يُكرَّم إلّا شكلُ `If-Range` بوسم الكيان القويّ (‏⁨RFC 9110 §13.1.5⁩).
وحدة نطاق غير معروفة أو `Range` غير صالح نحويًا	`200 OK`	تُتجاهَل الترويسة (‏⁨RFC 9110 §14.2⁩).
نطاق واحد قابل للإرضاء	`206 Partial Content`	يحمل `Content-Range`.
نطاقات متعدّدة قابلة للإرضاء	`206 Partial Content`	`multipart/byteranges` بحدّ فاصل مُشتقّ.
نطاقات بايتات صالحة، لا يُرضى أيٌّ منها	`416 Range Not Satisfiable`	يحمل `Content-Range: bytes */length` (‏⁨RFC 9110 §15.3.7⁩).

تُعلِن كلُّ استجابة Accept-Ranges: bytes وETag القويّ. وتضبط استجابتا 200 و206 أيضًا Content-Type وContent-Length.

يقبل تحليلُ النطاق الوحدةَ bytes= فقط. وهو يدعم first-last الصريح، وfirst- المفتوح النهاية (مُثبَّتًا عند النهاية)، واللاحقة -N (آخر ⁨N⁩ بايتًا؛ ولاحقةٌ لا تقلّ عن التمثيل تنتقي كلَّه). و- المجرّدة (أو أي مواصفة مشوَّهة بخلاف ذلك) تجعل ترويسة Range بكاملها غير صالحة نحويًا، فتُتجاهَل الترويسة ويُرجَع تمثيل 200 OK الكامل. ولاحقة -0، أو أي مواصفة تكون إزاحتها الأولى عند النهاية أو بعدها، هي مواصفة غير قابلة للإرضاء وتُسقَط؛ وإن لم تكن أي مواصفة في الترويسة قابلة للإرضاء فالاستجابة 416 Range Not Satisfiable. وتُقارَن الإزاحات العشرية الكبيرة من دون الاعتماد على إشباع فيض الأعداد الصحيحة، فتُعالَج قيمة Range من 30 خانة بصورة مستقلّة عن المنصّة. وتُدمَج النطاقات المتداخلة القابلة للإرضاء قبل بناء أي جسم؛ وتُحفَظ النطاقات المتمايزة فعلًا (غير المتداخلة) كأجزاء متعدّدة الأجزاء منفصلة.

أنماط الفشل ونموذج الاستثناء

WebviewException واجهة علامة تمدّد Throwable؛ التقطها لمعالجة النظام الفرعي كلِّه بصورة موحَّدة. ويُنفِّذها كلا الاستثناءين الملموسين.

UnsupportedDocumentException (تمدّد InvalidArgumentException) — يرفعها LinearizedDocument::fromBytes() حين لا تكون البايتات مستندًا مُخطَّطًا خطّيًا قابلًا للاستخدام. البنّاءات المُسمّاة: notLinearized() (لا قاموس معامِلات /Linearized)، وlengthMismatch($declaredLength, $actualLength) (لا يطابق /L المُعلَن الطولَ الفعلي — مبتور، أو مُلحَق به عبر تحديث تزايدي بما يتجاوز /L، أو غير مطابق)، وmalformedFirstPageOffset($firstPageEndOffset, $length) (إزاحة /E ليست إزاحة موجبة داخل الملفّ).
RangeNotSatisfiableException (تمدّد OutOfRangeException) — خطأ التقطيع البرمجيّ، يرفعه ByteRange::__construct() وLinearizedDocument::slice() / firstPageByteRange() حين يقع نطاق شامل خارج المستند. البنّاء المُسمّى: outOfBounds($firstByte, $lastByte, $length).

لا يرمي مُجيبُ ⁨HTTP⁩ RangeNotSatisfiableException لترويسات Range من العميل — فنطاق ⁨HTTP⁩ غير القابل للإرضاء هو استجابة 416 (‏⁨RFC 9110 §15.3.7⁩)، لا استثناء. وذلك الاستثناء محجوز للتقطيع البرمجيّ المباشر، حيث يكون الطلب خارج الحدود خطأَ مُستدعٍ. ويرمي ByteRangeResponder::__construct() استثناء InvalidArgumentException عاديًا (لا WebviewException) حين يحتوي contentType المُهيَّأ على محارف تحكُّم.

تصليب ضدّ حرمان الخدمة

يحدّ المُجيب عددَ النطاقات المدموجة المتمايزة المُكرَّمة لكلّ طلب (صنف تضخيم النطاق متعدّد الأجزاء، ‏⁨Apache HTTPD CVE-2011-3192⁩). وحين يطلب طلبٌ نطاقات مدموجة أكثر من الحدّ، أو بايتات إجمالية أكثر من التمثيل كاملًا، يُتجاهَل Range ويُرجَع 200 كامل. ويُشتقّ الحدّ الفاصل متعدّد الأجزاء حتميًّا ويُعاد اشتقاقه حتى يُضمَن ألّا يظهر داخل الجسم، فيُحفَظ المخرَج القابل للاستنساخ مع استبعاد تصادم الحدّ الفاصل.

المطابقة

يتبع سلوك نطاق البايتات ⁨RFC 9110⁩ (‏⁨HTTP Semantics⁩): ⁨§14⁩ (طلبات النطاق)، و⁨§13.1.5⁩ (If-Range)، و⁨§14.4⁩ (Content-Range)، و⁨§15.3.7⁩ (416). وتخطيط المستند المُخطَّط خطّيًا هو نموذج ⁨Fast Web View⁩ في ⁨ISO 32000-2 Annex F⁩. ولا تؤكّد الوحدة أي مُعرِّفات بنود خارجية إضافية تتجاوز السلوك الذي تتحقّق منه اختباراتها.

الحالات الحدّية وسلوك وضع ⁨FIPS⁩

يقدّم respondToBytes() نطاقات على بايتات اعتباطية حين لا تكون دلالات الصفحة الأولى لازمة.
مُحقِّق If-Range بتاريخ ⁨HTTP⁩ يُعامَل كعدم تطابق ← 200 كامل (يعيد العميل ببساطة الجلب).
ETag هو بصمة ⁨SHA-256⁩ تُستخدَم بحتًا كمُحقِّق ذاكرة مؤقّتة قويّ؛ ولا تؤدّي هذه الوحدة أي توقيع أو عمليات تشفير أخرى ولا تُعرِّف أي سلوك خاصّ بـ⁨FIPS⁩.

حدود النشر

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