Verbind een PHP-app met OnlyOffice-documenten en sla wijzigingen op.

Een aangepaste PHP-applicatie integreert met ONLYOFFICE Docs door een document-URL aan te bieden die Docs kan ophalen, de JavaScript-API van Docs in de browser te laden en een callback te accepteren die het bewerkte bestand opslaat. Zorg ervoor dat JWT-ondertekening op de PHP-server blijft en dat zowel de document-URL als de callback-URL bereikbaar zijn vanaf het netwerk waarop ONLYOFFICE Docs draait.

Veel integratieproblemen ontstaan ​​doordat de adressen die de browser, PHP en de documentenserver zien, door elkaar worden gehaald. Test elke route vanuit het netwerk dat deze gebruikt.

Bereid de PHP-app en de documentenserver voor.

ONLYOFFICE Docs biedt de documenteditor. Uw applicatie blijft de documentbeheerder en opslagservice: deze authenticeert gebruikers, bepaalt welke bestanden ze mogen openen, levert het bronbestand en slaat het resultaat op. Installeer Document Server apart en controleer het /healthcheckeindpunt voordat u de applicatiecode debugt.

Gebruik drie bereikbare IP-adressen in uw configuratie:

• Docs-URL: het adres dat de browser van de gebruiker gebruikt om de editor en de bijbehorende JavaScript-API te laden.
• Document-URL: een absoluut adres dat de documentserver kan gebruiken om het bronbestand uit de PHP-opslag te downloaden.
• Callback-URL: een absoluut adres waarnaar de documentenserver na bewerking een POST-verzoek kan sturen, zodat PHP de wijzigingen kan opslaan.

Bijvoorbeeld, https://docs.example.comkan de editor bedienen, terwijl https://app.example.com/files/42/downloaden https://app.example.com/onlyoffice/callbacknaar PHP verwijzen. Test de bereikbaarheid van browser naar Docs en van Docs naar PHP. In de implementatie localhostverwijst naar de huidige machine of container, dus is het meestal het verkeerde adres voor communicatie tussen services.

Een documentconfiguratie maken voor een geautoriseerd bestand.

Voor een geauthenticeerd openingsverzoek laadt u de metadata van het bestand en bouwt u de editorconfiguratie op in de PHP-backend. Stel de bestandsextensie, titel, absolute download-URL en een documentsleutel in. Houd deze sleutel stabiel voor gelijktijdige editors van dezelfde versie; wijzig deze wanneer PHP de broncode vervangt door een nieuwe versie.

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

Handhaaf de bestandsrechten voordat u de URL genereert. Geef geen opslaggegevens prijs en omzeil geen autorisatie; privé- of lokale links vereisen mogelijk ook een token volgens de regels van ONLYOFFICE.

Raadpleeg de configuratiehandleiding en de installatiegids voor zelfhosting van ONLYOFFICE voor de vereiste velden en het pad naar het API-script.

Laad de editor en onderteken de configuratie.

JWT staat voor JSON Web Token, een ondertekend token waarmee ONLYOFFICE kan controleren of de configuratie tijdens de overdracht niet is gewijzigd. JWT-validatie is standaard ingeschakeld in de huidige implementaties; onderteken de editorconfiguratie met het bijbehorende browsertoken-geheim dat is geconfigureerd in Docs. Als uw configuratie een apart uitgaand token-geheim gebruikt, valideer dan ook de callbacks met dat uitgaande token-geheim. Vanaf Docs 7.2 kunnen Docker-installaties automatisch een geheim genereren, dus stel stabiele geheimen in en bewaar deze voor productie.

De officiële handleiding voor het ondertekenen van ONLYOFFICE-bestanden toont PHP-code met het onderhouden firebase/php-jwtpakket. Installeer het met `npm install onlyoffice` composer require firebase/php-jwten onderteken vervolgens de volledige configuratie in de backend voordat u deze terugstuurt naar de pagina:

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

Houd het geheim buiten de browsercode en versiebeheer. Laad https://docs.example.com/web-apps/apps/api/documents/api.jsen geef de ondertekende JSON door aan 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>

Codeer JSON veilig met behulp van json_encodeof haal de ondertekende configuratie op van een same-origin endpoint; voeg geen onbetrouwbare waarden samen in JavaScript. De handleiding voor handtekeningenshardkey beschrijft HMAC-SHA256. Voor load-balanced Docs 8.1 en later kan het API-script de beschreven queryparameter bevatten ; een enkele server heeft deze niet nodig.

Wijzigingen opslaan via een PHP-callback.

Na het bewerken stuurt de documentenserver een POST-verzoek naar de server callbackUrl. Status 2 betekent dat de bewerking is voltooid en het bestand klaar is om op te slaan; status 6 betekent dat het bestand geforceerd is opgeslagen. De callback bevat een tijdelijke download-URL voor het bewerkte bestand. Download het bestand en vervang de opgeslagen versie automatisch, of maak een nieuwe versie aan volgens het revisiebeleid van uw app. De functie wordt {"error":0}pas geretourneerd nadat het schrijven naar de opslag succesvol is verlopen.

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

Het voorbeeld gaat uit van de standaard uitgaande Authorization: BearerJWT-header en het bijbehorende outbox-geheim. Pas het aan als uw server een andere header of body-token gebruikt. De downloadhelper moet alleen uw Docs-host toestaan, het antwoord controleren en het verwachte bestand veilig vervangen. Vertrouw nooit op een willekeurige URL of een niet-ondertekende documentsleutel.

Na een succesvolle opslag retourneert u JSON met de volgende informatie {"error":0}: Raadpleeg de callback-referentie voor statussen en payloads, en de opslaglevenscyclus voor de timing van de callback.

Controleer de volledige heen- en terugreis.

Open een test-DOCX-bestand als geautoriseerde gebruiker, voer een kleine bewerking uit en sluit de editor. Controleer of de callback-sleutel en -status overeenkomen met het beoogde bestand, verifieer of uw app de nieuwe bytes heeft opgeslagen en open het document vervolgens opnieuw. Als het laden mislukt, controleer dan de API-scriptroute en het configuratietoken; als het opslaan mislukt, controleer dan de bereikbaarheid van de callback, de JWT-validatie, het JSON-antwoord en de PHP-opslaglogboeken.

ONLYOFFICE publiceert een PHP-integratievoorbeeld en een PHP-voorbeeldapplicatie, maar waarschuwt expliciet dat voorbeeldintegraties geen beveiligingen bieden die geschikt zijn voor productieomgevingen, zoals autorisatie van opslag en validatie van opslagverzoeken. Gebruik ze om de API-flow te begrijpen en behoud vervolgens de toegangscontroles en callback-beveiliging van uw eigen applicatie.