Come integrare ONLYOFFICE Docs con un'applicazione PHP personalizzata

Partiamo dal confine dell'integrazione: un'applicazione PHP personalizzata non invia i byte del documento direttamente all'editor. La tua applicazione autentica l'utente, memorizza il file, fornisce un URL che il server ONLYOFFICE Docs può recuperare ed espone un endpoint di callback a cui Docs invia gli aggiornamenti di salvataggio. Il browser carica lo script dell'API di Docs e crea un editor in un elemento della pagina. Questo modello funziona con un server Docs self-hosted quando il browser ed entrambi i server possono raggiungere gli URL richiesti.

Nota importante sulla versione: ONLYOFFICE ha annunciato la versione 9.4 di Docs il 19 maggio 2026. L'annuncio specifica che la Community Edition open-source ha rimosso il precedente limite di 20 connessioni simultanee a partire dalla versione 9.4. Ciò modifica un aspetto relativo all'implementazione per gli utenti della Community; non elimina tuttavia la necessità di endpoint di archiviazione e callback raggiungibili, firma JWT o revisione della licenza. Verificare i termini di rilascio e di licenza per la versione esatta di Docs che si intende implementare. L'integrazione descritta di seguito segue il flusso API di Docs attualmente documentato.

Le quattro schermate illustrate sono esempi concettuali, non screenshot del prodotto. L'elenco dei documenti e il layout del progetto PHP sono specifici dell'applicazione e l'interfaccia dell'editor può variare a seconda della versione e della configurazione di Docs.

Prima di collegare qualsiasi cosa

È necessaria un'applicazione PHP, un server ONLYOFFICE Docs e un sistema di archiviazione documenti controllato dall'applicazione stessa. Docs e l'applicazione PHP possono essere eseguiti su host o container separati. Il browser dell'utente deve raggiungere il server Docs per scaricare le risorse dell'editor. Separatamente, il server Docs deve raggiungere l'URL del documento e l'URL di callback dell'applicazione. Un nome host come localhostspesso non funziona in una configurazione a container perché punta al container che effettua la richiesta, non all'altro servizio.

Utilizza HTTPS per gli endpoint pubblici, mantieni il tuo segreto JWT al di fuori del controllo di versione e decidi come mappare le autorizzazioni dei documenti agli utenti della tua applicazione. Per lo sviluppo locale, potrebbe essere necessaria una rete privata o un tunnel affinché Docs possa recuperare un file di sviluppo; in produzione è consigliabile utilizzare percorsi stabili e autenticati. La guida ufficiale all'installazione di ONLYOFFICE Docs in Docker spiega l'installazione e la configurazione del JWT. I segreti di esempio sono solo a scopo illustrativo: sostituiscili con un segreto privato e mantienilo coerente con la configurazione di Docs.

Passaggio 1: Definire i percorsi dei documenti e della rete

Inizia rendendo il documento disponibile a un URL assoluto e stabile che Docs possa recuperare. Non indirizzare l'editor a un percorso di sessione PHP o a un URL relativo accessibile solo dal browser. Crea invece una route applicativa autenticata, ad esempio https://app.example.com/docs/42/download. Prima di restituire i byte, tale route dovrebbe verificare l'accesso dell'utente autenticato al documento 42. Se il server Docs non può riutilizzare la sessione del browser dell'utente, emetti un URL di download temporaneo e con ambito limitato o utilizza un altro meccanismo di autorizzazione server-to-server.

Crea anche una route di callback come https://app.example.com/onlyoffice/callback?document=42. Deve accettare una richiesta POST dal server Docs, identificare il file di destinazione in modo sicuro ed essere raggiungibile dalla rete del server Docs. Il parametro URL che Docs invia tramite POST è un link di download temporaneo per il documento modificato; non è il file salvato nel tuo database. La tua callback deve recuperare quei byte e scriverli nella tua memoria.

ONLYOFFICE descrive il servizio di modifica e quello di archiviazione dei documenti come due componenti separati: Docs fornisce il servizio di modifica, mentre l'integratore fornisce il gestore e l'archiviazione dei documenti. Consulta la panoramica ufficiale "Come funziona" prima di scegliere l'endpoint e la configurazione di rete.

Passaggio 2: Creare la configurazione dell'editor in PHP

Per un documento Word, la configurazione identifica il tipo di file sorgente, una chiave univoca del documento, il titolo, l'URL di download, la modalità di modifica e l'URL di callback. La chiave è importante: consente a Documenti di identificare la sessione di modifica e di riutilizzare un documento memorizzato nella cache. Genera una nuova chiave quando il file viene modificato e salvato; riutilizza la stessa chiave per i client che devono accedere alla stessa sessione attiva del documento. Assicurati che la chiave rispetti i limiti di caratteri e lunghezza specificati nella documentazione.

L'esempio seguente presuppone l'utilizzo di Composer e della libreria Firebase PHP-JWT. Sostituisci ogni URL di esempio e ogni ricerca nello storage con i tuoi servizi che gestiscono l'autorizzazione.

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

Il token document.urldeve essere leggibile dal server Docs, non solo dal browser. document.keyDeve tenere traccia di una revisione salvata: se si riutilizza una chiave obsoleta dopo che il file sorgente è stato modificato, Docs potrebbe aprire contenuti memorizzati nella cache. Il token è un JSON Web Token (JWT) firmato, un formato standard per dimostrare che la configurazione proviene da un server che detiene il segreto condiviso. Il segreto di firma rimane sul server PHP; non inserirlo mai in JavaScript o HTML.

I nomi in codice docsDownloadUrl(), callbackUrl(), e editingKey()sono metodi dell'applicazione, non funzioni PHP integrate di ONLYOFFICE. L'implementazione esatta dipende dal sistema di archiviazione, dal framework web e dal modello di controllo degli accessi. ONLYOFFICE pubblica un SDK di integrazione PHP ufficiale ed esempi multilingue, ma il repository descrive esplicitamente le sue applicazioni demo come esempi di test che necessitano di modifiche per l'ambiente di produzione. Consultare la guida ufficiale alla firma JWT e gli esempi di integrazione ufficiali .

Passaggio 3: Carica l'API della documentazione e visualizza l'editor

Visualizza la configurazione firmata nella pagina solo dopo che la route PHP ha autorizzato l'utente. Esegui l'escape del JSON per un contesto JavaScript e rendi il contenitore dell'editor sufficientemente alto da essere utilizzabile. Il browser recupera i dati api.jsdal tuo server di documentazione; il costruttore sostituisce l'elemento segnaposto con un iframe dell'editor.

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

I tag sopra riportati sono mostrati come markup di esempio con caratteri di escape, in modo che possano essere letti come codice. Nella tua pagina reale, carica lo script API dall'URL del server Docs che ospita il tuo editor. Se l'area dell'editor è vuota, verifica innanzitutto che il browser possa aprire quell'URL, che l'app e Docs utilizzino certificati HTTPS compatibili e che gli strumenti per sviluppatori del browser non mostrino richieste di rete o contenuti misti bloccati. La documentazione di DocsAPI.DocEditor spiega il comportamento dei segnaposto e degli iframe.

Passaggio 4: Salva gli aggiornamenti tramite la funzione di callback

Al termine della modifica, Docs invia una richiesta POST a editorConfig.callbackUrl. Il statusvalore determina cosa deve fare il gestore. Lo stato 2 significa che il documento è pronto per essere salvato dopo la chiusura della modifica. Lo stato 6 significa che lo stato corrente è stato salvato tramite un'operazione di salvataggio forzato, mentre la sessione di modifica può continuare. Altri valori indicano lo stato della connessione, di nessuna modifica o di errore; non trattare ogni callback come un nuovo file.

Un gestore di callback dovrebbe analizzare il corpo JSON, convalidare la richiesta in base alle impostazioni JWT outbox abilitate sul server Docs, mappare il callback a un documento di proprietà dell'integrazione corrente e gestire gli stati di salvataggio in modo appropriato. In caso di stato 2 o 6, scaricare il documento inviato urldal server Docs, verificare che il download sia andato a buon fine e sostituire il file memorizzato in modo atomico, in modo che un download parziale non possa corrompere l'originale. Restituire la risposta di callback prevista dall'API corrente, in genere un oggetto JSON con errorimpostato su 0dopo l'elaborazione corretta.

<?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()e replaceAtomically()sono segnaposto, non routine di produzione complete. Utilizzare un client HTTP con timeout, verifica TLS, limiti di dimensione della risposta e destinazioni in uscita controllate; non recuperare un URL arbitrario senza misure di sicurezza. Verificare la firma/il token del callback utilizzando il metodo documentato per la versione e la configurazione esatte di Docs in esecuzione. Il riferimento ufficiale del gestore di callback elenca gli stati e quando è presente l'URL del file modificato.

Verifica il percorso di salvataggio completo

1. Apri un piccolo file DOCX come utente autorizzato a modificarlo.
2. Apporta una modifica visibile, attendi che l'editor ne confermi il salvataggio e chiudi il documento.
3. Esamina i log di PHP e della documentazione. Verifica che la callback sia arrivata a destinazione e che il percorso di archiviazione abbia scaricato il file restituito.
4. Riapri il file dall'applicazione e verifica che la modifica sia stata mantenuta. Esegui separatamente una prova di chiusura senza modifiche e una prova con un secondo editor simultaneo.

La guida ufficiale al flusso di salvataggio indica che, nella maggior parte dei casi, il salvataggio si completa circa 10 secondi dopo la fine della modifica; le dimensioni del file, la complessità, il tempo di conversione e le prestazioni del server possono influire sul ritardo. Non comunicare all'utente che il file è stato "salvato" solo perché l'iframe dell'editor si è chiuso: verifica la callback e la revisione salvata.

Errori di integrazione comuni

• L'editor si apre ma non riesce a caricare il file: prova document.urlad accedere dalla rete del server di Documenti, non solo dal browser del tuo computer.
• JWT rifiutato: confrontare il segreto e la configurazione HS256 su entrambi i lati; confermare che il token firmi l'oggetto di configurazione esatto che viene inviato.
• Le modifiche scompaiono: verifica la raggiungibilità del callback, la gestione dello stato, il recupero dell'URL di download temporaneo e le autorizzazioni di sostituzione dei file.
• Viene visualizzata la vecchia versione: emetti una nuova chiave del documento dopo una revisione salvata ed evita di servire involontariamente URL di origine memorizzati nella cache.
• Funziona in locale, ma non in produzione: verificare i percorsi del reverse proxy, i certificati TLS, il DNS del container, le regole del firewall e il nome host pubblico e interno utilizzato in ciascun URL.

Questo è il percorso principale per integrare ONLYOFFICE Docs con un'applicazione PHP personalizzata: autorizzare e distribuire il file sorgente, firmare una configurazione dell'editor per ogni documento, eseguire il rendering dell'editor API ufficiale e infine elaborare in modo sicuro le callback di salvataggio. I dettagli di produzione (autenticazione, archiviazione, firma dell'URL, verifica delle callback e politica di concorrenza) devono corrispondere alla propria applicazione e alla versione esatta di Docs distribuita.