Pro الإصدار

Document

لمحة سريعة

تقسّم وحدة ⁨Document⁩ ملف ⁨PDF⁩ إلى مقاطع بحسب نطاق الصفحات وتُجمِّع حافظات ⁨PDF Portfolios⁩ (المجموعات) بأعمدة مخطّط قابلة للفرز. وكلتا العمليتين محدودتان ضد المُدخَل العدائي.

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

تُشحَن هذه الميزة في ⁨NextPDF Pro⁩ (nextpdf/pro) وتُفعَّل بمغلَّف ترخيص من طبقة ⁨Pro⁩. ولا يُحمِّل النشرُ الذي يفتقر إلى ذلك الاستحقاق أصنافَ هذه الميزة. ⁨Document⁩ جزء من إصدار ⁨Pro⁩، دون علم ترخيص منفصل لكل ميزة. قارِن الإصدارات واحصل على ترخيص.

التثبيت

composer require nextpdf/pro:^3

تقع الشيفرة ضمن فضاء الأسماء NextPDF\Pro\Document.

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

تُوفَّر قدرتان:

يستخرج PdfSplitter نطاقات الصفحات إلى مقاطع ⁨PDF⁩ قائمة بذاتها. يكتشف الصفحات بمسح كائنات الصفحات في المُدخَل الخام ويُغلِّف الصفحات المُختارة في فهرس وشجرة صفحات صغريين. يدعم التقسيم القائم على النطاق، والتقسيم بحجم ثابت (splitEvery)، واستخراج نطاق مفرد (extractPages).
يبني PdfPortfolio قاموس ⁨PDF Collection⁩ يجمع مرفقات الملفات بمخطّط مُعرَّف. يدعم أوضاع العرض البلاطية والتفصيلية والمخفية ويُصدِر قاموسًا صالحًا للتضمين في فهرس المستند.

لماذا يعمل بهذه الطريقة

تقسيم ملف ⁨PDF⁩ ليس تقطيعًا للبايتات. يشير كائن الصفحة إلى الموارد المشتركة والخطوط ومسارات المحتوى عبر مرجع غير مباشر. كما يرث /MediaBox و/Resources من أسلافه في شجرة الصفحات. لذا يعيد المُقسِّم بناء كل مقطع بوصفه رسمًا بيانيًا للكائنات قائمًا بذاته: يجتاز الإغلاق المرجعي المتعدّي للصفحات المُختارة، ويُجسِّد السمات الموروثة، ويعيد الترقيم في فضاء مُعرّفات جديد، ويكتب جدول مرجعية متقاطعة بإزاحات دقيقة على مستوى البايت. اجتياز الإغلاق محدود، لأن رسمًا بيانيًا عدائيًا متشعّبًا قد يجرّ لولا ذلك عملًا غير محدود إلى مقطع واحد. تُفتح النتيجة بوصفها ملف ⁨PDF⁩ صالحًا قائمًا بذاته، لا شظية بمراجع معلّقة.

خلفية التصميم: تشريح ملف ⁨PDF⁩.

عقد السلوك

يفرض PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000) حدًّا لحجم المُدخَل وحدًّا لعدد النطاقات، ويرفض المُدخَل الذي لا يبدأ برأس ⁨PDF⁩.
يرفض splitEvery($pdfData, $pagesPerSegment) حجم مقطع أقل من 1؛ وقد يحتوي المقطع الأخير على صفحات أقل.
يرفض PdfPortfolio أي وضع عرض غير البلاطي أو التفصيلي أو المخفي عند الإنشاء.
يُعيد addSchema() وaddEntry() الحافظة للتسلسل الانسيابي؛ ويُعيد generateCollectionDictionary() سلسلة قاموس المجموعة.
تُنقَّى أسماء حقول المخطّط للاستخدام بوصفها كائنات اسم ⁨PDF⁩؛ وتُهرَّب قيم السلاسل لأجل سلاسل ⁨PDF⁩ الحرفية.

مثال شيفرة — بداية سريعة

ما يلي يعكس الـ ⁨API⁩ العام الموثَّق. لا يشحن المستودع أي مثال قابل للتشغيل لهذه الوحدة.

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$result = (new PdfSplitter())->split($pdfBytes, [new PageRange(1, 5)]);

مثال شيفرة — إنتاج

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$splitter = new PdfSplitter();

try {
    $result = $splitter->split(
        $pdfBytes,
        [new PageRange(1, 10), new PageRange(11, 20)],
        maxBytes: 50_000_000,
        maxRanges: 100,
    );
} catch (\InvalidArgumentException $e) {
    // Input rejected (not a PDF, or limits exceeded).
}

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

يعيد المُقسِّم بناء كل مقطع بوصفه رسمًا بيانيًا جديدًا للكائنات بجدول مرجعية متقاطعة حقيقي ودقيق على مستوى البايت؛ والمقاطع ملفات ⁨PDF⁩ صالحة قائمة بذاتها. وهو يعيد الترقيم في فضاء مُعرّفات جديد بدلًا من الحفاظ على تخطيط بايتات المصدر، لذا مرِّر بايتات المقطع إلى وحدة ⁨Writer⁩ لأجل سير عمل التحديث التزايدي أو التوقيع.
النطاق الذي لا يطابق أي صفحات يُنتج مقطعًا صغريًا من صفحة واحدة بدلًا من خطأ.
يتخذ فرز الحافظة افتراضيًا أول حقل في المخطّط، تصاعديًا.

الأداء

التقسيم وتجميع الحافظة خطّيان بحجم المُدخَل وعدد المدخلات. سقف المُدخَل الافتراضي هو 100 ⁨MB⁩ وسقف النطاق الافتراضي هو 1000؛ وكلاهما قابل للضبط من قِبل المستدعي نحو الأسفل. قِس بمستندات تمثيلية.

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

عامِل المُدخَل بوصفه غير موثوق. تحدّ حُرّاس الحجم والعدد استخدام الموارد. تُنقّي الوحدة أسماء الحقول وتُهرِّب قيم السلاسل قبل وصولها إلى قاموس المخرَج. ولا تُسجّل أي محتوى مستند.

المطابقة

يتبع قاموس الحافظة نموذج ⁨PDF Collections⁩ ويتبع المُقسِّم نموذج كائن الصفحة المُعرَّف في ⁨ISO 32000-2⁩؛ ويُحاشي المصدر البنود ذات الصلة. كان مجموعة ⁨RAG⁩ غير متاحة وقت التأليف، لذا لا تؤكّد هذه الصفحة أي مُعرّفات بنود خارجية وتحصر بيانات المطابقة في السلوك المُتحقَّق منه باختبارات الوحدة.

ملاحظة حدود ⁨Enterprise⁩

لا يغيّر ⁨Enterprise⁩ سلوك ⁨Document⁩. يضيف ⁨Enterprise⁩ ميزات أرشفة وامتثال من طبقة أعلى موثَّقة بشكل منفصل؛ وهي ليست مطلوبة للتقسيم أو لتجميع الحافظة.

احتياط ⁨Core⁩ / بديله

بدون ⁨Pro⁩، استخدم بدائيات المستند الأساسية في ⁨NextPDF Core⁩؛ والتقسيم بنطاق الصفحات وتجميع الحافظة إضافتان في ⁨Pro⁩. انظر /modules/document/.

حدود النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح الـ ⁨API⁩ العام المدعوم فقط. أما مسارات فضاءات الأسماء الداخلية والأصناف المساعدة وجداول الآليات وأسماء ملفات أدلة التشغيل وبادئات التذاكر فخارج النطاق.