如何將 ONLYOFFICE Docs 與自訂 PHP 應用程式集成

首先，我們需要明確整合邊界：自訂 PHP 應用程式不會直接將文件位元組傳送到編輯器。您的應用程式需要驗證使用者身分、儲存檔案、提供一個 ONLYOFFICE Docs 伺服器可以存取的 URL，並公開一個回呼端點，用於 Docs 發布並保存更新。瀏覽器會載入 Docs API 腳本，並在頁面元素中建立一個編輯器。當瀏覽器和伺服器都能存取所需的 URL 時，此模式適用於自架的 Docs 伺服器。

相關版本說明：ONLYOFFICE 於 2026 年 5 月 19 日發布了 Docs 9.4 版本。公告稱，開源社群版從 9.4 版本開始取消了先前的 20 個並發連線限制。這改變了社群版用戶部署時需要考慮的一個方面；但這並不意味著可以存取儲存和回調端點、JWT 簽名或授權審核都已取消。請查看您計劃部署的 Docs 版本的特定發布和授權條款。以下整合遵循目前文件中記錄的 Docs API 流程。

這四張螢幕截圖僅為概念範例，並非實際產品截圖。文件清單和 PHP 專案佈局因應用程式而異，編輯器介面也可能因 Docs 版本和配置而異。

在連接任何裝置之前

您需要一個 PHP 應用程式、一個 ONLYOFFICE Docs 伺服器以及由您的應用程式控制的文件儲存。 Docs 伺服器和 PHP 應用程式可以運行在不同的主機或容器中。使用者的瀏覽器必須存取 Docs 伺服器才能下載其編輯器資源。同時，Docs 伺服器也必須存取您應用程式的文件 URL 和回呼 URL。localhost在容器環境中，類似 `/example.com` 這樣的主機名稱通常會失效，因為它指向的是發出請求的容器，而不是其他服務。

對公共端點使用 HTTPS，將 JWT 金鑰保存在原始碼控制之外，並確定文件權限如何對應到應用程式使用者。對於本機開發，可能需要私有網路或隧道，以便文件可以取得開發文件；生產環境應使用穩定且經過驗證的路由。 ONLYOFFICE Docs 官方 Docker 安裝指南解釋了安裝和 JWT 配置。其範例金鑰僅供參考－請將其替換為私有金鑰，並使其與您的文件配置保持一致。

步驟 1：定義文件和網路路由

首先，確保文件位於一個穩定的絕對 URL 上，以便 Docs 可以取得該文件。請勿將編輯器指向 PHP 會話路徑或僅限瀏覽器存取的相對 URL。相反，創建一個經過身份驗證的應用程式路由，例如 `/ https://app.example.com/docs/42/downloadetc/docs ...

此外，還需要建立一個回呼路由，例如 `<callback_route> https://app.example.com/onlyoffice/callback?document=42`。該路由必須能夠接收來自 Docs 伺服器的 POST 請求，安全地識別目標文件，並且能夠從 Docs 伺服器網路存取。 Docs 伺服器返回的 URL 參數是已編輯文件的臨時下載鏈接，而不是資料庫中保存的文件。您的回調路由必須取得這些位元組並將其寫入您的儲存空間。

ONLYOFFICE 將編輯器和文件儲存服務視為兩個獨立的部分：Docs 提供編輯服務，而整合商提供文件管理和儲存服務。在選擇終端和網路設計之前，請參閱官方的「工作原理」概述。

步驟 2：使用 PHP 建置編輯器配置

對於 Word 文件，設定資訊包括來源文件類型、唯一的文檔鍵、標題、可下載 URL、編輯器模式和回呼 URL。文件鍵至關重要：它使 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金鑰，而不僅僅是瀏覽器可以讀取。此document.key密鑰應追蹤已儲存的版本：如果在來源檔案變更後重複使用過期的密鑰，則文件可能會開啟快取的內容。此令牌是經過簽署的 JSON Web Token (JWT)，這是一種用於證明配置來自持有共享金鑰的伺服器的標準格式。簽名金鑰保留在 PHP 伺服器上；切勿將其放入 JavaScript 或 HTML 中。

程式碼名稱 `<method name>` docsDownloadUrl()、callbackUrl()`<method name>` 和 ` editingKey()<method name>` 是應用程式方法，並非 ONLYOFFICE 內建的 PHP 函數。具體實現取決於您的儲存系統、Web 框架和存取控制模型。 ONLYOFFICE 發布了官方的 PHP 整合 SDK 和多語言範例，但其程式碼庫明確指出，演示應用程式僅為測試範例，需要進行生產環境的修改。請參閱官方 JWT 簽名指南和官方整合範例。

步驟 3：載入文件 API 並渲染編輯器

只有在 PHP 路由完成使用者授權後，才將簽名配置渲染到頁面中。對 JavaScript 上下文中的 JSON 進行轉義，並確保編輯器容器足夠高，以便於使用。瀏覽器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>

以上標籤以轉義後的範例標記形式顯示，以便可以將其視為程式碼。在您的實際頁面中，請從提供編輯器服務的文件伺服器的 URL 載入 API 腳本。如果編輯器區域為空白，請先確認瀏覽器可以開啟該 URL，應用程式和文件使用相容的 HTTPS 證書，且瀏覽器開發者工具未顯示任何被封鎖的混合內容或網頁要求。 DocsAPI.DocEditor文件解釋了佔位符和 iframe 的行為。

步驟 4：透過回呼儲存更新

編輯結束後，Docs 會向指定位址發送 POST 請求editorConfig.callbackUrl。該status請求的回傳值決定了您的處理程序應該執行的操作。狀態 2 表示編輯結束後文件已準備好儲存。狀態 6 表示目前狀態已透過強制儲存操作儲存，但編輯會話可以繼續。其他值表示連線狀態、無更改狀態或錯誤狀態；請勿將每次回呼視為新檔案。

回呼處理程序應解析 JSON 正文，根據文件伺服器上啟用的 JWT 寄件匣設定驗證請求，將回呼對應到目前整合擁有的文檔，並妥善處理儲存狀態。在狀態碼為 2 或 6 時，url從文件伺服器下載已發佈的文檔，驗證下載是否成功，並以原子方式替換已儲存的文件，以避免部分下載損壞原始檔案。傳回目前 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()只是佔位符，並非完整的生產流程。請使用具有逾時、TLS 驗證、回應大小限制和受控出站目標的 HTTP 用戶端；切勿在沒有任何安全措施的情況下取得任意 URL。請使用針對您執行的文件版本和配置所記錄的方法檢查回呼的簽名/令牌。官方回調處理程序參考文件列出了各種狀態以及何時存在已編輯文件 URL。

測試完整存檔路徑

1. 以具有編輯權限的使用者身分開啟一個小型的 DOCX 檔案。
2. 進行可見的更改，等待編輯器指示已儲存，然後關閉文件。
3. 檢查 PHP 和文檔日誌。確認回呼已到達，並且您的儲存路由已下載返回的檔案。
4. 從應用程式重新開啟文件，並確認更改仍然存在。分別測試不進行任何更改的關閉操作以及使用第二個編輯器同時開啟檔案的情況。

官方保存流程指南指出，大多數情況下，編輯結束後約 10 秒即可完成保存；檔案大小、複雜性、轉換時間和伺服器效能都可能影響保存延遲。不要僅僅因為編輯器 iframe 關閉就向使用者報告「已儲存」——務必驗證回調和已儲存的版本。

常見的整合故障

• 編輯器已打開，但無法從 Docs 伺服器的網路載入檔案test document.url，而不僅僅是從您的桌面瀏覽器載入。
• JWT 被拒絕：比較雙方的金鑰和 HS256 配置；確認令牌對所發送的配置物件進行簽署。
• 變更消失：檢查回呼可達性、狀態處理、暫時下載 URL 取得和檔案替換權限。
• 舊版出現：在儲存修訂後發出新的文件金鑰，避免意外提供快取的來源 URL。
• 本機運作正常，生產環境運作失敗：檢查反向代理路徑、TLS 憑證、容器 DNS、防火牆規則以及每個 URL 中使用的公用主機名稱與內部主機名稱。

這是將 ONLYOFFICE Docs 與自訂 PHP 應用程式整合的核心路徑：授權並提供原始文件，對每個文件的編輯器配置進行簽名，渲染官方 API 編輯器，然後安全地處理保存回調。生產環境的細節——身份驗證、儲存、URL 簽名、回調驗證和並發策略——必須與您自己的應用程式以及您部署的文件版本完全匹配。