كيفية دمج مستندات ONLYOFFICE مع تطبيق PHP مخصص

ابدأ بتحديد حدود التكامل: لا يرسل تطبيق PHP مخصص بيانات المستند مباشرةً إلى المحرر. يقوم تطبيقك بمصادقة المستخدم، وتخزين الملف، وتقديم عنوان URL يمكن لخادم ONLYOFFICE Docs جلبه، وعرض نقطة نهاية رد نداء حيث يقوم Docs بنشر تحديثات الحفظ. يقوم المتصفح بتحميل نص برمجة Docs API وإنشاء محرر في عنصر الصفحة. يعمل هذا النمط مع خادم Docs مُستضاف ذاتيًا عندما يتمكن المتصفح وكلا الخادمين من الوصول إلى عناوين URL المطلوبة.

ملاحظة هامة بخصوص الإصدار: أعلنت ONLYOFFICE عن إصدار Docs 9.4 في 19 مايو 2026. ويشير الإعلان إلى أن الإصدار المجاني مفتوح المصدر (Community Edition) قد ألغى الحد الأقصى السابق للاتصالات المتزامنة البالغ 20 اتصالاً بدءًا من الإصدار 9.4. يُغيّر هذا الأمر أحد اعتبارات النشر لمستخدمي الإصدار المجاني؛ ولكنه لا يُلغي الحاجة إلى نقاط نهاية تخزين واستدعاء قابلة للوصول، أو توقيع JWT، أو مراجعة الترخيص. يُرجى مراجعة شروط الإصدار والترخيص الخاصة بإصدار Docs الذي تنوي نشره. يتبع التكامل الموضح أدناه تدفق واجهة برمجة تطبيقات Docs الموثقة حاليًا.

الرسوم التوضيحية الأربعة للشاشة هي أمثلة مفاهيمية، وليست لقطات شاشة للمنتج. قائمة المستندات وتصميم مشروع PHP خاصان بالتطبيق، وقد تختلف واجهة المحرر باختلاف إصدار Docs وإعداداته.

قبل توصيل أي شيء

أنت بحاجة إلى تطبيق PHP، وخادم ONLYOFFICE Docs، ووحدة تخزين مستندات يتحكم بها تطبيقك. يمكن تشغيل Docs وتطبيق PHP على مضيفين أو حاويات منفصلة. يجب أن يصل متصفح المستخدم إلى خادم Docs لتنزيل موارد المحرر. وبشكل منفصل، يجب أن يصل خادم Docs إلى عنوان URL الخاص بالمستندات وعنوان URL الخاص بالرد في تطبيقك. localhostغالبًا ما يفشل اسم مضيف مثل هذا في إعداد الحاوية لأنه يشير إلى الحاوية التي تُرسل الطلب، وليس إلى الخدمة الأخرى.

استخدم بروتوكول HTTPS للنقاط النهائية العامة، واحفظ رمز JWT السري خارج نظام التحكم في الإصدارات، وحدد كيفية ربط أذونات المستندات بمستخدمي تطبيقك. في بيئة التطوير المحلية، قد تحتاج إلى شبكة خاصة أو نفق خاص لتمكين Docs من جلب ملف التطوير؛ أما في بيئة الإنتاج، فيُفضل استخدام مسارات ثابتة وموثقة. يشرح دليل تثبيت Docker الرسمي لـ ONLYOFFICE Docs عملية التثبيت وتكوين JWT. تُعدّ الرموز السرية المذكورة أمثلة توضيحية فقط، استبدلها برمز سري خاص بك، وحافظ على اتساقها مع تكوين Docs الخاص بك.

الخطوة 1: تحديد مسارات المستندات والشبكة

ابدأ بتوفير المستند على عنوان URL ثابت ومطلق يمكن لـ Docs جلبه. لا تُوجّه المحرر إلى مسار جلسة PHP أو عنوان URL نسبي خاص بالمتصفح فقط. بدلاً من ذلك، أنشئ مسار تطبيق مُصادق عليه، مثل `<مسار التطبيق>` https://app.example.com/docs/42/download. قبل إعادة البيانات، يجب أن يتحقق هذا المسار من وصول المستخدم المُسجّل دخوله إلى المستند رقم 42. إذا لم يتمكن خادم Docs من إعادة استخدام جلسة متصفح المستخدم، فأصدر عنوان URL لتنزيل قصير الأجل ومحدود النطاق، أو استخدم آلية تفويض أخرى بين الخوادم.

أنشئ أيضًا مسار رد نداء، مثل `<مسار رد النداء>` https://app.example.com/onlyoffice/callback?document=42. يجب أن يستقبل هذا المسار طلب POST من خادم Docs، وأن يُحدد الملف المستهدف بشكل آمن، وأن يكون قابلاً للوصول إليه من شبكة خادم Docs. مُعامل URL الذي يُرسله Docs هو رابط تنزيل مؤقت للمستند المُعدَّل؛ وهو ليس الملف المحفوظ في قاعدة البيانات. يجب على رد النداء جلب هذه البيانات وكتابتها في وحدة التخزين.

يصف ONLYOFFICE خدمة التحرير وخدمة تخزين المستندات كجزأين منفصلين: يوفر Docs خدمة التحرير، بينما يوفر المكامل إدارة المستندات وتخزينها. راجع نظرة عامة "كيف يعمل" الرسمية قبل اختيار نقطة النهاية وتصميم الشبكة.

الخطوة الثانية: إنشاء إعدادات المحرر بلغة PHP

بالنسبة لمستند Word، يحدد الإعداد نوع ملف المصدر، ومفتاحًا فريدًا للمستند، والعنوان، ورابط التنزيل، ووضع التحرير، ورابط إعادة التوجيه. المفتاح مهم: فهو يسمح لـ Docs بتحديد جلسة التحرير وإعادة استخدام مستند مخزن مؤقتًا. أنشئ مفتاحًا جديدًا عند تحرير الملف وحفظه؛ وأعد استخدام المفتاح نفسه للعملاء الذين يُفترض بهم الانضمام إلى جلسة المستند النشطة نفسها. حافظ على المفتاح ضمن حدود الأحرف والطول المحددة في الوثائق.

يفترض المثال أدناه استخدام Composer ومكتبة Firebase PHP-JWT. استبدل كل مثال لعنوان URL وعملية البحث عن التخزين بخدماتك الخاصة التي تدعم المصادقة.

<?php
use Firebase\JWT\JWT;

$document = $documents->findForUser($documentId, $currentUser);

$config = [
    'document' => [
        'fileType' => 'docx',
        'key' => $document->editingKey(),
        'title' => $document->filename(),
        'url' => $document->docsDownloadUrl(),
        'permissions' => [
            'edit' => true,
        ],
    ],
    'documentType' => 'word',
    'editorConfig' => [
        'mode' => 'edit',
        'callbackUrl' => $document->callbackUrl(),
        'user' => [
            'id' => (string) $currentUser->id(),
            'name' => $currentUser->displayName(),
        ],
    ],
];

$config['token'] = JWT::encode($config, $onlyOfficeJwtSecret, 'HS256');

يجب document.urlأن يكون الملف قابلاً للقراءة من قِبل خادم Docs، وليس فقط من قِبل المتصفح. document.keyينبغي أن يتتبع الملف نسخة محفوظة: إذا أعدت استخدام مفتاح قديم بعد تغيير ملف المصدر، فقد يفتح Docs المحتوى المخزن مؤقتًا. الرمز المميز هو رمز ويب JSON مُوقّع (JWT)، وهو تنسيق قياسي لإثبات أن التكوين جاء من خادم يحتفظ بالسر المشترك. يبقى سر التوقيع على خادم PHP؛ لا تضعه أبدًا في JavaScript أو HTML.

أسماء الرموز هي دوال تطبيقية docsDownloadUrl()، callbackUrl()وليست editingKey()دوال PHP مدمجة في ONLYOFFICE. يعتمد التنفيذ الدقيق على نظام التخزين، وإطار عمل الويب، ونموذج التحكم في الوصول. تنشر ONLYOFFICE حزمة تطوير برمجية (SDK) رسمية للتكامل مع PHP وأمثلة متعددة اللغات، لكن المستودع يصف تطبيقاته التجريبية صراحةً بأنها أمثلة اختبارية تتطلب تعديلات في بيئة الإنتاج. راجع دليل توقيع JWT الرسمي وأمثلة التكامل الرسمية .

الخطوة 3: تحميل واجهة برمجة تطبيقات المستندات وعرض المحرر

لا تعرض الإعدادات الموقعة في الصفحة إلا بعد أن يُصادق مسار PHP على المستخدم. قم بتهريب JSON لسياق JavaScript، واجعل حاوية المحرر طويلة بما يكفي لتكون قابلة للاستخدام. يجلب المتصفح البيانات api.jsمن خادم Docs الخاص بك؛ ويستبدل المُنشئ عنصر العنصر النائب بإطار iframe للمحرر.

<div id="onlyoffice-editor" style="width:100%;height:900px"></div>
<script src="https://docs.example.com/web-apps/apps/api/documents/api.js"></script>
<script>
  const config = /* safely encoded JSON rendered by PHP */;
  const editor = new DocsAPI.DocEditor('onlyoffice-editor', config);
</script>

تُعرض الوسوم أعلاه كنموذج ترميز مُهَرَّب ليسهل قراءتها كشفرة برمجية. في صفحتك الفعلية، حمّل نص برمجة واجهة برمجة التطبيقات (API) من عنوان URL لخادم Docs الذي يُشغّل مُحرّرك. إذا كانت منطقة المُحرّر فارغة، فتأكد أولًا من أن المتصفح قادر على فتح عنوان URL هذا، وأن التطبيق وDocs يستخدمان شهادات HTTPS متوافقة، وأن أدوات مطوّري المتصفح لا تُظهر أي محتوى مختلط محظور أو طلبات شبكة. يشرح توثيق DocsAPI.DocEditor سلوك العنصر النائب والإطار المضمن (iframe).

الخطوة الرابعة: حفظ التحديثات من خلال رد الاتصال

عند انتهاء التحرير، يرسل Docs طلب POST إلى editorConfig.callbackUrl. statusتحدد القيمة الإجراء الذي يجب على معالجك اتخاذه. الحالة 2 تعني أن المستند جاهز للحفظ بعد إغلاق التحرير. الحالة 6 تعني أنه تم حفظ الحالة الحالية من خلال عملية حفظ إجبارية، بينما يمكن لجلسة التحرير الاستمرار. تشير القيم الأخرى إلى حالات الاتصال، أو عدم وجود تغيير، أو وجود خطأ؛ لا تتعامل مع كل رد نداء كملف جديد.

يجب على معالج الاستدعاء تحليل نص JSON، والتحقق من صحة الطلب وفقًا لإعدادات صندوق صادر JWT المُفعّلة على خادم المستندات، وربط الاستدعاء بمستند تملكه التكاملات الحالية، والتعامل مع حالات الحفظ بعناية. عند الحالة 2 أو 6، يتم تنزيل الملف المُرسل urlمن خادم المستندات، والتحقق من نجاح التنزيل، واستبدال الملف المخزن بشكل كامل حتى لا يؤدي التنزيل الجزئي إلى تلف الملف الأصلي. يُعاد رد الاستدعاء المتوقع من واجهة برمجة التطبيقات الحالية، وهو عادةً كائن JSON مُعيّن errorبعد 0المعالجة الناجحة.

<?php
$payload = json_decode(file_get_contents('php://input'), true);

// Verify the callback token as configured for your Docs server.
// Resolve the document from your own database; do not trust a user-supplied path.
$status = (int) ($payload['status'] ?? 0);

if (in_array($status, [2, 6], true) && !empty($payload['url'])) {
    $file = $storage->downloadFromDocs($payload['url']);
    $storage->replaceAtomically($document, $file);
}

header('Content-Type: application/json');
echo json_encode(['error' => 0]);

downloadFromDocs()وهي replaceAtomically()عناصر نائبة، وليست إجراءات إنتاج كاملة. استخدم عميل HTTP مع مهلة زمنية، وتحقق من TLS، وحدود لحجم الاستجابة، ووجهات خارجية مُتحكَّم بها؛ لا تجلب عنوان URL عشوائيًا دون ضمانات. تحقق من توقيع/رمز الاستدعاء باستخدام الطريقة الموثقة لإصدار Docs والتكوين المُستخدمين. يُدرج مرجع معالج الاستدعاء الرسمي الحالات ومتى يكون عنوان URL للملف المُعدَّل موجودًا.

اختبر مسار الحفظ الكامل

1. افتح ملف DOCX صغيرًا كمستخدم لديه إذن بتحريره.
2. قم بإجراء تغيير مرئي، وانتظر حتى يشير المحرر إلى أنه تم حفظه، ثم أغلق المستند.
3. افحص سجلات PHP و Docs. تأكد من وصول رد الاتصال وأن مسار التخزين الخاص بك قد قام بتنزيل الملف المُعاد.
4. أعد فتح الملف من التطبيق وتأكد من استمرار التغيير. اختبر إغلاق الملف دون حدوث أي تغيير، ثم اختبر محررًا ثانيًا يعمل في الوقت نفسه بشكل منفصل.

يشير دليل عملية الحفظ الرسمي إلى أن عملية الحفظ تكتمل في معظم الحالات بعد حوالي 10 ثوانٍ من انتهاء التحرير؛ وقد يؤثر حجم الملف وتعقيده ووقت التحويل وأداء الخادم على هذا التأخير. لا تُبلغ المستخدم بكلمة "تم الحفظ" لمجرد إغلاق إطار التحرير، بل تحقق من رد الاتصال والنسخة المحفوظة.

حالات فشل التكامل الشائعة

• يفتح المحرر ولكنه لا يستطيع تحميل الملف: اختبر ذلك document.urlمن شبكة خادم المستندات، وليس فقط من متصفح سطح المكتب الخاص بك.
• تم رفض JWT: قارن السر وتكوين HS256 على كلا الجانبين؛ تأكد من أن الرمز المميز يوقع كائن التكوين المحدد الذي يتم إرساله.
• تختفي التغييرات: تحقق من إمكانية الوصول إلى رد الاتصال، ومعالجة الحالة، وجلب عنوان URL للتنزيل المؤقت، وأذونات استبدال الملفات.
• يظهر الإصدار القديم: قم بإصدار مفتاح مستند جديد بعد مراجعة محفوظة وتجنب عرض عناوين URL المصدر المخزنة مؤقتًا عن غير قصد.
• يعمل محليًا، ويفشل في بيئة الإنتاج: افحص مسارات الوكيل العكسي، وشهادات TLS، ونظام أسماء النطاقات للحاوية، وقواعد جدار الحماية، واسم المضيف العام مقابل اسم المضيف الداخلي المستخدم في كل عنوان URL.

هذا هو المسار الأساسي لدمج ONLYOFFICE Docs مع تطبيق PHP مخصص: تخويل ملف المصدر وتقديمه، وتوقيع إعدادات محرر كل مستند، وعرض محرر واجهة برمجة التطبيقات الرسمية، ثم معالجة ردود الاستدعاء الخاصة بالحفظ بشكل آمن. يجب أن تتطابق تفاصيل الإنتاج - المصادقة، والتخزين، وتوقيع عنوان URL، والتحقق من ردود الاستدعاء، وسياسة التزامن - مع تطبيقك الخاص وإصدار Docs الذي تقوم بنشره.