วิธีผสานรวม ONLYOFFICE Docs กับแอปพลิเคชัน PHP ที่พัฒนาขึ้นเอง

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

หมายเหตุเกี่ยวกับเวอร์ชันที่เกี่ยวข้อง: ONLYOFFICE ประกาศ Docs 9.4 เมื่อวันที่ 19 พฤษภาคม 2026 การประกาศดังกล่าวระบุว่า รุ่น Community Edition แบบโอเพนซอร์สได้ยกเลิกข้อจำกัดการเชื่อมต่อพร้อมกัน 20 รายการเดิมแล้ว โดยเริ่มตั้งแต่เวอร์ชัน 9.4 เป็นต้นไป การเปลี่ยนแปลงนี้ส่งผลต่อข้อควรพิจารณาในการใช้งานสำหรับผู้ใช้รุ่น Community Edition หนึ่งข้อ แต่ยังคงมีความจำเป็นต้องมีพื้นที่จัดเก็บข้อมูลและเอนด์พอยต์สำหรับการเรียกกลับที่เข้าถึงได้ การลงนาม JWT หรือการตรวจสอบใบอนุญาต โปรดตรวจสอบข้อกำหนดการเผยแพร่และใบอนุญาตสำหรับเวอร์ชัน Docs ที่คุณวางแผนจะใช้งาน การผสานรวมด้านล่างนี้เป็นไปตามขั้นตอนการทำงานของ API Docs ที่ระบุไว้ในเอกสารปัจจุบัน

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

ก่อนที่คุณจะเชื่อมต่ออะไรก็ตาม

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

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

ขั้นตอนที่ 1: กำหนดเส้นทางเอกสารและเครือข่าย

เริ่มต้นด้วยการทำให้เอกสารสามารถเข้าถึงได้ที่ URL ที่เสถียรและแน่นอน ซึ่ง Docs สามารถดึงข้อมูลได้ อย่าชี้ตัวแก้ไขไปยังเส้นทางเซสชัน PHP หรือ URL สัมพัทธ์ที่ใช้ได้เฉพาะในเบราว์เซอร์เท่านั้น แต่ให้สร้างเส้นทางแอปพลิเคชันที่ต้องมีการตรวจสอบสิทธิ์ เช่นhttps://app.example.com/docs/42/downloadก่อนที่จะส่งข้อมูลกลับมา เส้นทางนั้นควรตรวจสอบสิทธิ์การเข้าถึงเอกสาร 42 ของผู้ใช้ที่ลงชื่อเข้าใช้ หากเซิร์ฟเวอร์ Docs ไม่สามารถใช้เซสชันเบราว์เซอร์ของผู้ใช้ซ้ำได้ ให้กำหนด URL ดาวน์โหลดแบบจำกัดขอบเขตที่มีอายุสั้น หรือกลไกการอนุญาตแบบเซิร์ฟเวอร์ต่อเซิร์ฟเวอร์อื่น

นอกจากนี้ ให้สร้างเส้นทางเรียกกลับ (callback route) เช่นhttps://app.example.com/onlyoffice/callback?document=42โดยจะต้องรับคำขอ POST จากเซิร์ฟเวอร์ Docs ระบุไฟล์เป้าหมายได้อย่างปลอดภัย และสามารถเข้าถึงได้จากเครือข่ายของเซิร์ฟเวอร์ Docs พารามิเตอร์ URL ที่ Docs ส่งกลับมานั้นเป็นลิงก์ดาวน์โหลดชั่วคราวสำหรับเอกสารที่แก้ไขแล้ว ไม่ใช่ไฟล์ที่บันทึกไว้ในฐานข้อมูลของคุณ เส้นทางเรียกกลับของคุณต้องดึงข้อมูลเหล่านั้นและเขียนลงในพื้นที่จัดเก็บของคุณ

ONLYOFFICE อธิบายว่าบริการแก้ไขเอกสารและบริการจัดเก็บเอกสารเป็นส่วนที่แยกจากกัน: Docs ให้บริการแก้ไขเอกสาร ในขณะที่ตัวรวมระบบให้บริการจัดการเอกสารและพื้นที่จัดเก็บ โปรดดูภาพรวม "วิธีการทำงาน" อย่างเป็นทางการก่อนเลือกอุปกรณ์ปลายทางและการออกแบบเครือข่ายของคุณ

ขั้นตอนที่ 2: สร้างการตั้งค่าตัวแก้ไขใน PHP

สำหรับการตั้งค่าเอกสาร Word จะระบุประเภทไฟล์ต้นฉบับ รหัสเอกสารที่ไม่ซ้ำกัน ชื่อเรื่อง URL สำหรับดาวน์โหลด โหมดแก้ไข และ URL สำหรับการเรียกกลับ รหัสเอกสารมีความสำคัญ เพราะช่วยให้ 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 Web Token (JWT) ที่ลงนามแล้ว ซึ่งเป็นรูปแบบมาตรฐานสำหรับการพิสูจน์ว่าการกำหนดค่ามาจากเซิร์ฟเวอร์ที่เก็บความลับร่วมกัน ความลับในการลงนามจะอยู่บนเซิร์ฟเวอร์ PHP ห้ามใส่ไว้ใน JavaScript หรือ HTML เด็ดขาด

ชื่อโค้ดdocsDownloadUrl(), callbackUrl(), และeditingKey()เป็นเมธอดของแอปพลิเคชัน ไม่ใช่ฟังก์ชัน PHP ในตัวของ ONLYOFFICE การใช้งานที่แน่นอนขึ้นอยู่กับระบบจัดเก็บข้อมูล เฟรมเวิร์กเว็บ และโมเดลการควบคุมการเข้าถึงของคุณ ONLYOFFICE เผยแพร่ SDK การรวม PHP อย่างเป็นทางการและตัวอย่างหลายภาษา แต่ในที่เก็บข้อมูลระบุอย่างชัดเจนว่าแอปพลิเคชันสาธิตเป็นตัวอย่างทดสอบที่ต้องมีการเปลี่ยนแปลงในการใช้งานจริง โปรดตรวจสอบคู่มือลายเซ็น JWT อย่างเป็นทางการและตัวอย่างการรวมระบบอย่างเป็นทางการ

ขั้นตอนที่ 3: โหลด Docs API และแสดงผลตัวแก้ไข

แสดงการตั้งค่าที่ลงชื่อแล้วลงในหน้าเว็บหลังจากที่เส้นทาง PHP อนุญาตผู้ใช้แล้วเท่านั้น หลีกเลี่ยงอักขระพิเศษใน JSON สำหรับบริบท JavaScript และทำให้คอนเทนเนอร์ตัวแก้ไขมีความสูงเพียงพอที่จะใช้งานได้ เบราว์เซอร์จะดึงข้อมูลapi.jsจากเซิร์ฟเวอร์เอกสารของคุณ ตัวสร้างจะแทนที่องค์ประกอบตัวยึดตำแหน่งด้วย 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

ขั้นตอนที่ 4: บันทึกการอัปเดตผ่านฟังก์ชันเรียกกลับ

เมื่อการแก้ไขสิ้นสุดลง Docs จะส่งคำขอ POST ไปยัง ค่า editorConfig.callbackUrlในstatusคำขอจะกำหนดว่าตัวจัดการของคุณควรทำอะไร สถานะ 2 หมายความว่าเอกสารพร้อมที่จะบันทึกหลังจากปิดการแก้ไข สถานะ 6 หมายความว่าสถานะปัจจุบันได้รับการบันทึกแล้วผ่านการบันทึกแบบบังคับ ในขณะที่เซสชันการแก้ไขยังคงดำเนินต่อไปได้ ค่าอื่นๆ บ่งบอกถึงสถานะการเชื่อมต่อ ไม่มีการเปลี่ยนแปลง หรือข้อผิดพลาด อย่าถือว่าทุกการเรียกกลับเป็นไฟล์ใหม่

ตัวจัดการการเรียกกลับควรแยกวิเคราะห์เนื้อหา JSON ตรวจสอบความถูกต้องของคำขอตามการตั้งค่ากล่องขาออก JWT ที่เปิดใช้งานบนเซิร์ฟเวอร์ Docs ของคุณ แมปการเรียกกลับไปยังเอกสารที่การผสานรวมปัจจุบันเป็นเจ้าของ และจัดการสถานะการบันทึกอย่างรอบคอบ เมื่อสถานะเป็น 2 หรือ 6 ให้ดาวน์โหลดไฟล์ที่ส่งมาurlจากเซิร์ฟเวอร์ Docs ตรวจสอบว่าการดาวน์โหลดสำเร็จ และแทนที่ไฟล์ที่จัดเก็บไว้โดยอัตโนมัติ เพื่อป้องกันไม่ให้การดาวน์โหลดบางส่วนทำให้ไฟล์ต้นฉบับเสียหาย ส่งคืนการตอบสนองการเรียกกลับที่ API ปัจจุบันคาดหวัง ซึ่งโดยทั่วไปจะเป็นออบเจ็กต์ JSON ที่errorตั้งค่าเป็น true 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 ยืนยันว่าการเรียกกลับ (callback) มาถึงแล้ว และเส้นทางจัดเก็บข้อมูลของคุณได้ดาวน์โหลดไฟล์ที่ส่งกลับมาเรียบร้อยแล้ว
4. เปิดไฟล์อีกครั้งจากแอปพลิเคชันและตรวจสอบว่าการเปลี่ยนแปลงยังคงอยู่หรือไม่ ทดสอบการปิดไฟล์โดยไม่มีการเปลี่ยนแปลงและการแก้ไขพร้อมกันอีกโปรแกรมหนึ่งแยกต่างหาก

คู่มือขั้นตอนการบันทึกอย่างเป็นทางการระบุว่า ในกรณีส่วนใหญ่ การบันทึกจะเสร็จสมบูรณ์ประมาณ 10 วินาทีหลังจากแก้ไขเสร็จสิ้น ขนาดไฟล์ ความซับซ้อน เวลาในการแปลง และประสิทธิภาพของเซิร์ฟเวอร์อาจส่งผลต่อความล่าช้า อย่าแจ้งว่า "บันทึกแล้ว" ให้ผู้ใช้ทราบเพียงเพราะ iframe ของตัวแก้ไขปิดลง ตรวจสอบการเรียกกลับและการแก้ไขที่บันทึกไว้แล้ว

ความล้มเหลวในการบูรณาการที่พบบ่อย

• โปรแกรมแก้ไขเปิดขึ้นแต่ไม่สามารถโหลดไฟล์ได้:โปรดทดสอบdocument.urlจากเครือข่ายเซิร์ฟเวอร์ของเอกสาร ไม่ใช่แค่จากเบราว์เซอร์บนเดสก์ท็อปของคุณเท่านั้น
• JWT ถูกปฏิเสธ:เปรียบเทียบข้อมูลลับและการกำหนดค่า HS256 ทั้งสองฝั่ง ยืนยันว่าโทเค็นลงนามในออบเจ็กต์การกำหนดค่าที่ส่งมาอย่างถูกต้อง
• การเปลี่ยนแปลงจะหายไป:ตรวจสอบความสามารถในการเข้าถึงการเรียกกลับ การจัดการสถานะ การดึง URL ดาวน์โหลดชั่วคราว และสิทธิ์ในการแทนที่ไฟล์
• ปรากฏเวอร์ชันเก่า:สร้างรหัสเอกสารใหม่หลังจากบันทึกการแก้ไข และหลีกเลี่ยงการแสดง URL แหล่งที่มาที่แคชไว้โดยไม่ตั้งใจ
• ใช้งานได้ในเครื่องโลคอล แต่ใช้งานไม่ได้ในสภาพแวดล้อมจริง:ตรวจสอบเส้นทางของรีเวิร์สพร็อกซี ใบรับรอง TLS DNS ของคอนเทนเนอร์ กฎไฟร์วอลล์ และชื่อโฮสต์สาธารณะเทียบกับชื่อโฮสต์ภายในที่ใช้ในแต่ละ URL

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