Conectați o aplicație PHP la ONLYOFFICE Docs și salvați modificările

O aplicație PHP personalizată se integrează cu ONLYOFFICE Docs prin furnizarea unei adrese URL a documentului pe care Docs o poate prelua, încărcarea API-ului JavaScript Docs în browser și acceptarea unui apel invers care stochează fișierul editat. Păstrați semnătura JWT pe serverul PHP și faceți ca atât adresa URL a documentului, cât și adresa URL de apel invers să fie accesibile din rețeaua în care rulează ONLYOFFICE Docs.

Multe eșecuri de integrare apar din cauza confundării adreselor văzute de browser, PHP și Document Server. Testați fiecare rută din rețeaua care o folosește.

Pregătiți aplicația PHP și serverul de documente

ONLYOFFICE Docs oferă editorul de documente. Aplicația dvs. rămâne managerul de documente și serviciul de stocare: autentifică utilizatorii, decide ce fișiere pot deschide, furnizează fișierul sursă și salvează rezultatul. Instalați Document Server separat, apoi verificați /healthcheckendpoint-ul său înainte de a depana codul aplicației.

Folosește trei adrese accesibile în configurație:

• URL-ul documentelor: adresa pe care browserul utilizatorului o folosește pentru a încărca editorul și API-ul său JavaScript.
• URL-ul documentului: o adresă absolută pe care serverul de documente o poate utiliza pentru a descărca fișierul sursă din memoria PHP.
• URL de apel invers: o adresă absolută la care serverul de documente poate trimite un mesaj POST după editare, astfel încât PHP să poată stoca modificările.

De exemplu, https://docs.example.compoate servi editorului, în timp ce https://app.example.com/files/42/downloadși https://app.example.com/onlyoffice/callbackindică PHP. Testează accesibilitatea browser-to-Docs și Docs-to-PHP. În implementare, localhostînseamnă mașina sau containerul curent, deci de obicei este o adresă greșită între servicii.

Creați o configurație de document pentru un fișier autorizat

Pentru o cerere de deschidere autentificată, încărcați metadatele fișierului și construiți configurația editorului pe backend-ul PHP. Setați extensia fișierului, titlul, adresa URL absolută de descărcare și o cheie a documentului. Mențineți această cheie stabilă pentru editorii concurenți ai aceleiași versiuni; schimbați-o atunci când PHP înlocuiește sursa cu o versiune nouă.

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

Aplicați permisiunile fișierelor înainte de a genera adresa URL. Nu expuneți datele de autentificare pentru stocare și nu ocoliți autorizarea; linkurile private sau locale pot necesita, de asemenea, un token conform regulilor ONLYOFFICE.

Consultați referința de configurare a documentelor și ghidul de instalare auto-găzduit de ONLYOFFICE pentru câmpurile obligatorii și calea scriptului API.

Încărcați editorul și semnați configurația acestuia

JWT înseamnă JSON Web Token, un token semnat care permite ONLYOFFICE să verifice dacă configurația nu a fost modificată în tranzit. Validarea JWT este activată în mod implicit în implementările actuale; semnați configurația editorului cu secretul corespunzător pentru token-ul de browser, configurat în Docs. Dacă configurația dvs. utilizează un secret separat pentru token-ul de ieșire, validați și apelurile inverse cu acel secret pentru căsuța de ieșire. Începând cu Docs 7.2, instalările Docker pot genera automat un secret, așadar setați și păstrați secrete stabile pentru producție.

Ghidul oficial de semnătură ONLYOFFICE prezintă cod PHP cu firebase/php-jwtpachetul întreținut. Instalați-l cu composer require firebase/php-jwt, apoi semnați configurația completă în backend înainte de a o returna pe pagină:

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

Nu permiteți accesul secretului la codul browserului și la controlul sursei. Încărcați https://docs.example.com/web-apps/apps/api/documents/api.jsși transmiteți fișierul JSON semnat către 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>

Codificați JSON în siguranță cu json_encodesau preluați configurația semnată de la un endpoint cu aceeași origine; nu concatenați valori nesigure în JavaScript. Ghidul de semnătură documentează HMAC-SHA256. Pentru Docs 8.1 și versiunile ulterioare cu sarcină echilibrată, scriptul API poate include shardkeyparametrul de interogare documentat; un singur server nu are nevoie de acesta.

Salvați modificările printr-un apel invers PHP

După editare, Document Server trimite o solicitare POST către callbackUrl. Starea 2 înseamnă că editarea este finalizată și fișierul este gata de salvare; starea 6 este un rezultat al salvării forțate. Repealarea include o adresă URL temporară de descărcare pentru fișierul editat. Descărcați-l și înlocuiți atomic versiunea stocată sau creați o versiune nouă conform politicii de revizuire a aplicației. Reveniți {"error":0}numai după ce scrierea în spațiul de stocare are succes.

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

Exemplul presupune Authorization: Bearerantetul JWT implicit de ieșire și secretul corespunzător pentru căsuța de ieșire. Adaptați-l dacă serverul dvs. folosește un antet sau un token de corp diferit. Ajutorul de descărcare ar trebui să permită doar gazda dvs. Docs, să verifice răspunsul și să înlocuiască în siguranță fișierul așteptat. Nu aveți niciodată încredere într-o adresă URL arbitrară sau într-o cheie de document nesemnată.

După o salvare reușită, returnează JSON care conține {"error":0}. Consultați referința callback-ului pentru stări și sarcini utile și ciclul de viață al salvării pentru temporizarea callback-ului.

Verificați întreaga călătorie dus-întors

Deschideți un DOCX de test ca utilizator autorizat, faceți o mică modificare și închideți editorul. Confirmați că cheia de apel invers și starea corespund fișierului dorit, verificați dacă aplicația a stocat noii octeți, apoi redeschideți documentul. Dacă încărcarea eșuează, verificați ruta scriptului API și token-ul de configurare; dacă salvarea eșuează, verificați accesibilitatea apelului invers, validarea JWT, răspunsul JSON și jurnalele de stocare PHP.

ONLYOFFICE publică un exemplu de integrare PHP și o aplicație PHP eșantion, dar avertizează explicit că integrările eșantion nu oferă protecții de producție, cum ar fi autorizarea stocării și validarea cererilor de salvare. Folosește-le pentru a înțelege fluxul API, apoi păstrează verificările de acces și securitatea apelurilor inverse ale propriei aplicații.