قم بتوصيل تطبيق PHP ببرنامج ONLYOFFICE Docs واحفظ التعديلات

يتكامل تطبيق PHP مخصص مع ONLYOFFICE Docs من خلال توفير رابط URL للمستند يمكن لـ Docs جلبه، وتحميل واجهة برمجة تطبيقات JavaScript الخاصة بـ Docs في المتصفح، واستقبال رد نداء يخزن الملف المُعدَّل. حافظ على توقيع JWT على خادم PHP، واجعل كلاً من رابط URL للمستند ورابط رد النداء قابلين للوصول من الشبكة التي يعمل عليها ONLYOFFICE Docs.

تنشأ العديد من حالات فشل التكامل من خلط العناوين التي يراها المتصفح وPHP وخادم المستندات. اختبر كل مسار من الشبكة التي يستخدمه.

قم بإعداد تطبيق PHP وخادم المستندات

يوفر ONLYOFFICE Docs محرر المستندات. ويبقى تطبيقك هو مدير المستندات وخدمة التخزين: فهو يُصادق على المستخدمين، ويُحدد الملفات التي يُمكنهم فتحها، ويُوفر ملف المصدر، ويحفظ النتيجة. ثبّت خادم المستندات بشكل منفصل، ثم تحقق من /healthcheckنقطة النهاية الخاصة به قبل تصحيح أخطاء كود التطبيق.

استخدم ثلاثة عناوين يمكن الوصول إليها في إعداداتك:

• عنوان URL للمستندات: العنوان الذي يستخدمه متصفح المستخدم لتحميل المحرر وواجهة برمجة تطبيقات JavaScript الخاصة به.
• عنوان URL للمستند: عنوان مطلق يمكن لخادم المستندات استخدامه لتنزيل ملف المصدر من وحدة تخزين PHP.
• عنوان URL لإعادة التوجيه: عنوان مطلق يمكن لخادم المستندات إرسال طلب POST إليه بعد التحرير حتى يتمكن PHP من تخزين التغييرات.

على سبيل المثال، https://docs.example.comيمكن تشغيل المحرر، بينما https://app.example.com/files/42/downloadيشير https://app.example.com/onlyoffice/callbackإلى PHP. اختبر إمكانية الوصول من المتصفح إلى Docs ومن Docs إلى PHP. في عملية النشر، localhostيُقصد بالجهاز أو الحاوية الحالية، لذا عادةً ما يكون عنوان الخدمة غير صحيح.

قم بإنشاء تكوين مستند لملف مُصرَّح به

لطلب فتح موثق، حمّل بيانات تعريف الملف وأنشئ إعدادات المحرر على خادم PHP. حدد امتداد الملف وعنوانه ورابط التنزيل المطلق ومفتاح المستند. حافظ على ثبات هذا المفتاح للمحررين المتزامنين من نفس الإصدار؛ غيّره عندما يستبدل PHP المصدر بإصدار جديد.

<?php
$config = [
  'documentType' => 'word',
  'document' => [
    'fileType' => 'docx',
    'key' => $document['revision_key'],
    'title' => $document['name'],
    'url' => 'https://app.example.com/files/42/download',
    'permissions' => ['edit' => true],
  ],
  'editorConfig' => [
    'callbackUrl' => 'https://app.example.com/onlyoffice/callback',
    'user' => ['id' => (string)$user['id'], 'name' => $user['name']],
  ],
];

فرض صلاحيات الملفات قبل إنشاء عنوان URL. لا تكشف بيانات اعتماد التخزين أو تتجاوز المصادقة؛ قد تتطلب الروابط الخاصة أو المحلية رمزًا مميزًا وفقًا لقواعد ONLYOFFICE.

راجع مرجع تكوين المستندات الخاص بـ ONLYOFFICE ودليل التثبيت الذاتي للاطلاع على الحقول المطلوبة ومسار برنامج API النصي.

قم بتحميل المحرر وتوقيع إعداداته

JWT اختصار لـ JSON Web Token، وهو رمز مميز مُوقّع يسمح لـ ONLYOFFICE بالتحقق من عدم تغيير الإعدادات أثناء النقل. يتم تفعيل التحقق من صحة JWT افتراضيًا في عمليات النشر الحالية؛ وقّع إعدادات المحرر باستخدام سرّ browser-token المطابق المُكوّن في Docs. إذا كان إعدادك يستخدم سرًّا منفصلًا للرمز الصادر، فتحقق من صحة ردود الاتصال باستخدام سرّ الصندوق الصادر هذا أيضًا. بدءًا من Docs 7.2، يمكن لعمليات تثبيت Docker إنشاء سرّ تلقائيًا، لذا عيّن أسرارًا ثابتة واحتفظ بها للإنتاج.

يُظهر دليل التوقيع الرسمي لـ ONLYOFFICE كود PHP مع firebase/php-jwtالحزمة المُدارة. ثبّتها باستخدام الأمر التالي composer require firebase/php-jwt، ثم وقّع على التكوين الكامل في الواجهة الخلفية قبل إعادته إلى الصفحة:

use Firebase\JWT\JWT;

$secret = getenv('ONLYOFFICE_JWT_SECRET');
if (!$secret) {
    throw new RuntimeException('ONLYOFFICE JWT secret is not configured');
}
$config['token'] = JWT::encode($config, $secret, 'HS256');

احتفظ بالسر بعيدًا عن شفرة المتصفح ونظام التحكم في المصدر. حمّل ملف https://docs.example.com/web-apps/apps/api/documents/api.jsJSON الموقّع ومرّره إلى DocsAPI.DocEditor:

<div id="editor"></div>
<script src="https://docs.example.com/web-apps/apps/api/documents/api.js"></script>
<script>
  new DocsAPI.DocEditor("editor", <?= $signedConfigJson ?>);
</script>

قم بتشفير JSON بأمان json_encodeأو استرجع التكوين المُوقّع من نقطة نهاية من نفس المصدر؛ لا تُدمج القيم غير الموثوقة في جافا سكريبت. يوثّق دليل التوقيع HMAC-SHA256. بالنسبة لإصدارات Docs 8.1 والإصدارات الأحدث المُوازنة للأحمال، يمكن أن يتضمن نص برمجة واجهة برمجة التطبيقات (API) مُعامل الاستعلام الموثّق shardkey؛ لا يحتاج خادم واحد إليه.

احفظ التغييرات من خلال دالة رد نداء PHP

بعد التحرير، يرسل خادم المستندات طلب POST إلى [عنوان URL callbackUrl]. الحالة 2 تعني اكتمال التحرير وجاهزية الملف للحفظ؛ أما الحالة 6 فتعني حفظ الملف قسرًا. يتضمن رد الاتصال رابط تنزيل مؤقت للملف المُعدَّل. قم بتنزيله واستبدل النسخة المخزنة به، أو أنشئ نسخة جديدة وفقًا لسياسة مراجعة تطبيقك. لا تُرجع أي بيانات {"error":0}إلا بعد نجاح عملية الكتابة إلى وحدة التخزين.

<?php
use Firebase\JWT\JWT;
use Firebase\JWT\Key;

$raw = file_get_contents('php://input');
$data = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
$auth = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
$token = preg_replace('/^Bearer\s+/i', '', $auth);
$claims = JWT::decode($token, new Key($outboxSecret, 'HS256'));
$verified = (array)($claims->payload ?? []);

if (($verified['key'] ?? '') !== ($data['key'] ?? '')) {
    http_response_code(401);
    exit;
}
$document = findDocumentByRevisionKey($verified['key']);
if (!$document) {
    http_response_code(404);
    exit;
}
if (in_array((int)$data['status'], [2, 6], true)) {
    downloadAndStoreFromDocs($data['url'], $document);
}
header('Content-Type: application/json');
echo json_encode(['error' => 0]);

يفترض هذا المثال استخدام رأس JWT الصادر الافتراضي Authorization: Bearerورمز التحقق من صندوق الصادر المطابق. عدّله إذا كان خادمك يستخدم رأسًا أو رمزًا مختلفًا في نص الطلب. يجب أن يسمح برنامج التنزيل فقط لمضيف Docs الخاص بك، ويتحقق من الاستجابة، ويستبدل الملف المتوقع بأمان. لا تثق أبدًا بعنوان URL عشوائي أو مفتاح مستند غير موقّع.

بعد إتمام عملية الحفظ بنجاح، يتم إرجاع بيانات JSON تحتوي على المعلومات المطلوبة {"error":0}. راجع مرجع الاستدعاء للاطلاع على الحالات والبيانات المُرسلة، ودورة حياة الحفظ لمعرفة توقيت الاستدعاء.

تحقق من الرحلة ذهابًا وإيابًا بالكامل

افتح ملف DOCX تجريبيًا كمستخدم مُصرَّح له، وأجرِ تعديلًا بسيطًا، ثم أغلق المحرر. تأكد من تطابق مفتاح الاستدعاء وحالته مع الملف المطلوب، وتحقق من أن تطبيقك قد خزَّن البيانات الجديدة، ثم أعد فتح المستند. إذا فشل التحميل، فتحقق من مسار نص برمجة واجهة برمجة التطبيقات ورمز التكوين؛ وإذا فشل الحفظ، فتحقق من إمكانية الوصول إلى الاستدعاء، والتحقق من صحة رمز JWT، واستجابة JSON، وسجلات تخزين PHP.

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