將 PHP 應用程式連接到 ONLYOFFICE Docs 並儲存編輯內容

一個自訂的 PHP 應用程式透過以下方式與 ONLYOFFICE Docs 整合：提供一個文件 URL，供 ONLYOFFICE Docs 取得；在瀏覽器中載入 ONLYOFFICE Docs 的 JavaScript API；以及接收一個回呼函數，該函數用於儲存已編輯的文件。 JWT 簽章保留在 PHP 伺服器上，並確保文件 URL 和回呼 URL 均可從 ONLYOFFICE Docs 運行所在的網路存取。

許多整合失敗都是由於瀏覽器、PHP 和文件伺服器看到的位址混淆造成的。請測試網路中使用該路由的每條路由。

準備 PHP 應用程式和文件伺服器

ONLYOFFICE Docs 提供文件編輯器。您的應用程式仍然負責文件管理和儲存服務：它負責驗證使用者身分、決定使用者可以開啟哪些文件、提供原始檔案並保存結果。請單獨安裝文檔伺服器，然後/healthcheck在調試應用程式程式碼之前驗證其端點。

配置中請使用三個可達位址：

• 文件 URL：使用者瀏覽器用於載入編輯器及其 JavaScript API 的位址。
• 文件 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 的規則，私人連結或本機連結也可能需要令牌。

有關必填欄位和 API 腳本路徑，請參閱 ONLYOFFICE 的文件配置參考和自架安裝指南。

載入編輯器並對其配置進行簽名

JWT 指的是 JSON Web Token，它是一種簽名令牌，用於讓 ONLYOFFICE 驗證配置在傳輸過程中是否已更改。目前部署中預設啟用 JWT 驗證；請使用文件中配置的匹配瀏覽器令牌金鑰對編輯器配置進行簽署。如果您的設定使用單獨的出站令牌金鑰，也請使用該出站金鑰驗證回呼。從文件 7.2 版本開始，Docker 安裝可以自動產生金鑰，因此請為生產環境設定並保留穩定的金鑰。

ONLYOFFICE 官方簽名指南展示了包含維護firebase/php-jwt包的 PHP 程式碼。使用以下命令安裝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_encode使用同源端點安全地對 JSON 進行編碼或取得已簽署的設定；不要將不受信任的值連接到 JavaScript 中。簽名指南中記錄了 HMAC-SHA256。對於負載平衡的 Docs 8.1 及更高版本，API 腳本可以包含文件中記錄的shardkey查詢參數；單一伺服器則不需要。

透過 PHP 回呼儲存更改

編輯完成後，文件伺服器會向目標伺服器傳送 POST 請求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]);

此範例假設使用預設的Authorization: BearerJWT 出站標頭和匹配的出站金鑰。如果您的伺服器使用不同的標頭或正文令牌，請進行相應調整。下載輔助程式應僅允許您的文件主機訪問，檢查回應，並安全地替換預期文件。切勿信任任意 URL 或未簽署的文件金鑰。

成功儲存後，返回包含以下內容的 JSON {"error":0}：。有關狀態和有效負載，請參閱回呼參考文件；有關回呼時間，請參閱儲存生命週期文件。

核實完整的往返行程

以授權使用者身分開啟一個測試 DOCX 文件，進行少量編輯，然後關閉編輯器。確認回調鍵和狀態與目標檔案匹配，驗證應用程式是否已儲存新位元組，然後重新開啟文件。如果載入失敗，請檢查 API 腳本路由和配置令牌；如果儲存失敗，請檢查回調可達性、JWT 驗證、JSON 回應和 PHP 儲存日誌。

ONLYOFFICE 發布了一個PHP 整合範例和一個 PHP 範例應用程序，但明確警告說，範例整合缺乏生產環境保護措施，例如儲存授權和保存請求驗證。請使用它們來了解 API 流程，然後保留您自己的應用程式的存取檢查和回呼安全性。