Verbinden Sie eine PHP-Anwendung mit ONLYOFFICE Docs und speichern Sie Änderungen.

Eine benutzerdefinierte PHP-Anwendung integriert sich in ONLYOFFICE Docs, indem sie eine Dokument-URL bereitstellt, die von Docs abgerufen werden kann, die JavaScript-API von Docs im Browser lädt und einen Callback entgegennimmt, der die bearbeitete Datei speichert. Die JWT-Signierung muss auf dem PHP-Server erfolgen, und sowohl die Dokument-URL als auch die Callback-URL müssen aus dem Netzwerk erreichbar sein, in dem ONLYOFFICE Docs ausgeführt wird.

Viele Integrationsfehler entstehen durch die Vermischung der Adressen, die vom Browser, PHP und dem Dokumentenserver verwendet werden. Testen Sie jede Route aus dem Netzwerk, das sie nutzt.

Bereiten Sie die PHP-Anwendung und den Dokumentenserver vor.

ONLYOFFICE Docs stellt den Dokumenteneditor bereit. Ihre Anwendung bleibt Dokumentenverwaltung und -speicherung: Sie authentifiziert Benutzer, legt fest, welche Dateien geöffnet werden dürfen, liefert die Quelldatei und speichert das Ergebnis. Installieren Sie den Dokumentenserver separat und überprüfen Sie dessen /healthcheckEndpunkt, bevor Sie den Anwendungscode debuggen.

Verwenden Sie in Ihrer Konfiguration drei erreichbare Adressen:

• Docs-URL: die Adresse, die der Browser des Benutzers verwendet, um den Editor und seine JavaScript-API zu laden.
• Dokument-URL: eine absolute Adresse, die der Dokumentenserver verwenden kann, um die Quelldatei aus dem PHP-Speicher herunterzuladen.
• Callback-URL: eine absolute Adresse, an die der Dokumentenserver nach der Bearbeitung einen POST-Request senden kann, damit PHP die Änderungen speichern kann.

Beispielsweise https://docs.example.comkann der Editor bereitgestellt werden, während https://app.example.com/files/42/downloadauf https://app.example.com/onlyoffice/callbackPHP verwiesen wird. Testen Sie die Erreichbarkeit vom Browser zur Dokumentation und von der Dokumentation zu PHP. Im Deployment-Prozess localhostbezieht sich dies auf den aktuellen Rechner oder Container und ist daher in der Regel die falsche dienstübergreifende Adresse.

Erstellen Sie eine Dokumentkonfiguration für eine autorisierte Datei

Bei einer authentifizierten Öffnungsanfrage werden die Metadaten der Datei geladen und die Editorkonfiguration im PHP-Backend erstellt. Dateierweiterung, Titel, absolute Download-URL und ein Dokumentschlüssel werden festgelegt. Dieser Schlüssel muss für gleichzeitige Bearbeitungen derselben Version konstant bleiben; er wird nur geändert, wenn PHP den Quellcode durch eine neuere Version ersetzt.

<?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']],
  ],
];

Vor der URL-Generierung müssen die Dateiberechtigungen geprüft werden. Speicherzugangsdaten dürfen nicht offengelegt oder die Autorisierung umgangen werden; private oder lokale Links können gemäß den ONLYOFFICE-Regeln ebenfalls ein Token erfordern.

Die erforderlichen Felder und den Pfad zum API-Skript finden Sie in der Dokumentationskonfigurationsreferenz und der Anleitung zur selbstgehosteten Installation von ONLYOFFICE .

Laden Sie den Editor und signieren Sie seine Konfiguration.

JWT steht für JSON Web Token, ein signiertes Token, mit dem ONLYOFFICE überprüfen kann, ob die Konfiguration während der Übertragung verändert wurde. Die JWT-Validierung ist in aktuellen Bereitstellungen standardmäßig aktiviert. Signieren Sie die Editor-Konfiguration mit dem entsprechenden Browser-Token-Geheimnis, das in der Dokumentation konfiguriert ist. Wenn Ihre Konfiguration ein separates ausgehendes Token-Geheimnis verwendet, validieren Sie auch die Rückrufe mit diesem ausgehenden Token-Geheimnis. Ab Version 7.2 der Dokumentation können Docker-Installationen automatisch ein Geheimnis generieren. Verwenden Sie daher für den Produktivbetrieb stabile Geheimnisse.

Die offizielle ONLYOFFICE-Signaturanleitung zeigt PHP-Code mit dem zugehörigen firebase/php-jwtPaket. Installieren Sie es mit [Befehl einfügen] composer require firebase/php-jwtund signieren Sie anschließend die gesamte Konfiguration im Backend, bevor Sie sie an die Seite zurückgeben.

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');

Halten Sie das Geheimnis von Browsercode und Quellcodeverwaltung fern. Laden https://docs.example.com/web-apps/apps/api/documents/api.jsund übergeben Sie das signierte JSON an 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-Daten sollten sicher kodiert json_encodeoder die signierte Konfiguration von einem Endpunkt mit demselben Ursprung abgerufen werden. Nicht vertrauenswürdige Werte dürfen nicht in JavaScript verkettet werden. Die Signaturanleitung beschreibt HMAC-SHA256. Bei Load-Balancing-Versionen ab Docs 8.1 kann das API-Skript den dokumentierten shardkeyAbfrageparameter enthalten; ein einzelner Server benötigt ihn nicht.

Änderungen über einen PHP-Callback speichern

Nach der Bearbeitung sendet der Dokumentenserver eine POST-Anfrage callbackUrl. Status 2 bedeutet, dass die Bearbeitung abgeschlossen ist und die Datei gespeichert werden kann; Status 6 bedeutet, dass die Datei zwangsweise gespeichert wurde. Die Callback-Funktion enthält eine temporäre Download-URL für die bearbeitete Datei. Laden Sie diese herunter und ersetzen Sie die gespeicherte Version atomar oder erstellen Sie eine neue Version gemäß der Revisionsrichtlinie Ihrer Anwendung. Die Funktion kehrt {"error":0}erst zurück, wenn der Schreibvorgang erfolgreich war.

<?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]);

Das Beispiel geht von einem standardmäßigen ausgehenden Authorization: BearerJWT-Header und dem passenden Outbox-Secret aus. Passen Sie es an, falls Ihr Server einen anderen Header oder Body-Token verwendet. Der Download-Helper sollte nur Zugriff auf Ihren Docs-Host zulassen, die Antwort prüfen und die erwartete Datei sicher ersetzen. Vertrauen Sie niemals einer beliebigen URL oder einem unsignierten Dokumentschlüssel.

Nach erfolgreichem Speichern wird JSON mit den entsprechenden Informationen zurückgegeben {"error":0}. Informationen zu Statusmeldungen und Nutzdaten finden Sie in der Callback-Referenz , den Speicherlebenszyklus bezüglich des Callback-Zeitpunkts.

Überprüfen Sie die vollständige Hin- und Rückreise

Öffnen Sie als autorisierter Benutzer eine Test-DOCX-Datei, nehmen Sie eine kleine Änderung vor und schließen Sie den Editor. Stellen Sie sicher, dass Callback-Schlüssel und Status mit der gewünschten Datei übereinstimmen, überprüfen Sie, ob Ihre Anwendung die neuen Bytes gespeichert hat, und öffnen Sie das Dokument erneut. Falls das Laden fehlschlägt, überprüfen Sie die API-Skriptroute und das Konfigurationstoken; falls das Speichern fehlschlägt, überprüfen Sie die Erreichbarkeit des Callbacks, die JWT-Validierung, die JSON-Antwort und die PHP-Speicherprotokolle.

ONLYOFFICE stellt ein PHP-Integrationsbeispiel und eine PHP-Beispielanwendung bereit, weist aber ausdrücklich darauf hin, dass den Beispielintegrationen produktionsreife Schutzmechanismen wie Speicherautorisierung und Validierung von Speicheranfragen fehlen. Nutzen Sie diese, um den API-Ablauf zu verstehen, und implementieren Sie anschließend die Zugriffskontrollen und die Callback-Sicherheit Ihrer eigenen Anwendung.