Pro الإصدار

الإسقاط — مرجع متعمّق

لمحة سريعة

هذه الصفحة هي المرجع المتعمّق لوحدة ⁨Projection⁩ في ⁨Pro⁩. توثّق السطح العام لعمليات ⁨tokenize⁩ و⁨emit⁩ و⁨round-trip⁩، وبوابة النية، ودلالات دورة الذهاب والإياب لمجرى المحتوى. يحلّل ContentProjectionWriter مجرى محتوى ⁨PDF⁩ لفظيًّا إلى قائمة رموز مسطّحة ومرتّبة، ثم يعيد تسلسل قائمة الرموز إلى مجرى محتوى جديد. النموذج أحادي الاتجاه: يُنتج الإصدار مجرى جديدًا، ولا يعدّل الأصل في مكانه أبدًا.

ملاحظة. يُقصد بـ«⁨Projection⁩» هنا إسقاط رموز مجرى المحتوى، وليس الإسقاط الإحداثي أو الجغرافي المكاني.

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

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

لا توجد راية ترخيص لكل ميزة على حدة. هذه قدرة من إصدار ⁨Pro⁩. يتطلّب الإصدار إضافةً إلى ذلك وسيطًا صريحًا من نوع ProjectionIntent يفرضه نظام الأنواع، لا مفتاح ترخيص.

سطح واجهة ⁨API⁩ العامة

composer require nextpdf/pro:^3

توجد الوحدة في مساحة الأسماء NextPDF\Pro\Projection. جميع العمليات على ContentProjectionWriter ساكنة (⁨static⁩).

الرمز	المعاملات	السلوك الافتراضي	يُرجع	يُطلق أو يفشل بـ	ملاحظات
`ContentProjectionWriter::tokenize`	`string $contentStream`	يحلّل المجرى لفظيًّا إلى قائمة رموز مسطّحة ومرتّبة؛ يطبّع المسافات البيضاء، ويُسقط التعليقات، ويتخطّى البايتات غير المعروفة	`list<ContentToken>`	لا شيء؛ البايتات المشوّهة أو التحكّمية تُتخطّى ولا تُرفض	للقراءة فقط؛ لا يتطلّب نية.
`ContentProjectionWriter::emit`	`list<ContentToken> $tokens`, `ProjectionIntent $intent`	يُسلسِل الرموز إلى مجرى محتوى جديد؛ الخرج مستقلّ عن قيمة النية	`string`	لا شيء في الجسم؛ الوسيط المفقود أو غير `ProjectionIntent` يفشل عند حدّ الأنواع	النية بوابة عند موضع الاستدعاء، لا مفتاح زمن تشغيل.
`ContentProjectionWriter::roundTrip`	`string $contentStream`	يرمِّز ثم يعيد الإصدار دون أي تعديل؛ بوابة التحقّق	`string`	لا شيء	الخرج ليس مطابقًا على مستوى البايت؛ يُحفَظ تسلسل العوامل (⁨operators⁩) وقيم المعامِلات (⁨operands⁩).
`ContentToken::__construct`	`ContentTokenType $type`, `string\|int\|float\|bool\|null $value = null`	يبني رمزًا غير قابل للتغيير؛ لا يُجري أي تحقّق	`ContentToken`	لا شيء؛ `$value` غير المتوافق نوعيًّا يفشل عند حدّ الأنواع	`readonly`؛ `type` و`value` عامّان.
`ContentToken::isTextOperator`	—	يبيّن ما إذا كان الرمز عامل نص (⁨BT, ET, Tj, TJ, Td, TD, Tm, T*, Tf, Tc, Tw, Tz, TL, Tr, Ts⁩, `'`, `"`)	`bool`	لا شيء؛ يُرجع `false` للرموز غير العاملية	—
`ContentToken::isTextShowingOperator`	—	يبيّن ما إذا كان الرمز عامل إظهار نص (⁨Tj, TJ⁩, `'`, `"`)	`bool`	لا شيء؛ يُرجع `false` للرموز غير العاملية	مجموعة فرعية من عوامل النص.
`ContentTokenType`	— (تعداد ذو دعم نصي)	يعدّد مُميِّزات الرموز: ⁨LiteralString, HexString, Number, Name, Operator, ArrayBegin, ArrayEnd, DictBegin, DictEnd, Boolean, Null⁩	—	—	القيم الداعمة معرّفات مستقرّة.
`ProjectionIntent`	— (تعداد صِرف)	يعدّد نيّتَي الإصدار المسموحتين: ⁨Sanitization, SteganographicEmbedding⁩	—	—	لا حالة عامة، لذا يُبلّغ التحليل الساكن عن أي استخدام غير مُعلَن.

public static function tokenize(string $contentStream): array
public static function emit(array $tokens, ProjectionIntent $intent): string
public static function roundTrip(string $contentStream): string

enum ProjectionIntent
{
    case Sanitization;
    case SteganographicEmbedding;
}

public function __construct(
    public ContentTokenType $type,
    public string|int|float|bool|null $value = null,
) {}

public function isTextOperator(): bool
public function isTextShowingOperator(): bool

عقد السلوك

يحلّل ContentProjectionWriter::tokenize($contentStream) المجرى لفظيًّا إلى list<ContentToken> مسطّحة ومرتّبة. يغطّي السلاسل الحرفية، والسلاسل الست عشرية، والأسماء، والأعداد، ومحدِّدات المصفوفات والقواميس، والقيم المنطقية، والقيمة الخالية (⁨null⁩)، والعوامل. تُستهلَك المسافات البيضاء والتعليقات وتُسقَط؛ البايت غير المعروف يقدّم المؤشّر دون إنتاج رمز. هذا المرور للقراءة فقط ولا يحتاج نية.

يُسلسِل emit($tokens, $intent) قائمة رموز عائدةً إلى بايتات مجرى المحتوى ويتطلّب ProjectionIntent. النية إعلان عند موضع الاستدعاء فقط: البايتات المُصدَرة متطابقة بصرف النظر عن الحالة المُمرَّرة. تحتفظ الأعداد بتمييزها بين الصحيح والعشري — تُصدَر الأعداد الصحيحة حرفيًّا، وتُصدَر الأعداد العشرية بما يصل إلى ستّة أرقام كسرية مع اقتطاع الأصفار اللاحقة. تُعاد جدولة هروب السلاسل الحرفية، وتُصدَر السلاسل الست عشرية بأحرف كبيرة، وتحمل الأسماء الشَّرطة المائلة البادئة. يتبع كلَّ عامل سطرٌ جديد؛ وتكبح محدِّدات المصفوفات والقواميس الفاصلَ المجاور.

يرمِّز roundTrip($contentStream) ثم يعيد الإصدار دون أي تغيير. هو بوابة التحقّق: أكّد نتيجةً نظيفة قبل الوثوق بأي تسلسل تعديل-وإصدار. الخرج ليس مطابقًا للمدخل على مستوى البايت — تُطبَّع المسافات البيضاء وتزول التعليقات — لكن يُحفَظ تسلسل العوامل وقيم المعامِلات.

لِـProjectionIntent حالتان اثنتان بالضبط: Sanitization (تنقيح مُتلِف وغير قابل للعكس) وSteganographicEmbedding (تضمين حمولة مخفية). لا توجد حالة عامة، لذا يمكن للتحليل الساكن أن يُبلّغ عن أي إصدار يفتقر إلى غرض مُعلَن ومعروف. ContentToken قيمة readonly غير قابلة للتغيير تحمل مُميِّز type وقيمة value مفكوكة الترميز؛ ويصنّف isTextOperator() وisTextShowingOperator() الرموز العاملية ويُرجعان false لكل رمز غير عاملي.

الحالات الحدّية وأنماط الفشل

أكّد دورة ذهاب وإياب نظيفة قبل أي تسلسل تعديل-وإصدار. عامِل دورةَ الذهاب والإياب الفاشلة كشرط توقّف.
نية Sanitization غير قابلة للعكس. الرموز المُزالة غائبة عن الخرج ولا يمكن استرجاعها منه.
النية لا تغيّر الخرج. يُنتج emit() البايتات نفسها لكلتا الحالتين؛ الوسيط بوابة عند موضع الاستدعاء. يطبّق المستدعي تعديلات التنقيح والإخفاء بتغيير قائمة الرموز قبل الإصدار.
يطبّع المُصدِر المسافات البيضاء ويُسقط التعليقات، لذا تختلف المقارنة على مستوى البايت مع الأصل حتى لدورة ذهاب وإياب غير مُعدَّلة.
تُنسَّق المعامِلات العشرية بستّة أرقام كسرية على الأكثر ثم تُقتطع. القيم التي تحتاج دقّة أكبر تُقرَّب عند الإصدار؛ والأعداد الصحيحة مضبوطة تمامًا.
تشمل هروبات السلاسل الحرفية المدخلة المفكوكة \n و\r و\t و\b و\f، والمحدِّدات المهروبة، وهروبات ثمانية تصل إلى ثلاثة أرقام مقيّدة إلى بايت واحد.
السلسلة الست عشرية ذات عدد الأرقام الفردي تُحشى بصفر لاحق عند الإدخال، مطابقةً لقاعدة ⁨ISO⁩ للسلاسل الست عشرية.
البايتات المشوّهة أو التحكّمية تُتخطّى ولا تُرفض؛ ولا يُطلق tokenize() أي استثناء على المدخل غير المتوقّع.
لا تُجري هذه الوحدة أي عمليات تعمية ولا تُعرّف أي سلوك خاصّ بـ ⁨FIPS⁩.

المطابقة

يعامل الترميز المجرى كتسلسل من العوامل والمعامِلات بصياغة كائنات ⁨PDF⁩ القياسية، وفق ⁨ISO 32000-2:2020, 8.2⁩. يتبع تجميع البايتات إلى رموز أصناف المحارف اللفظية في ⁨ISO 32000-2:2020, 7.2⁩. تُحشى السلسلة الست عشرية ذات الطول الفردي بصفر في الرقم الأخير، وفق ⁨ISO 32000-2:2020, 7.3.4.3⁩. هذه البنود مسجّلة في سجلّ الاستشهادات لهذه الصفحة.

تصف هذه العبارات القدرة مقابل البنود المُستشهَد بها. لا تملك ⁨NextPDF⁩ أي شهادة مطابقة، ودعم بندٍ ما ليس ادّعاء اعتماد.

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

متوفّر منذ إصدار الوحدة ⁨1.10.0⁩؛ العمليات الثلاث جميعها نقاط دخول ساكنة على ContentProjectionWriter.
تكلفة ⁨tokenize⁩ و⁨emit⁩ خطّية بطول مجرى المحتوى. لا يوجد رقم إنتاجية منشور؛ فقِس بمجارٍ تمثيلية.
نموذج الرموز المسطّح — رمز واحد لكل عنصر لفظي، لا مُجمَّع حسب العامل — هو ما يتيح التعديلات الجراحية مثل ضبط عدد واحد داخل مصفوفة ⁨TJ⁩. تُوجد التمثيلات المُجمَّعة حسب العامل في مواضع أخرى من شجرة ⁨Pro⁩ وهي خارج النطاق هنا.
ContentToken غير قابل للتغيير. ابنِ قائمة مُعدَّلة بإنشاء رموز جديدة بدلًا من تغيير الرموز القائمة.
أبقِ بوابة دورة الذهاب والإياب في خطّ أنابيبك: roundTrip() الناجح هو الشرط المسبق الذي صُمّمت الوحدة حوله قبل أي تعديل مُتلِف.

حدود النشر

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