Collega un'app PHP a ONLYOFFICE Docs e salva le modifiche

Un'applicazione PHP personalizzata si integra con ONLYOFFICE Docs fornendo un URL del documento che Docs può recuperare, caricando l'API JavaScript di Docs nel browser e accettando una callback che memorizza il file modificato. Mantieni la firma JWT sul server PHP e rendi sia l'URL del documento che l'URL di callback raggiungibili dalla rete in cui è in esecuzione ONLYOFFICE Docs.

Molti problemi di integrazione derivano dalla confusione tra gli indirizzi visti dal browser, da PHP e dal server dei documenti. Testa ogni percorso dalla rete che lo utilizza.

Preparare l'applicazione PHP e il server dei documenti.

ONLYOFFICE Docs fornisce l'editor di documenti. La tua applicazione rimane il gestore dei documenti e il servizio di archiviazione: autentica gli utenti, decide quali file possono aprire, fornisce il file sorgente e salva il risultato. Installa Document Server separatamente, quindi verifica il suo /healthcheckendpoint prima di eseguire il debug del codice dell'applicazione.

Nella configurazione, utilizza tre indirizzi raggiungibili:

• URL della documentazione: l'indirizzo utilizzato dal browser dell'utente per caricare l'editor e la relativa API JavaScript.
• URL del documento: un indirizzo assoluto che il Document Server può utilizzare per scaricare il file sorgente dalla memoria PHP.
• URL di callback: un indirizzo assoluto a cui il Document Server può inviare una richiesta POST dopo la modifica, in modo che PHP possa memorizzare le modifiche.

Ad esempio, https://docs.example.compuò servire l'editor, mentre https://app.example.com/files/42/downloade https://app.example.com/onlyoffice/callbackpuntano a PHP. Testa la raggiungibilità dal browser alla documentazione e dalla documentazione a PHP. Nella distribuzione, localhostindica la macchina o il container corrente, quindi di solito è l'indirizzo cross-service errato.

Creare una configurazione del documento per un file autorizzato

Per una richiesta di apertura autenticata, carica i metadati del file e crea la configurazione dell'editor sul backend PHP. Imposta l'estensione del file, il titolo, l'URL di download assoluto e una chiave del documento. Mantieni questa chiave invariata per gli editor simultanei della stessa versione; modificala quando PHP sostituisce il codice sorgente con una nuova versione.

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

Applica le autorizzazioni sui file prima di generare l'URL. Non esporre le credenziali di accesso alla memoria né aggirare l'autorizzazione; i link privati ​​o locali potrebbero inoltre richiedere un token in base alle regole di ONLYOFFICE.

Consultare il documento di riferimento sulla configurazione e la guida all'installazione self-hosted di ONLYOFFICE per i campi obbligatori e il percorso dello script API.

Carica l'editor e firma la sua configurazione

JWT sta per JSON Web Token, un token firmato che consente a ONLYOFFICE di verificare che la configurazione non sia stata modificata durante la trasmissione. La convalida JWT è abilitata per impostazione predefinita nelle implementazioni correnti; firma la configurazione dell'editor con il segreto del token del browser corrispondente configurato in Docs. Se la tua configurazione utilizza un segreto del token in uscita separato, convalida anche le callback con tale segreto della casella di posta in uscita. A partire da Docs 7.2, le installazioni Docker possono generare automaticamente un segreto, quindi imposta e conserva segreti stabili per l'ambiente di produzione.

La guida ufficiale alla firma di ONLYOFFICE mostra il codice PHP con il firebase/php-jwtpacchetto aggiornato. Installalo con composer require firebase/php-jwt, quindi firma la configurazione completa nel backend prima di restituirla alla 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');

Mantieni il segreto fuori dal codice del browser e dal controllo di versione. Carica https://docs.example.com/web-apps/apps/api/documents/api.jse passa il JSON firmato a 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 JSON in modo sicuro json_encodeo recupera la configurazione firmata da un endpoint same-origin; non concatenare valori non attendibili in JavaScript. La guida alla firma documenta HMAC-SHA256. Per Docs 8.1 e versioni successive con bilanciamento del carico, lo script API può includere il parametro di query documentato shardkey; un singolo server non ne ha bisogno.

Salva le modifiche tramite una funzione di callback PHP.

Dopo la modifica, Document Server invia una richiesta POST a callbackUrl. Lo stato 2 indica che la modifica è completa e il file è pronto per essere salvato; lo stato 6 indica un salvataggio forzato. La callback include un URL di download temporaneo per il file modificato. Scaricalo e sostituisci in modo atomico la versione memorizzata oppure crea una nuova versione in base alla politica di revisione della tua app. Restituisci il controllo {"error":0}solo dopo che la scrittura nella memoria è andata a buon fine.

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

L'esempio presuppone l' Authorization: Bearerintestazione JWT in uscita predefinita e il segreto outbox corrispondente. Adattalo se il tuo server utilizza un'intestazione o un token del corpo diversi. Lo strumento di download dovrebbe consentire l'accesso solo al tuo host Docs, controllare la risposta e sostituire in modo sicuro il file previsto. Non fidarti mai di un URL arbitrario o di una chiave di documento non firmata.

Dopo un salvataggio riuscito, restituisci JSON contenente {"error":0}. Consulta il riferimento di callback per stati e payload e il ciclo di vita del salvataggio per la tempistica del callback.

Verifica l'intero viaggio di andata e ritorno

Apri un file DOCX di prova come utente autorizzato, apporta una piccola modifica e chiudi l'editor. Verifica che la chiave di callback e lo stato corrispondano al file previsto, controlla che la tua app abbia memorizzato i nuovi byte, quindi riapri il documento. Se il caricamento non riesce, controlla il percorso dello script API e il token di configurazione; se il salvataggio non riesce, controlla la raggiungibilità del callback, la convalida JWT, la risposta JSON e i log di archiviazione PHP.

ONLYOFFICE pubblica un esempio di integrazione PHP e un'applicazione di esempio PHP, ma avverte esplicitamente che le integrazioni di esempio non dispongono di protezioni di produzione come l'autorizzazione all'archiviazione e la convalida delle richieste di salvataggio. Utilizzatele per comprendere il flusso dell'API, quindi mantenete i controlli di accesso e la sicurezza delle callback della vostra applicazione.