Wie man ONLYOFFICE Docs in eine benutzerdefinierte PHP-Anwendung integriert

Beginnen wir mit der Integrationsgrenze: Eine benutzerdefinierte PHP-Anwendung sendet keine Dokumentbytes direkt an den Editor. Ihre Anwendung authentifiziert den Benutzer, speichert die Datei, stellt eine URL bereit, die der ONLYOFFICE Docs-Server abrufen kann, und bietet einen Callback-Endpunkt, an den Docs Speicheraktualisierungen sendet. Der Browser lädt das Docs-API-Skript und erstellt einen Editor in einem Seitenelement. Dieses Muster funktioniert mit einem selbstgehosteten Docs-Server, sofern Browser und Server die erforderlichen URLs erreichen können.

Wichtiger Versionshinweis: ONLYOFFICE hat Docs 9.4 am 19. Mai 2026 angekündigt. Laut Ankündigung wurde die bisherige Beschränkung auf 20 gleichzeitige Verbindungen in der Open-Source-Community-Edition ab Version 9.4 aufgehoben. Dies ändert einen Aspekt bei der Bereitstellung für Community-Nutzer; die Notwendigkeit erreichbarer Speicher- und Callback-Endpunkte, JWT-Signierung und Lizenzprüfung entfällt jedoch nicht. Bitte prüfen Sie die Versions- und Lizenzbedingungen für die von Ihnen geplante Docs-Version. Die unten beschriebene Integration folgt dem aktuell dokumentierten API-Ablauf von Docs.

Die vier Bildschirmabbildungen sind konzeptionelle Beispiele und keine Screenshots des Produkts. Die Dokumentenliste und das PHP-Projektlayout sind anwendungsspezifisch, und die Benutzeroberfläche des Editors kann je nach Docs-Version und -Konfiguration variieren.

Bevor Sie irgendetwas anschließen

Sie benötigen eine PHP-Anwendung, einen ONLYOFFICE Docs-Server und einen von Ihrer Anwendung verwalteten Dokumentenspeicher. Docs und die PHP-Anwendung können auf separaten Hosts oder in Containern ausgeführt werden. Der Browser des Benutzers muss den Docs-Server erreichen, um die Editor-Ressourcen herunterzuladen. Der Docs-Server muss seinerseits die Dokument-URL und die Callback-URL Ihrer Anwendung erreichen können. Ein Hostname wie beispielsweise `/example.com` localhostführt in einer Container-Umgebung häufig zu Problemen, da er auf den anfragenden Container und nicht auf den anderen Dienst verweist.

Verwenden Sie HTTPS für öffentliche Endpunkte, speichern Sie Ihr JWT-Geheimnis außerhalb der Versionskontrolle und legen Sie fest, wie Dokumentberechtigungen den Benutzern Ihrer Anwendung zugeordnet werden. Für die lokale Entwicklung kann ein privates Netzwerk oder ein Tunnel erforderlich sein, damit Docs eine Entwicklungsdatei abrufen kann; für den Produktivbetrieb sollten stabile, authentifizierte Routen verwendet werden. Die offizielle ONLYOFFICE Docs Docker-Installationsanleitung erläutert die Installation und die JWT-Konfiguration. Die darin enthaltenen Beispielgeheimnisse dienen lediglich als Beispiele – ersetzen Sie diese durch Ihr privates Geheimnis und stellen Sie sicher, dass es mit Ihrer Docs-Konfiguration übereinstimmt.

Schritt 1: Dokument- und Netzwerkrouten definieren

Stellen Sie das Dokument zunächst unter einer stabilen, absoluten URL bereit, die Docs abrufen kann. Verwenden Sie im Editor keine PHP-Session-URL oder eine relative URL, die nur im Browser funktioniert. Erstellen Sie stattdessen eine authentifizierte Anwendungsroute, z. B. `/ https://app.example.com/docs/42/downloadvar/www/docs ...

Erstellen Sie außerdem eine Callback-Route https://app.example.com/onlyoffice/callback?document=42. Diese muss einen POST-Request vom Docs-Server empfangen, die Zieldatei sicher identifizieren und vom Netzwerk des Docs-Servers aus erreichbar sein. Der von Docs zurückgesendete URL-Parameter ist ein temporärer Download-Link für das bearbeitete Dokument; es handelt sich nicht um die in Ihrer Datenbank gespeicherte Datei. Ihre Callback-Funktion muss diese Daten abrufen und in Ihrem Speicher ablegen.

ONLYOFFICE beschreibt Editor und Dokumentenspeicher als separate Komponenten: Docs stellt den Bearbeitungsdienst bereit, während der Integrator Dokumentenmanagement und -speicherung übernimmt. Lesen Sie die offizielle Übersicht „So funktioniert es“, bevor Sie sich für ein Endgerät und ein Netzwerkdesign entscheiden.

Schritt 2: Erstellen Sie die Editorkonfiguration in PHP

Die Konfiguration eines Word-Dokuments legt den Dateityp, einen eindeutigen Dokumentschlüssel, den Titel, die Download-URL, den Bearbeitungsmodus und die Callback-URL fest. Der Schlüssel ist wichtig: Er ermöglicht es Docs, die Bearbeitungssitzung zu identifizieren und ein zwischengespeichertes Dokument wiederzuverwenden. Generieren Sie einen neuen Schlüssel, sobald die Datei bearbeitet und gespeichert wurde; verwenden Sie denselben Schlüssel für Clients, die derselben aktiven Dokumentsitzung beitreten sollen. Halten Sie die dokumentierten Zeichen- und Längenbeschränkungen für den Schlüssel ein.

Das folgende Beispiel setzt Composer und die Firebase PHP-JWT-Bibliothek voraus. Ersetzen Sie alle Beispiel-URLs und Speicherabfragen durch Ihre eigenen, autorisierungsfähigen Dienste.

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

Die Datei document.urlmuss vom Docs-Server lesbar sein, nicht nur vom Browser. Sie document.keysollte eine gespeicherte Revision nachverfolgen: Wird ein veralteter Schlüssel nach Änderungen an der Quelldatei wiederverwendet, kann Docs zwischengespeicherte Inhalte öffnen. Das Token ist ein signiertes JSON Web Token (JWT), ein Standardformat zum Nachweis, dass die Konfiguration von einem Server stammt, der das gemeinsame Geheimnis besitzt. Das Signaturgeheimnis verbleibt auf dem PHP-Server; es darf niemals in JavaScript oder HTML gespeichert werden.

Die Codenamen `<code>` docsDownloadUrl(), callbackUrl()`<code>` und editingKey()`<code>` bezeichnen Anwendungsmethoden und keine integrierten PHP-Funktionen von ONLYOFFICE. Die genaue Implementierung hängt von Ihrem Speichersystem, Webframework und Zugriffskontrollmodell ab. ONLYOFFICE stellt ein offizielles PHP-Integrations-SDK und mehrsprachige Beispiele bereit. Die Demo-Anwendungen im Repository sind jedoch ausdrücklich als Testbeispiele zu kennzeichnen, die für den Produktiveinsatz angepasst werden müssen. Lesen Sie die offizielle JWT-Signaturanleitung und die offiziellen Integrationsbeispiele .

Schritt 3: Laden der Docs-API und Rendern des Editors

Die signierte Konfiguration wird erst dann in die Seite eingebunden, nachdem die PHP-Route den Benutzer autorisiert hat. Das JSON wird für einen JavaScript-Kontext maskiert, und der Editor-Container wird so hoch gestaltet, dass er gut nutzbar ist. Der Browser lädt die Daten api.jsvon Ihrem Dokumentationsserver; der Konstruktor ersetzt das Platzhalterelement durch ein Editor-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>

Die obenstehenden Tags sind als Beispiel-Markup mit Escape-Sequenzen dargestellt, damit sie als Code gelesen werden können. Laden Sie auf Ihrer eigentlichen Seite das API-Skript von der URL des Docs-Servers, der Ihren Editor bereitstellt. Falls der Editorbereich leer ist, überprüfen Sie zunächst, ob der Browser diese URL öffnen kann, ob die Anwendung und Docs kompatible HTTPS-Zertifikate verwenden und ob die Entwicklertools des Browsers keine blockierten Mixed-Content- oder Netzwerkanfragen anzeigen. Die Dokumentation zu DocsAPI.DocEditor erläutert das Verhalten von Platzhaltern und iFrames.

Schritt 4: Aktualisierungen über den Rückruf speichern

Nach Beendigung der Bearbeitung sendet Docs einen POST-Request an die entsprechende Schnittstelle editorConfig.callbackUrl. Der statusWert des Requests bestimmt das Verhalten Ihres Handlers. Status 2 bedeutet, dass das Dokument nach Abschluss der Bearbeitung gespeichert werden kann. Status 6 bedeutet, dass der aktuelle Zustand durch einen erzwungenen Speichervorgang gesichert wurde, die Bearbeitungssitzung aber fortgesetzt werden kann. Andere Werte kennzeichnen Verbindungs-, Änderungs- oder Fehlerzustände; behandeln Sie nicht jeden Callback als neue Datei.

Ein Callback-Handler sollte den JSON-Body analysieren, die Anfrage gemäß den auf Ihrem Docs-Server aktivierten JWT-Outbox-Einstellungen validieren, den Callback einem Dokument zuordnen, das der aktuellen Integration gehört, und Speicherstände gezielt verwalten. Bei Status 2 oder 6 lädt er die urlvom Docs-Server bereitgestellte Datei herunter, überprüft den erfolgreichen Download und ersetzt die gespeicherte Datei atomar, sodass ein unvollständiger Download das Original nicht beschädigen kann. Anschließend gibt er die von der aktuellen API erwartete Callback-Antwort zurück, typischerweise ein JSON-Objekt, dessen Status nach erfolgreicher Verarbeitung auf „ errortrue“ gesetzt ist .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()Diese Beispiele sind Platzhalter und replaceAtomically()keine vollständigen Produktionsroutinen. Verwenden Sie einen HTTP-Client mit Timeouts, TLS-Verifizierung, Antwortgrößenbeschränkungen und kontrollierten ausgehenden Zielen. Rufen Sie keine beliebigen URLs ohne entsprechende Sicherheitsvorkehrungen ab. Überprüfen Sie die Signatur/das Token des Callbacks anhand der in der Dokumentation für Ihre spezifische Docs-Version und Konfiguration beschriebenen Methode. Die offizielle Callback-Handler-Referenz listet Statusmeldungen und Informationen zum Vorhandensein der URL der bearbeiteten Datei auf.

Testen Sie den vollständigen Speicherpfad

1. Öffnen Sie eine kleine DOCX-Datei als Benutzer, der die Berechtigung zum Bearbeiten hat.
2. Nehmen Sie eine sichtbare Änderung vor, warten Sie, bis der Editor anzeigt, dass sie gespeichert wurde, und schließen Sie das Dokument.
3. Überprüfen Sie die PHP- und Docs-Logs. Stellen Sie sicher, dass der Callback empfangen wurde und Ihre Speicherroute die zurückgegebene Datei heruntergeladen hat.
4. Öffnen Sie die Datei erneut in der Anwendung und prüfen Sie, ob die Änderung erhalten geblieben ist. Testen Sie anschließend separat das Schließen der Datei ohne Änderungen sowie einen zweiten gleichzeitig geöffneten Editor.

Die offizielle Anleitung zum Speichervorgang weist darauf hin, dass der Speichervorgang in den meisten Fällen etwa 10 Sekunden nach Beendigung der Bearbeitung abgeschlossen ist. Dateigröße, Komplexität, Konvertierungszeit und Serverleistung können die Verzögerung beeinflussen. Melden Sie dem Benutzer nicht automatisch „gespeichert“, nur weil der Editor-iFrame geschlossen wurde – überprüfen Sie stattdessen den Callback und die gespeicherte Revision.

Häufige Integrationsfehler

• Der Editor öffnet sich, kann aber die Datei nicht laden: Test document.urlvom Netzwerk des Docs-Servers, nicht nur von Ihrem Desktop-Browser.
• JWT abgelehnt: Vergleichen Sie das Geheimnis und die HS256-Konfiguration auf beiden Seiten; bestätigen Sie, dass das Token das exakte Konfigurationsobjekt signiert, das gesendet wird.
• Änderungen verschwinden: Überprüfung der Erreichbarkeit von Rückruffunktionen, Statusbehandlung, Abrufen der temporären Download-URL und Berechtigungen zum Ersetzen von Dateien.
• Alte Version erscheint: Nach dem Speichern einer Revision wird ein neuer Dokumentschlüssel ausgegeben, um zu vermeiden, dass zwischengespeicherte Quell-URLs unbeabsichtigt ausgeliefert werden.
• Funktioniert lokal, schlägt in der Produktion fehl: Überprüfen Sie die Reverse-Proxy-Pfade, TLS-Zertifikate, Container-DNS, Firewall-Regeln und den öffentlichen bzw. internen Hostnamen, der in jeder URL verwendet wird.

Dies ist der Kernpfad für die Integration von ONLYOFFICE Docs in eine benutzerdefinierte PHP-Anwendung: Autorisierung und Bereitstellung der Quelldatei, Signierung einer dokumentspezifischen Editorkonfiguration, Darstellung des offiziellen API-Editors und anschließende sichere Verarbeitung von Speicher-Callbacks. Die Produktionsdetails – Authentifizierung, Speicherung, URL-Signierung, Callback-Verifizierung und Parallelitätsrichtlinie – müssen mit Ihrer Anwendung und der verwendeten Docs-Version übereinstimmen.