الدمج

لمحة سريعة

يدمج ⁨NextPDF\Pro\Merge\SmartMerger⁩ عدّة ملفّات ⁨PDF⁩ في ملف واحد، ثم يطبّق تحسينات ⁨Pro⁩: شجرة إشارات مرجعية موحَّدة من تسميات كل مدخل، وإزالة الصفحات المكرَّرة بتجزئة المحتوى، واختيار نطاق الصفحات لكل مدخل. ويجري تجميع المستند الأساسي عبر محرّك دمج الرسم البياني للكائنات في ⁨Pro⁩. فهو يعيد ترقيم كل مدخل في فضاء كائنات واحد ويكتب جدول إحالات مرجعية حقيقيًا.

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

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

تتوفّر أصناف الدمج كلّما كانت حزمة ⁨Pro⁩ مثبَّتة. ولا يضبط هذه الوحدة أي علم قدرة في وقت التشغيل.

التثبيت

composer require nextpdf/pro:^3

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

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

يتحكّم ⁨SmartMergeConfig⁩ في التحسينات:

• توحيد الإشارات المرجعية يدرج مدخل مخطّط واحدًا لكل مدخل مُسمّى، يشير إلى بداية قسم ذلك المدخل. ويتبع هذا نموذج ⁨/Outlines⁩ في كتالوج المستند وفق ⁨ISO 32000-2:2020 §7.7.2⁩.
• إزالة الصفحات المكرَّرة يزيل الصفحات المكرَّرة المتطابقة بايتيًا عبر المدخلات، مقارَنةً بتجزئة المحتوى.
• إعادة كتابة الروابط يمسح إجراءات ⁨GoTo⁩ الداخلية في المخرَج المدمَج.

يُبلِّغ ⁨SmartMergeResult⁩ عن البايتات المدمَجة إضافةً إلى إحصاءات: إجمالي الصفحات، وعدد المصادر، وحجم المخرَج، والإشارات المرجعية المُضافة، والمكرَّرات المُزالة، والروابط المُكتشَفة، وتسميات المدخلات مرتَّبةً.

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

دمج ملفّات ⁨PDF⁩ ليس تسلسلًا بايتيًا: فكل مدخل يحمل أرقام كائناته، وجدول إحالاته المرجعية، وشجرة صفحاته الخاصة، فالوصل الساذج لا يُحمَّل في أي قارئ مطابق. لذلك يفوّض ⁨SmartMerger⁩ التجميع الأساسي إلى محرّك الرسم البياني للكائنات في ⁨Pro⁩ (⁨PdfSplitter::mergeDocuments()⁩)، الذي يعيد ترقيم كل مدخل في فضاء كائنات متّصل واحد، ويعيد بناء شجرة صفحات واحدة، ويُصدِر جدول إحالات مرجعية حقيقيًا بإزاحات بايتية صحيحة. ثم تنطبق تحسينات ⁨Pro⁩ — توحيد الإشارات المرجعية، وإزالة المكرَّرات، واكتشاف الروابط — على ذلك المخرَج المُتحقَّق منه بدلًا من إعادة تنفيذ التجميع. وإزالة المكرَّرات على مستوى المستند كاملًا، ومعالجة الروابط بالاكتشاف فقط، حدودُ نطاق مقصودة تُبقي الدمج حتميًا وآمنًا على المدخلات غير الموثوقة.

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

عقد السلوك

• المدخل. قائمة غير فارغة من ⁨MergeInput⁩. وتثير القائمة الفارغة ⁨InvalidArgumentException⁩. ويُقيَّد عدد المدخلات وحجم بايتات كل مدخل بـ ⁨SmartMergeConfig⁩ (⁨maxInputs⁩، ⁨maxBytesPerInput⁩).
• المخرَج. ‏⁨SmartMergeResult⁩. تكون ⁨isValid()⁩ صحيحة حين يبدأ المخرَج بترويسة ⁨%PDF⁩.
• توحيد الإشارات المرجعية يضيف مدخلًا واحدًا لكل مدخل له تسمية غير فارغة، حين يكون ⁨consolidateBookmarks⁩ مُفعَّلًا.
• إزالة المكرَّرات اشتراكية (⁨deduplicatePages⁩، مُعطَّلة افتراضيًا) وتطابق الصفحات كاملةً بتجزئة المحتوى، لا الصفحات المتشابهة بصريًا.
• إعادة كتابة الروابط في الإصدار الحالي تكتشف إجراءات ⁨GoTo⁩ الداخلية وتعدّها؛ وهي لا تُجري إعادة حلّ كاملة للوجهات عبر المستندات. عامِل ⁨linksRewritten⁩ عدد اكتشاف.
• الحتمية. بالنسبة إلى مدخلات وإعداد متطابقَين يكون تدفّق البايتات المدمَج مستقرًّا، رهنًا بملف تعريف الحتمية الموثَّق لمحرّك دمج ⁨Pro⁩.

سطح الواجهة البرمجية (⁨API⁩) العام

النوع	الصنف	الأعضاء الرئيسية
⁨NextPDF\Pro\Merge\SmartMerger⁩	⁨final class⁩	⁨__construct(?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null)⁩، ⁨merge(array $inputs, SmartMergeConfig $config = new SmartMergeConfig()): SmartMergeResult⁩
⁨NextPDF\Pro\Merge\MergeInput⁩	⁨final readonly class⁩	⁨__construct(string $pdfData, array $pageRanges = [], string $label = '')⁩، ⁨hasPageRanges(): bool⁩
⁨NextPDF\Pro\Merge\SmartMergeConfig⁩	⁨final readonly class⁩	⁨__construct(bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000)⁩، ⁨default()⁩، ⁨basic()⁩
⁨NextPDF\Pro\Merge\SmartMergeResult⁩	⁨final readonly class⁩	⁨string $pdfData⁩، ⁨int $totalPages⁩، ⁨int $sourceCount⁩، ⁨int $bookmarksAdded⁩، ⁨int $duplicatesRemoved⁩، ⁨int $linksRewritten⁩، ⁨array $inputLabels⁩، ⁨isValid(): bool⁩، ⁨hasOptimizations(): bool⁩

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

<?php

declare(strict_types=1);

use NextPDF\Pro\Merge\MergeInput;
use NextPDF\Pro\Merge\SmartMerger;

$result = (new SmartMerger())->merge([
    new MergeInput(file_get_contents('cover.pdf'), label: 'Cover'),
    new MergeInput(file_get_contents('body.pdf'),  label: 'Body'),
]);

echo $result->totalPages, " pages, ",
     $result->bookmarksAdded, " bookmarks\n";

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

<?php

declare(strict_types=1);

use NextPDF\Pro\Merge\MergeInput;
use NextPDF\Pro\Merge\SmartMergeConfig;
use NextPDF\Pro\Merge\SmartMerger;

function assemblePacket(array $sections): string
{
    $inputs = [];
    foreach ($sections as $label => $bytes) {
        $inputs[] = new MergeInput($bytes, label: (string) $label);
    }

    $config = new SmartMergeConfig(
        consolidateBookmarks: true,
        deduplicatePages: true,
        rewriteLinks: false,
        maxInputs: 50,
    );

    $result = (new SmartMerger())->merge($inputs, $config);

    if (! $result->isValid()) {
        throw new RuntimeException('merge produced invalid output');
    }

    return $result->pdfData;
}

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

• المدخل الواحد صالح ويُدمَج إلى نسخة مُطبَّعة من ذلك المستند.
• تقارن إزالة المكرَّرات محتوى البايتات للصفحة كاملةً؛ والصفحات التي تختلف بالبيانات الوصفية أو ترقيم الكائنات فقط لا تُعامَل بوصفها مكرَّرات.
• يُطبَّق اختيار نطاق الصفحات على مدخل قبل ترتيب الدمج.
• ‏⁨linksRewritten⁩ عدد إجراءات مُكتشَفة، لا ضمان بأن كل هدف رابط عبر المستندات قد أُعيد توجيهه.

الأداء

تهيمن على الكلفة محرّك دمج ⁨Pro⁩ وتتناسب مع إجمالي بايتات المدخلات وعدد الصفحات. وتضيف إزالة المكرَّرات تجزئة محتوى واحدة لكل صفحة. وتمثّل مقدّمة ⁨performance_budget⁩ مرجع كل عملية دمج.

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

يُقيَّد عدد المدخلات وحجم كل مدخل بـ ⁨SmartMergeConfig⁩ للحدّ من استنزاف الموارد بمدخلات عدائية. ولا ينفّذ الدمج نصوص المستند المُضمَّنة. راجِع نموذج أمان ⁨Core⁩ لتصليب تحليل تدفّق البايتات.

المطابقة

الادّعاء	بند المواصفة	الحالة
إشارات مرجعية موحَّدة عبر ⁨/Outlines⁩	ISO 32000-2:2020 §7.7.2	مُتحقَّق منه (مجموعة اختبارات الوحدة)
إزالة الصفحات المكرَّرة بتجزئة المحتوى	—	مُتحقَّق منه (مجموعة اختبارات الوحدة)
إعادة حلّ كاملة للروابط عبر المستندات	—	غير مدعوم (اكتشاف فقط)

الرجوع إلى ⁨Core⁩ / البديل

للتسلسل الأساسي من دون توحيد ⁨Pro⁩، يكون ⁨NextPDF\Document\PdfMerger⁩ المفتوح المصدر في ⁨Core⁩ هو المسار المستقل المدعوم. ولا يفوّض ⁨SmartMerger⁩ إليه؛ إذ يعمل دمج ⁨Pro⁩ على محرّك الرسم البياني للكائنات الخاص به. راجِع /modules/core/document/.

ملاحظة عن حدّ ⁨Enterprise⁩

تُجري هذه الوحدة دمجًا بنيويًا. وهي لا تُجري تجميع حجز قانوني، أو حجبًا، أو تغليف سلسلة عهدة إثباتية؛ وتلك ليست موفَّرة هنا.

حدّ النشر

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

انظر أيضًا

• الدمج — مرجع معمّق
• جدول المحتويات
• الفروق
• نموذج مستند ⁨Core⁩