เชื่อมต่อแอป PHP กับ ONLYOFFICE Docs และบันทึกการแก้ไข

แอปพลิเคชัน PHP ที่กำหนดเองจะผสานรวมกับ ONLYOFFICE Docs โดยการส่ง URL ของเอกสารที่ Docs สามารถดึงข้อมูลได้ โหลด JavaScript API ของ Docs ในเบราว์เซอร์ และรับการเรียกกลับ (callback) ที่เก็บไฟล์ที่แก้ไขแล้ว ควรคงการลงนาม JWT ไว้บนเซิร์ฟเวอร์ PHP และทำให้ทั้ง URL ของเอกสารและ URL ของการเรียกกลับสามารถเข้าถึงได้จากเครือข่ายที่ ONLYOFFICE Docs ทำงานอยู่

ความล้มเหลวในการผสานรวมหลายอย่างเกิดจากการสับสนของที่อยู่เครือข่ายที่เบราว์เซอร์ PHP และเซิร์ฟเวอร์เอกสารมองเห็น ทดสอบแต่ละเส้นทางจากเครือข่ายที่ใช้งานอยู่

เตรียมแอปพลิเคชัน PHP และเซิร์ฟเวอร์เอกสาร

ONLYOFFICE Docs เป็นเพียงโปรแกรมแก้ไขเอกสารเท่านั้น แอปพลิเคชันของคุณยังคงทำหน้าที่เป็นตัวจัดการเอกสารและบริการจัดเก็บ โดยจะตรวจสอบสิทธิ์ผู้ใช้ ตัดสินใจว่าไฟล์ใดที่ผู้ใช้สามารถเปิดได้ จัดหาไฟล์ต้นฉบับ และบันทึกผลลัพธ์ ติดตั้ง Document Server แยกต่างหาก จากนั้นตรวจสอบ/healthcheckปลายทางของ Document Server ก่อนที่จะดีบักโค้ดแอปพลิเคชัน

ใช้ที่อยู่ IP ที่สามารถเข้าถึงได้สามแห่งในการตั้งค่าของคุณ:

• URL ของเอกสาร:ที่อยู่ซึ่งเบราว์เซอร์ของผู้ใช้ใช้ในการโหลดตัวแก้ไขและ API JavaScript ของตัวแก้ไขนั้น
• URL ของเอกสาร:ที่อยู่แบบสัมบูรณ์ที่เซิร์ฟเวอร์เอกสารสามารถใช้เพื่อดาวน์โหลดไฟล์ต้นฉบับจากที่เก็บข้อมูล PHP
• URL สำหรับการเรียกกลับ:ที่อยู่แบบสัมบูรณ์ที่เซิร์ฟเวอร์เอกสารสามารถส่งคำขอ POST ไปได้หลังจากแก้ไขเสร็จ เพื่อให้ PHP สามารถบันทึกการเปลี่ยนแปลงได้

ตัวอย่างเช่นhttps://docs.example.comสามารถใช้เป็นตัวแก้ไข ในขณะที่ ชี้ไป https://app.example.com/files/42/downloadยังhttps://app.example.com/onlyoffice/callbackPHP ทดสอบการเข้าถึงระหว่างเบราว์เซอร์กับเอกสาร และเอกสารกับ PHP ในการใช้งานจริงlocalhostหมายถึงเครื่องหรือคอนเทนเนอร์ปัจจุบัน ดังนั้นโดยปกติแล้วจึงเป็นที่อยู่ข้ามบริการที่ไม่ถูกต้อง

สร้างการกำหนดค่าเอกสารสำหรับไฟล์ที่ได้รับอนุญาต

สำหรับการเปิดไฟล์ที่ต้องมีการตรวจสอบสิทธิ์ ให้โหลดเมตาเดตาของไฟล์และสร้างการกำหนดค่าตัวแก้ไขบนแบ็กเอนด์ PHP ตั้งค่าส่วนขยายไฟล์ ชื่อไฟล์ URL ดาวน์โหลดแบบสัมบูรณ์ และคีย์เอกสาร รักษาคีย์นั้นให้คงที่สำหรับผู้แก้ไขพร้อมกันที่ใช้เวอร์ชันเดียวกัน เปลี่ยนคีย์เมื่อ 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 หากการตั้งค่าของคุณใช้รหัสลับ outgoing-token แยกต่างหาก ให้ตรวจสอบการเรียกกลับด้วยรหัสลับ outbox นั้นด้วย ตั้งแต่ Docs เวอร์ชัน 7.2 เป็นต้นไป การติดตั้ง Docker สามารถสร้างรหัสลับโดยอัตโนมัติได้ ดังนั้นควรตั้งค่าและเก็บรักษารหัสลับที่เสถียรสำหรับการใช้งานจริง

คู่มือการลงลายเซ็นอย่างเป็นทางการของ ONLYOFFICE แสดงโค้ด PHP ที่ใช้firebase/php-jwtแพ็กเกจที่ได้รับการดูแลรักษา ติดตั้งโดยใช้คำสั่ง `npm install` 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.jsและส่ง JSON ที่ลงนามแล้วไปยัง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หรือดึงการกำหนดค่าที่ลงนามแล้วจากปลายทางต้นทางเดียวกัน อย่ารวมค่าที่ไม่น่าเชื่อถือเข้ากับ JavaScript คู่มือ การลงนามอธิบาย HMAC-SHA256 สำหรับ Docs 8.1 และเวอร์ชันที่ใหม่กว่าที่มีการโหลดบาลานซ์ สคริปต์ API สามารถรวมshardkeyพารามิเตอร์การค้นหาที่ระบุไว้ในเอกสารได้ เซิร์ฟเวอร์เดี่ยวไม่จำเป็นต้องใช้พารามิเตอร์นี้

บันทึกการเปลี่ยนแปลงผ่านฟังก์ชันเรียกกลับของ PHP

หลังจากแก้ไขเสร็จแล้ว Document Server จะส่งคำขอ POST ไปยังcallbackUrlสถานะ 2 หมายถึงการแก้ไขเสร็จสมบูรณ์และไฟล์พร้อมที่จะบันทึก สถานะ 6 คือผลลัพธ์การบันทึกแบบบังคับ ฟังก์ชันเรียกกลับจะรวม URL สำหรับดาวน์โหลดไฟล์ที่แก้ไขแล้วชั่วคราว ดาวน์โหลดไฟล์นั้นและแทนที่เวอร์ชันที่จัดเก็บไว้โดยอัตโนมัติ หรือสร้างเวอร์ชันใหม่ตามนโยบายการแก้ไขของแอปของคุณ ส่งคืนค่า{"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]);

ตัวอย่างนี้ใช้Authorization: Bearerส่วนหัว JWT ขาออกเริ่มต้นและรหัสลับกล่องขาออกที่ตรงกัน ปรับเปลี่ยนหากเซิร์ฟเวอร์ของคุณใช้ส่วนหัวหรือโทเค็นเนื้อหาที่แตกต่างกัน ตัวช่วยดาวน์โหลดควรอนุญาตเฉพาะโฮสต์เอกสารของคุณ ตรวจสอบการตอบสนอง และแทนที่ไฟล์ที่คาดหวังอย่างปลอดภัย อย่าเชื่อถือ URL ที่ไม่น่าเชื่อถือหรือคีย์เอกสารที่ไม่ได้ลงนาม

หลังจากบันทึกสำเร็จแล้ว ให้ส่งคืน JSON ที่มีข้อมูล{"error":0}. โปรดดูเอกสารอ้างอิงการเรียกกลับสำหรับสถานะและข้อมูลที่จะส่ง และวงจรชีวิตการบันทึกสำหรับช่วงเวลาการเรียกกลับ

ตรวจสอบการเดินทางไปกลับทั้งหมด

เปิดไฟล์ DOCX สำหรับทดสอบในฐานะผู้ใช้ที่ได้รับอนุญาต ทำการแก้ไขเล็กน้อย แล้วปิดตัวแก้ไข ตรวจสอบว่าคีย์การเรียกกลับและสถานะตรงกับไฟล์ที่ต้องการ ตรวจสอบว่าแอปของคุณบันทึกไบต์ใหม่แล้ว จากนั้นเปิดเอกสารอีกครั้ง หากการโหลดล้มเหลว ให้ตรวจสอบเส้นทางสคริปต์ API และโทเค็นการกำหนดค่า หากการบันทึกล้มเหลว ให้ตรวจสอบการเข้าถึงการเรียกกลับ การตรวจสอบ JWT การตอบสนอง JSON และบันทึกการจัดเก็บ PHP

ONLYOFFICE เผยแพร่ตัวอย่างการผสานรวม PHPและแอปพลิเคชันตัวอย่าง PHP แต่เตือนอย่างชัดเจนว่าการผสานรวมตัวอย่างเหล่านี้ขาดการป้องกันในสภาพแวดล้อมการใช้งานจริง เช่น การอนุญาตการจัดเก็บข้อมูลและการตรวจสอบความถูกต้องของคำขอบันทึก ใช้ตัวอย่างเหล่านี้เพื่อทำความเข้าใจขั้นตอนการทำงานของ API จากนั้นให้คงการตรวจสอบการเข้าถึงและความปลอดภัยของการเรียกกลับในแอปพลิเคชันของคุณไว้