ONLYOFFICE DocsをカスタムPHPアプリケーションと統合する方法

まず、統合の境界について説明します。カスタムPHPアプリケーションは、ドキュメントのバイトデータをエディタに直接送信しません。アプリケーションはユーザー認証を行い、ファイルを保存し、ONLYOFFICE Docsサーバーが取得できるURLを提供し、Docsが保存更新を送信するコールバックエンドポイントを公開します。ブラウザはDocs APIスクリプトを読み込み、ページ要素内にエディタを作成します。このパターンは、ブラウザと両方のサーバーが必要なURLにアクセスできる場合に、自己ホスト型のDocsサーバーでも機能します。

関連バージョン情報：ONLYOFFICEは2026年5月19日にDocs 9.4を発表しました。発表によると、オープンソースのCommunity Editionは9.4から同時接続数の20制限を撤廃しました。これにより、Communityユーザーにとって導入時の考慮事項が1つ変更されますが、アクセス可能なストレージとコールバックエンドポイント、JWT署名、ライセンスレビューの必要性は変わりません。導入予定のDocsビルドのリリースとライセンス条項を確認してください。以下の統合は、現在ドキュメント化されているDocs APIフローに従います。

掲載されている4つの画面図は概念的な例であり、実際の製品スクリーンショットではありません。ドキュメント一覧とPHPプロジェクトのレイアウトはアプリケーション固有のものであり、エディタのインターフェースはDocsのバージョンや構成によって異なる場合があります。

何かを接続する前に

PHPアプリケーション、ONLYOFFICE Docsサーバー、およびアプリケーションで制御されるドキュメントストレージが必要です。DocsとPHPアプリケーションは、別々のホストまたはコンテナで実行できます。ユーザーのブラウザは、エディタのアセットをダウンロードするためにDocsサーバーにアクセスする必要があります。また、Docsサーバーは、アプリケーションのドキュメントURLとコールバックURLにアクセスする必要があります。ホスト名がlocalhostコンテナ設定では失敗することがよくあります。これは、リクエストを行ったコンテナを指しており、他のサービスを指していないためです。

公開エンドポイントにはHTTPSを使用し、JWTシークレットはソース管理外に保存し、ドキュメントのアクセス許可をアプリケーションのユーザーにどのようにマッピングするかを決定します。ローカル開発では、Docsが開発ファイルを取得できるようにプライベートネットワークまたはトンネルが必要になる場合があります。本番環境では、安定した認証済みルートを使用する必要があります。ONLYOFFICE Docsの公式Dockerインストールガイドでは、インストールとJWTの設定について説明しています。サンプルシークレットはあくまで例です。実際のシークレットに置き換え、Docsの設定と一貫性を保ってください。

ステップ1：ドキュメントとネットワークの経路を定義する

まず、ドキュメントを Docs が取得できる安定した絶対 URL で利用できるようにします。エディタを PHP セッション パスやブラウザ専用の相対 URL に指定しないでください。代わりに、 などの認証済みアプリケーション ルートを作成しますhttps://app.example.com/docs/42/download。このルートは、バイトを返す前に、サインインしているユーザーがドキュメント 42 にアクセスできるかどうかを確認する必要があります。Docs サーバーがユーザーのブラウザ セッションを再利用できない場合は、有効期限の短いスコープ付きダウンロード URL または別のサーバー間認証メカニズムを発行します。

また、次のようなコールバック ルートを作成してくださいhttps://app.example.com/onlyoffice/callback?document=42。このルートは、Docs サーバーからの POST リクエストを受け入れ、対象ファイルを安全に識別し、Docs サーバー ネットワークからアクセス可能である必要があります。Docs が返信する URL パラメータは、編集されたドキュメントの一時的なダウンロード リンクであり、データベースに保存されたファイルではありません。コールバックでは、これらのバイトを取得してストレージに書き込む必要があります。

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()はアプリケーション メソッドであり、ONLYOFFICE の組み込み PHP 関数ではありません。具体的な実装は、ストレージ システム、Web フレームワーク、およびアクセス制御モデルによって異なります。ONLYOFFICE は公式の PHP 統合 SDK と多言語の例を公開していますが、リポジトリにはデモ アプリケーションが本番環境での変更が必要なテスト 例であると明記されています。公式の JWT 署名ガイドと公式の統合例を確認してください。

ステップ3：Docs 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>

上記のタグは、コードとして読み取れるようにエスケープされたサンプルマークアップとして表示されています。実際のページでは、エディターを提供する Docs サーバーの URL から API スクリプトを読み込んでください。エディター領域が空白の場合は、まず、ブラウザがその URL を開けること、アプリと Docs が互換性のある HTTPS 証明書を使用していること、およびブラウザの開発者ツールでブロックされた混合コンテンツまたはネットワーク要求がないことを確認してください。プレースホルダーと iframe の動作については、DocsAPI.DocEditor のドキュメントを参照してください。

ステップ4：コールバックを通じて更新を保存する

編集が終了すると、Docs は に POST リクエストを送信しますeditorConfig.callbackUrl。このstatus値によって、ハンドラーが実行すべき処理が決まります。ステータス 2 は、編集終了後にドキュメントを保存する準備が整ったことを意味します。ステータス 6 は、編集セッションを継続できる状態で、強制保存操作によって現在の状態が保存されたことを意味します。その他の値は、接続状態、変更なし、またはエラー状態を示します。すべてのコールバックを新しいファイルとして扱わないでください。

コールバック ハンドラは、JSON ボディを解析し、Docs サーバーで有効になっている JWT アウトボックス設定に従ってリクエストを検証し、コールバックを現在の統合が所有するドキュメントにマッピングし、保存状態を意図的に処理する必要があります。ステータス 2 または 6 の場合、投稿されたドキュメントを Docs サーバーurlからダウンロードし、ダウンロードが成功したことを確認し、部分的なダウンロードによって元のファイルが破損しないように、保存されたファイルをアトミックに置き換えます。現在の API が期待するコールバック レスポンスを返します。通常は、処理が成功した後にerrorに設定されたJSON オブジェクトです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とDocsのログを確認してください。コールバックが到着し、ストレージルートが返されたファイルをダウンロードしたことを確認してください。
4. アプリケーションからファイルを再度開き、変更が保持されていることを確認してください。変更なしの閉じ方と、別のエディタを同時に使用した場合についても、それぞれ個別にテストしてください。

公式の保存フローガイドによると、ほとんどの場合、編集終了後約10秒で保存が完了します。ただし、ファイルサイズ、複雑さ、変換時間、サーバーのパフォーマンスによって遅延が変わる場合があります。エディタのiframeが閉じたからといって、ユーザーに「保存済み」と報告しないでください。コールバックと保存されたリビジョンを確認してください。

よくある統合の失敗

• エディタは開きますが、ファイルを読み込めません。document.urlデスクトップブラウザからだけでなく、ドキュメントサーバーのネットワークからもテストしてください。
• JWTが拒否されました：両側のシークレットとHS256構成を比較し、トークンが送信されている構成オブジェクトと完全に一致することを確認します。
• 変更が消える場合：コールバックの到達可能性、ステータス処理、一時的なダウンロードURLの取得、およびファイル置換の権限を確認してください。
• 古いバージョンが表示される場合：保存された改訂版の後に新しいドキュメントキーを発行し、キャッシュされたソースURLを意図せず提供しないようにします。
• ローカル環境では正常に動作するのに、本番環境では失敗する：リバースプロキシのパス、TLS証明書、コンテナのDNS、ファイアウォールルール、および各URLで使用されている公開ホスト名と内部ホスト名を調査する。

ONLYOFFICE DocsをカスタムPHPアプリケーションと統合するための基本的な手順は以下のとおりです。ソースファイルの認証と配信、ドキュメントごとのエディタ設定への署名、公式APIエディタのレンダリング、そして安全な保存コールバック処理。認証、ストレージ、URL署名、コールバック検証、同時実行ポリシーといった運用上の詳細設定は、アプリケーションおよびデプロイするDocsのバージョンと完全に一致させる必要があります。