Cum să integrezi documentele ONLYOFFICE cu o aplicație PHP personalizată

Începeți cu limita integrării: o aplicație PHP personalizată nu trimite octeți de document direct în editor. Aplicația dvs. autentifică utilizatorul, stochează fișierul, servește o adresă URL pe care serverul ONLYOFFICE Docs o poate prelua și expune un punct final de apel invers unde Docs postează actualizări de salvare. Browserul încarcă scriptul API Docs și creează un editor într-un element de pagină. Acest model funcționează cu un server Docs auto-găzduit atunci când browserul și ambele servere pot accesa adresele URL necesare.

O notă relevantă privind versiunea: ONLYOFFICE a anunțat Docs 9.4 pe 19 mai 2026. Anunțul precizează că ediția open-source Community Edition a eliminat limita anterioară de 20 de conexiuni simultane începând cu versiunea 9.4. Aceasta modifică o considerație de implementare pentru utilizatorii Community; nu elimină necesitatea stocării accesibile și a punctelor finale de apel invers, a semnării JWT sau a revizuirii licențelor. Verificați termenii lansării și ai licenței pentru versiunea exactă a Docs pe care intenționați să o implementați. Integrarea de mai jos respectă fluxul API Docs documentat actual.

Cele patru ilustrații de ecran sunt exemple conceptuale, nu capturi de ecran ale produsului. Lista de documente și aspectul proiectului PHP sunt specifice aplicației, iar interfața editorului poate varia în funcție de versiunea și configurația Docs.

Înainte de a conecta orice

Aveți nevoie de o aplicație PHP, un server ONLYOFFICE Docs și un spațiu de stocare a documentelor controlat de aplicația dvs. Docs și aplicația PHP pot rula pe gazde sau containere separate. Browserul utilizatorului trebuie să ajungă la serverul Docs pentru a descărca resursele editorului său. Separat, serverul Docs trebuie să ajungă la adresa URL a documentului și la adresa URL de apel invers al aplicației dvs. Un nume de gazdă, cum ar fi , localhosteșuează adesea în configurarea unui container, deoarece indică înapoi la containerul care face solicitarea, nu la celălalt serviciu.

Folosește HTTPS pentru endpoint-uri publice, persistă secretul JWT în afara controlului sursei și decide cum se mapează permisiunile documentelor la utilizatorii aplicației tale. Pentru dezvoltarea locală, poate fi nevoie de o rețea privată sau de un tunel, astfel încât Docs să poată prelua un fișier de dezvoltare; producția ar trebui să utilizeze rute stabile și autentificate. Ghidul oficial de instalare ONLYOFFICE Docs Docker explică instalarea și configurarea JWT. Secretele sale eșantion sunt exemple - înlocuiește-le cu un secret privat și păstrează-l consistent cu configurația Docs.

Pasul 1: Definiți rutele documentelor și ale rețelei

Începeți prin a face documentul disponibil la o adresă URL stabilă, absolută, pe care Docs o poate prelua. Nu îndreptați editorul către o cale de sesiune PHP sau către o adresă URL relativă exclusivă pentru browser. În schimb, creați o rută de aplicație autentificată, cum ar fi https://app.example.com/docs/42/download. Înainte de a returna octeți, acea rută ar trebui să verifice accesul utilizatorului conectat la documentul 42. Dacă serverul Docs nu poate reutiliza sesiunea de browser a utilizatorului, emiteți o adresă URL de descărcare cu scop scurt, sau un alt mecanism de autorizare server-la-server.

Creați și o rută de apel invers, cum ar fi https://app.example.com/onlyoffice/callback?document=42. Aceasta trebuie să accepte un POST de la serverul Docs, să identifice fișierul țintă în siguranță și să fie accesibilă din rețeaua serverului Docs. Parametrul URL pe care Docs îl postează înapoi este un link temporar de descărcare pentru documentul editat; nu este fișierul salvat în baza de date. Ruta de apel invers trebuie să preia acei octeți și să îi scrie în memoria dvs.

ONLYOFFICE descrie editorul și serviciul de stocare a documentelor ca părți separate: Docs furnizează serviciul de editare, în timp ce integratorul furnizează managerul de documente și stocarea. Consultați prezentarea oficială „Cum funcționează” înainte de a alege endpoint-ul și designul rețelei.

Pasul 2: Construiți configurația editorului în PHP

Pentru un document Word, configurația identifică tipul fișierului sursă, o cheie unică a documentului, titlul, adresa URL descărcabilă, modul editor și adresa URL de apel invers. Cheia este importantă: permite programului Docs să identifice sesiunea de editare și să reutilizeze un document din cache. Generați o cheie nouă după ce fișierul a fost editat și salvat; reutilizați aceeași cheie pentru clienții care sunt meniți să se alăture aceleiași sesiuni active de documente. Păstrați cheia în limitele de caractere și lungime documentate.

Exemplul de mai jos presupune Composer și biblioteca Firebase PHP-JWT. Înlocuiți fiecare exemplu de URL și căutare în spațiul de stocare cu propriile servicii care acceptă autorizarea.

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

Fișierul document.urltrebuie să poată fi citit de serverul Docs, nu doar de browser. Fișierul document.keyar trebui să urmărească o revizie salvată: dacă reutilizați o cheie veche după ce fișierul sursă s-a modificat, Docs poate deschide conținut din cache. Tokenul este un JSON Web Token (JWT) semnat, un format standard pentru a dovedi că configurația a provenit de la un server care deține secretul partajat. Secretul de semnare rămâne pe serverul PHP; nu îl puneți niciodată în JavaScript sau HTML.

Numele de cod docsDownloadUrl(), callbackUrl(), și editingKey()sunt metode de aplicație, nu funcții PHP ONLYOFFICE încorporate. Implementarea exactă depinde de sistemul de stocare, framework-ul web și modelul de control al accesului. ONLYOFFICE publică un SDK oficial de integrare PHP și exemple multilingve, dar depozitul descrie explicit aplicațiile sale demo ca exemple de testare care necesită modificări de producție. Consultați ghidul oficial de semnătură JWT și exemplele oficiale de integrare .

Pasul 3: Încărcați API-ul Docs și randați editorul

Redați configurația semnată în pagină numai după ce ruta PHP a autorizat utilizatorul. Utilizați codul JSON pentru un context JavaScript și faceți containerul editorului suficient de înalt pentru a fi utilizabil. Browserul preia date api.jsde pe serverul dvs. Docs; constructorul înlocuiește elementul placeholder cu un iframe al editorului.

<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>

Etichetele de mai sus sunt afișate ca markup eșantion escape, astfel încât să poată fi citite ca și cod. În pagina reală, încărcați scriptul API de la adresa URL a serverului Docs care deservește editorul. Dacă zona editorului este goală, confirmați mai întâi că browserul poate deschide adresa URL respectivă, că aplicația și Docs utilizează certificate HTTPS compatibile și că instrumentele de dezvoltare ale browserului nu afișează nicio solicitare blocată de conținut mixt sau de rețea. Documentația DocsAPI.DocEditor explică comportamentul placeholderului și al iframe-ului.

Pasul 4: Salvați actualizările prin apel invers

Când editarea se termină, Docs trimite un mesaj POST către editorConfig.callbackUrl. statusValoarea determină ce ar trebui să facă handler-ul. Starea 2 înseamnă că documentul este gata de salvare după închiderea editării. Starea 6 înseamnă că starea curentă a fost salvată printr-o operațiune de salvare forțată, în timp ce sesiunea de editare poate continua. Alte valori indică stări de conectare, fără modificări sau eroare; nu tratați fiecare apel invers ca un fișier nou.

Un handler de apel invers ar trebui să analizeze corpul JSON, să valideze cererea conform setărilor de ieșire JWT activate pe serverul Docs, să mape apelul invers la un document deținut de integrarea curentă și să gestioneze în mod deliberat stările de salvare. În starea 2 sau 6, descărcați fișierul postat urlde pe serverul Docs, verificați dacă descărcarea a reușit și înlocuiți fișierul stocat atomic, astfel încât o descărcare parțială să nu poată corupe originalul. Returnați răspunsul de apel invers așteptat de API-ul curent, de obicei un obiect JSON cu errorsetarea la 0după procesarea cu succes.

<?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()și replaceAtomically()sunt substituenți, nu rutine de producție complete. Folosiți un client HTTP cu timeout-uri, verificare TLS, limite de dimensiune a răspunsului și destinații de ieșire controlate; nu preluați o adresă URL arbitrară fără măsuri de siguranță. Verificați semnătura/token-ul apelului invers folosind metoda documentată pentru versiunea și configurația exactă a Docs pe care o executați. Referința oficială a handlerului de apel invers listează stările și când este prezentă adresa URL a fișierului editat.

Testați calea completă de salvare

1. Deschideți un fișier DOCX mic ca utilizator cu permisiunea de a-l edita.
2. Faceți o modificare vizibilă, așteptați ca editorul să indice că este salvată și închideți documentul.
3. Inspectați jurnalele PHP și Docs. Confirmați că apelul invers a sosit și că ruta de stocare a descărcat fișierul returnat.
4. Redeschideți fișierul din aplicație și confirmați că modificarea persistă. Testați separat o închidere fără modificări și un al doilea editor simultan.

Ghidul oficial privind fluxul de salvare menționează că, în majoritatea cazurilor, salvarea se finalizează la aproximativ 10 secunde după terminarea editării; dimensiunea fișierului, complexitatea, timpul de conversie și performanța serverului pot afecta întârzierea. Nu raportați utilizatorului „salvat” doar pentru că iframe-ul editorului s-a închis - verificați apelul invers și revizia stocată.

Eșecuri comune de integrare

• Editorul se deschide, dar nu poate încărca fișierul: testați document.urldin rețeaua serverului Docs, nu doar din browserul desktopului.
• JWT respins: comparați secretul și configurația HS256 pe ambele părți; confirmați că tokenul semnează exact obiectul de configurare trimis.
• Modificările dispar: verificați accesibilitatea apelurilor inverse, gestionarea stării, preluarea URL-ului de descărcare temporară și permisiunile de înlocuire a fișierelor.
• Apare o versiune veche: emiteți o nouă cheie de document după o revizie salvată și evitați difuzarea neintenționată a adreselor URL sursă din cache.
• Funcționează local, eșuează în producție: inspectați căile de proxy invers, certificatele TLS, DNS-ul containerului, regulile firewall și numele de gazdă public versus intern utilizat în fiecare adresă URL.

Aceasta este calea principală pentru integrarea ONLYOFFICE Docs cu o aplicație PHP personalizată: autorizarea și servirea fișierului sursă, semnarea unei configurații de editor per document, randarea editorului API oficial, apoi procesarea în siguranță a apelurilor inverse de salvare. Detaliile de producție - autentificarea, stocarea, semnarea URL-urilor, verificarea apelurilor inverse și politica de concurență - trebuie să corespundă propriei aplicații și versiunii exacte de Docs pe care o implementați.