Converter

لمحة سريعة

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

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

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

لا يحكم هذه الوحدة أي علم قدرة في وقت التشغيل. تُحَلّ أصناف ⁨Converter⁩ متى كانت حزمة ⁨Pro⁩ مثبَّتة ومُحمَّلة تلقائيًا.

التثبيت

composer require nextpdf/pro:^3

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

يحلّل ⁨Converter⁩ مُعامِلات إظهار النص داخل دفق محتوى ⁨PDF⁩ — Tj وTJ و' وفق ⁨ISO 32000-2:2020 §9.4⁩ — ويُعيد بناء تمثيل تقريبي لكل صفحة. يقرأ الوضع من مُعامِلَي النص Td وTm، وحجم الخط من Tf، ثم يُسقِط النقاط على إحداثيات المخرَج.

تُعرَض ثلاثة محوّلات، واحد لكل ConversionTarget:

• يُغلِّف PdfToHtmlConverter كل صفحة في حاوية موضوعة ويُصدِر عناصر <div> موضوعة بشكل مطلق لكل تتابع نصّي. المخرَج مستند ⁨HTML5⁩ قائم بذاته.
• يحلّل PdfToSvgConverter مجموعة محدودة من مُعامِلات الرسم (المستطيلات عبر re، والخطوط عبر m/l) إضافةً إلى النص، ويُصدِر عناصر <rect> و<line> و<text> المطابقة لصفحة واحدة.
• يستخرج PdfToTextConverter النص المُفكَّك فقط، صفحةً صفحةً، مفصولًا بعلامة فاصل صفحات.

هذا مُصدِّر محدود عمدًا. يُقرِّب وضع النص؛ ولا يُعيد التدفّق، ولا يُنقِّط، ولا يُعيد إنتاج المسارات المتجهية، أو التظليل، أو الاقتطاع، أو الشفافية، أو الصور المُضمَّنة. للحصول على عرض ⁨HTML⁩ إلى ⁨PDF⁩ كامل الدقّة في الاتجاه المعاكس، استخدم مسار ⁨HTML⁩ في ⁨Core.⁩

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

يُخزِّن ملف ⁨PDF⁩ النصّ بوصفه مُعامِلات إظهار محارف موضوعة، لا محارف دلالية، فلا يوجد نص مستند موثوق يمكن استرجاعه. لذا يمسح ⁨Converter⁩ مُعامِلات دفق المحتوى مباشرةً — Tj وTJ و'، إضافةً إلى Td وTm وTf للتموضع — ويُعيد بناء تخطيط تقريبي بدلًا من إعادة تدفّق الصفحة أو تنقيطها. هذا المسح المحدود هو ما يُبقي التصدير خطّيًا بطول البايتات، وحتميًا للمُدخَل المتطابق، وآمنًا على البايتات غير الموثوقة دون تنفيذ أي منطق مُضمَّن. كما يضع السقف الصادق: لا تُعيَّن المحارف عكسيًا إلى ⁨Unicode⁩، لذا تُصدَّر الخطوط ذات الترميز المخصّص بوصفها بايتات خام وتبقى الدقّة البصرية التامة خارج النطاق. خلفية التصميم: لماذا نصّ ملف ⁨PDF⁩ ليس نصًّا حقًّا.

عقد السلوك

• المُدخَل. بايتات ⁨PDF⁩ خام (string). السلسلة الفارغة تثير InvalidArgumentException.
• المخرَج. كائن قيمة ConversionResult يحمل السلسلة المُنتَجة، وConversionTarget، وعدد الصفحات المُعالَجة، وقياس زمن المعالجة.
• التغطية. استخراج النص (Tj/TJ/') هو المسار المُتحقَّق منه، المُختبَر بمجموعة الوحدات. يغطّي تصدير ⁨SVG⁩ المستطيلات والخطوط المستقيمة والنص فقط. لون حدّ ⁨RGB⁩ غير مُمرَّر بعدُ إلى مخرَج ⁨SVG.⁩
• الحتمية. لمُدخَل وتهيئة متطابقين، يكون دفق بايتات ⁨HTML⁩ أو ⁨SVG⁩ أو النص المُنتَج مستقرًّا. الحقل processingTimeMs قياس جداري وليس جزءًا من السطح الحتمي.
• الترميز. مخرَج ⁨HTML⁩ مُهرَّب بـ htmlspecialchars؛ ومخرَج ⁨SVG⁩ مُهرَّب بترميز ⁨XML.⁩ تُفكَّك تسلسلات هروب سلاسل ⁨PDF⁩ الشائعة (\n، \r، \t، \(، \)، \\) لأجل الهدف النصّي.

سطح الـ ⁨API⁩ العام

النوع	الصنف	الأعضاء الرئيسيون
NextPDF\Pro\Converter\PdfToHtmlConverter	final class	convert(string $pdfData, ?ConversionConfig $config = null): ConversionResult
NextPDF\Pro\Converter\PdfToSvgConverter	final class	convert(string $pdfData, int $pageIndex = 0, ?ConversionConfig $config = null): ConversionResult
NextPDF\Pro\Converter\PdfToTextConverter	final class	convert(string $pdfData): ConversionResult, extractPage(string $pdfData, int $pageIndex): string
NextPDF\Pro\Converter\ConversionConfig	final readonly class	__construct(ConversionTarget $target, bool $embedFonts = false, bool $embedImages = true, float $scaleFactor = 1.0, string $cssClass = 'pdf-page')
NextPDF\Pro\Converter\ConversionResult	final readonly class	string $output, ConversionTarget $target, int $pageCount, float $processingTimeMs, size(): int, isValid(): bool
NextPDF\Pro\Converter\ConversionTarget	enum	Html5, Svg, PlainText; mimeType(): string, fileExtension(): string

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

<?php

declare(strict_types=1);

use NextPDF\Pro\Converter\PdfToTextConverter;

$pdf    = file_get_contents('report.pdf');
$result = (new PdfToTextConverter())->convert($pdf);

echo $result->pageCount, " pages, ", $result->size(), " bytes of text\n";
echo $result->output;

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

<?php

declare(strict_types=1);

use NextPDF\Pro\Converter\ConversionConfig;
use NextPDF\Pro\Converter\ConversionTarget;
use NextPDF\Pro\Converter\PdfToHtmlConverter;

function exportPreview(string $pdfBytes): string
{
    if ($pdfBytes === '') {
        throw new InvalidArgumentException('empty PDF payload');
    }

    $config = new ConversionConfig(
        target: ConversionTarget::Html5,
        scaleFactor: 1.0,
        cssClass: 'doc-preview',
    );

    $result = (new PdfToHtmlConverter())->convert($pdfBytes, $config);

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

    return $result->output;
}

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

• ملف ⁨PDF⁩ بلا كتل نص BT/ET يُنتج مخرَجًا فارغًا أو غلاف صفحة فقط؛ وملفات ⁨PDF⁩ الممسوحة ضوئيًا (المؤلَّفة من صور فقط) لا تُنتج أي نص لأنه لا توجد خطوة تعرّف ضوئي على الحروف.
• يحوّل PdfToSvgConverter صفحة واحدة في المرّة، مُختارة بـ $pageIndex؛ والفهرس خارج النطاق يُنتج دفق صفحة فارغًا.
• الوضع تقريبي. النص الموضوع بتحويلات غير نصّية، أو النص المُدوَّر، أو تدفّق الأعمدة قد لا يُعيد إنتاج تخطيطه البصري الأصلي.
• لا يُطبَّق تعيين المحرف إلى ⁨Unicode⁩؛ والنص من خطوط تستخدم ترميزات مخصّصة قد يُصدَّر بوصفه تسلسل البايتات الخام.

الأداء

التحليل خطّي بطول بايتات الـ ⁨PDF.⁩ تتبع الذاكرة المُدخَل إضافةً إلى سلسلة المخرَج المُنتَجة. تُعدّ بيانات performance_budget الوصفية المرجعَ لكل استدعاء لمستند مكتبي اعتيادي.

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

يحلّل المحوّل بايتات ⁨PDF⁩ غير موثوقة بمسح محدود عبر strpos/substr على مُعامِلات النص؛ ولا يُنفّذ أي ⁨JavaScript⁩ مُضمَّن ولا يتبع المراجع الخارجية. عامِل ⁨HTML⁩ المُصدَّر بوصفه محتوى غير موثوق وهرّبه بما يناسب وجهته. انظر نموذج أمان ⁨Core.⁩

المطابقة

الادعاء	بند المعيار	الحالة
تحليل مُعامِل إظهار النص Tj	ISO 32000-2:2020 §9.4	مُتحقَّق منه (مجموعة وحدات)
تحليل مُعامِل إظهار نص المصفوفة TJ	ISO 32000-2:2020 §9.4	مُتحقَّق منه (مجموعة وحدات)
دقّة صفحة متجهية/نقطية كاملة	—	غير مدعوم (خارج النطاق)

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

لا يوجد مكافئ في ⁨Core⁩ لتصدير ⁨PDF.⁩ للاتجاه الأمامي (تأليف ⁨PDF⁩ من ⁨HTML⁩)، فإن مسار ⁨HTML⁩ مفتوح المصدر في ⁨Core⁩ هو المسار المدعوم. انظر /modules/core/html/.

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

‏⁨Converter⁩ مُصدِّر نص/أشكال من طبقة ⁨Pro.⁩ لا يُجري تعرّفًا ضوئيًا على الحروف، أو إعادة بناء دلالية، أو فهمًا للمستند. تلك شؤون منفصلة لا توفّرها هذه الوحدة.

حدود النشر

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

انظر أيضًا

• ⁨Converter⁩ — مرجع متعمّق
• ⁨Extraction⁩
• ⁨Diff⁩
• مسار ⁨HTML⁩ في ⁨Core⁩