PHPアプリをONLYOFFICE Docsに接続して編集内容を保存する

カスタムPHPアプリケーションは、ONLYOFFICE Docsが取得できるドキュメントURLを提供し、ブラウザでDocs JavaScript APIをロードし、編集されたファイルを保存するコールバックを受け入れることで、ONLYOFFICE Docsと連携します。PHPサーバー上でJWT署名を行い、ドキュメントURLとコールバックURLの両方がONLYOFFICE Docsが稼働しているネットワークからアクセスできるようにしてください。

統合エラーの多くは、ブラウザ、PHP、ドキュメントサーバーが認識するアドレスが混同されていることが原因です。各ルートを、そのルートを使用するネットワークからテストしてください。

PHPアプリとドキュメントサーバーを準備する

ONLYOFFICE Docsはドキュメントエディタを提供します。アプリケーションはドキュメントマネージャーおよびストレージサービスとして機能します。つまり、ユーザー認証、開くことができるファイルの決定、ソースファイルの提供、結果の保存を行います。Document Serverは別途インストールし、/healthcheckアプリケーションコードのデバッグを行う前にエンドポイントを確認してください。

設定には、到達可能なアドレスを3つ使用してください。

• ドキュメントURL：ユーザーのブラウザがエディタとそのJavaScript APIを読み込むために使用するアドレス。
• ドキュメントURL：ドキュメントサーバーがPHPストレージからソースファイルをダウンロードするために使用できる絶対アドレス。
• コールバックURL：ドキュメントサーバーが編集後にPOSTを送信できる絶対アドレス。PHPが変更内容を保存できるようにするため。

例えば、https://docs.example.comはエディタを提供し、 はhttps://app.example.com/files/42/downloadPHPhttps://app.example.com/onlyoffice/callbackを指します。ブラウザから Docs および Docs から 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検証がデフォルトで有効になっています。Docsで設定されているブラウザトークンシークレットと一致するシークレットを使用してエディタ設定に署名してください。セットアップで別の送信トークンシークレットを使用している場合は、その送信ボックスシークレットを使用してコールバックも検証してください。Docs 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を安全にエンコードするjson_encodeか、同一オリジンエンドポイントから署名付き設定を取得してください。信頼できない値をJavaScriptに連結しないでください。署名ガイドにはHMAC-SHA256が記載されています。ロードバランシングされたDocs 8.1以降では、APIスクリプトにshardkeyドキュメントに記載されているクエリパラメータを含めることができますが、単一サーバーでは必要ありません。

PHPコールバックを介して変更を保存します

編集後、ドキュメントサーバーはPOSTリクエストを送信しますcallbackUrl。ステータス2は編集が完了し、ファイルの保存準備が整ったことを意味します。ステータス6は強制保存の結果です。コールバックには、編集済みファイルの一時的なダウンロードURLが含まれています。この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: BearerJWTヘッダーとそれに一致する送信ボックスシークレットを前提としています。サーバーが異なるヘッダーまたはボディトークンを使用している場合は、適宜修正してください。ダウンロードヘルパーは、Docsホストのみを許可し、応答を確認して、期待されるファイルを安全に置き換える必要があります。任意のURLや署名されていないドキュメントキーを信頼しないでください。

保存が成功したら、JSON を返します{"error":0}。ステータスとペイロードについてはコールバックのリファレンスを、コールバックのタイミングについては保存ライフサイクルを参照してください。

往復旅行全体を確認してください

認証済みユーザーとしてテスト用のDOCXファイルを開き、簡単な編集を行った後、エディタを閉じます。コールバックキーとステータスが目的のファイルと一致していることを確認し、アプリが新しいバイトを保存したことを確認してから、ドキュメントを再度開きます。読み込みに失敗した場合は、APIスクリプトのルートと構成トークンを確認してください。保存に失敗した場合は、コールバックの到達可能性、JWTの検証、JSONレスポンス、およびPHPストレージログを確認してください。

ONLYOFFICEはPHP統合の例とPHPサンプルアプリを公開していますが、サンプル統合にはストレージ認証や保存リクエスト検証といった本番環境向けの保護機能が欠けていることを明示的に警告しています。これらのサンプルはAPIフローを理解するために使用し、アクセスチェックやコールバックのセキュリティは独自のアプリケーションで実装してください。