Comment intégrer ONLYOFFICE Docs à une application PHP personnalisée

Commencez par définir les limites de l'intégration : une application PHP personnalisée n'envoie pas directement les données du document à l'éditeur. Votre application authentifie l'utilisateur, stocke le fichier, fournit une URL accessible au serveur ONLYOFFICE Docs et expose un point de terminaison de rappel où Docs envoie les mises à jour d'enregistrement. Le navigateur charge le script de l'API Docs et crée un éditeur dans un élément de page. Ce modèle fonctionne avec un serveur Docs auto-hébergé lorsque le navigateur et les deux serveurs peuvent accéder aux URL requises.

Note de version importante : ONLYOFFICE a annoncé la sortie de Docs 9.4 le 19 mai 2026. Cette annonce précise que l’édition communautaire open source ne limite plus les connexions simultanées à 20 personnes à partir de la version 9.4. Cela modifie un aspect du déploiement pour les utilisateurs de la communauté ; toutefois, l’accès au stockage et aux points de terminaison de rappel, la signature JWT et la vérification de la licence restent obligatoires. Veuillez consulter les conditions de la version et de la licence de Docs que vous prévoyez de déployer. L’intégration ci-dessous suit le flux d’API Docs documenté.

Les quatre illustrations d'écran sont des exemples conceptuels et non des captures d'écran du produit. La liste des documents et la mise en page du projet PHP sont spécifiques à l'application, et l'interface de l'éditeur peut varier selon la version de Docs et sa configuration.

Avant de connecter quoi que ce soit

Vous avez besoin d'une application PHP, d'un serveur ONLYOFFICE Docs et d'un espace de stockage de documents géré par votre application. Docs et l'application PHP peuvent s'exécuter sur des hôtes ou des conteneurs distincts. Le navigateur de l'utilisateur doit accéder au serveur Docs pour télécharger les ressources de son éditeur. Par ailleurs, le serveur Docs doit accéder à l'URL des documents et à l'URL de rappel de votre application. Un nom d'hôte tel que « /localhost » localhostpose souvent problème dans une configuration de conteneur, car il pointe vers le conteneur effectuant la requête, et non vers l'autre service.

Utilisez HTTPS pour les points de terminaison publics, stockez votre secret JWT en dehors du système de contrôle de version et définissez la correspondance entre les permissions des documents et les utilisateurs de votre application. Pour le développement local, un réseau privé ou un tunnel peut être nécessaire pour que Docs puisse récupérer un fichier de développement ; en production, utilisez des routes stables et authentifiées. Le guide d'installation Docker officiel d'ONLYOFFICE Docs explique l'installation et la configuration JWT. Les exemples de secrets fournis sont donnés à titre indicatif ; remplacez-les par un secret privé et assurez-vous de sa cohérence avec la configuration de Docs.

Étape 1 : Définir les routes des documents et du réseau

Commencez par rendre le document accessible via une URL absolue et stable que Docs peut récupérer. N'indiquez pas à l'éditeur un chemin de session PHP ni une URL relative réservée au navigateur. Créez plutôt une route d'application authentifiée, par exemple : ` https://app.example.com/docs/42/download<URL_42>`. Avant de renvoyer des octets, cette route doit vérifier l'accès de l'utilisateur connecté au document 42. Si le serveur Docs ne peut pas réutiliser la session du navigateur, fournissez une URL de téléchargement temporaire et limitée dans le temps, ou un autre mécanisme d'autorisation serveur à serveur.

Créez également une route de rappel https://app.example.com/onlyoffice/callback?document=42. Celle-ci doit accepter une requête POST du serveur Docs, identifier le fichier cible de manière sécurisée et être accessible depuis le réseau du serveur Docs. Le paramètre d'URL renvoyé par Docs est un lien de téléchargement temporaire pour le document modifié ; il ne s'agit pas du fichier enregistré dans votre base de données. Votre fonction de rappel doit récupérer ces données et les enregistrer dans votre espace de stockage.

ONLYOFFICE présente l'éditeur et le service de stockage de documents comme deux éléments distincts : Docs assure le service d'édition, tandis que l'intégrateur fournit le gestionnaire et le stockage des documents. Consultez la présentation officielle « Fonctionnement » avant de choisir votre architecture réseau et vos points de terminaison.

Étape 2 : Créer la configuration de l’éditeur en PHP

Pour un document Word, la configuration identifie le type de fichier source, une clé de document unique, le titre, l'URL de téléchargement, le mode d'édition et l'URL de rappel. Cette clé est essentielle : elle permet à Docs d'identifier la session d'édition et de réutiliser un document mis en cache. Générez une nouvelle clé lorsque le fichier est modifié et enregistré ; réutilisez la même clé pour les clients qui rejoignent la même session active. Veillez à respecter les limites de caractères et de longueur indiquées pour la clé.

L'exemple ci-dessous suppose l'utilisation de Composer et de la bibliothèque Firebase PHP-JWT. Remplacez chaque URL et requête de stockage par vos propres services prenant en charge l'autorisation.

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

Le jeton document.urldoit être lisible par le serveur de documentation, et non pas seulement par le navigateur. Il document.keydoit suivre une révision enregistrée : si vous réutilisez une clé obsolète après la modification du fichier source, la documentation risque d’ouvrir du contenu mis en cache. Le jeton est un jeton Web JSON (JWT) signé, un format standard permettant de prouver que la configuration provient d’un serveur détenant le secret partagé. Le secret de signature reste sur le serveur PHP ; ne l’intégrez jamais dans JavaScript ni dans HTML.

Les noms de code ` <nom_de_code>` docsDownloadUrl(), callbackUrl()`<nom_de_code>` et ` editingKey()<nom_de_code>` correspondent à des méthodes d'application et non à des fonctions PHP intégrées à ONLYOFFICE. L'implémentation exacte dépend de votre système de stockage, de votre framework web et de votre modèle de contrôle d'accès. ONLYOFFICE publie un kit de développement logiciel (SDK) d'intégration PHP officiel et des exemples multilingues, mais le dépôt précise que ses applications de démonstration sont des exemples de test nécessitant des modifications pour la production. Consultez le guide officiel sur les signatures JWT et les exemples d'intégration officiels .

Étape 3 : Charger l’API Docs et afficher l’éditeur

N'affichez la configuration signée sur la page qu'une fois l'utilisateur authentifié par la route PHP. Échappez le JSON pour un contexte JavaScript et dimensionnez le conteneur de l'éditeur pour qu'il soit utilisable. Le navigateur récupère les données api.jsdepuis votre serveur de documentation ; le constructeur remplace l'élément d'espace réservé par une iframe d'éditeur.

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

Les balises ci-dessus sont affichées sous forme d'exemple de balisage échappé afin qu'elles puissent être interprétées comme du code. Sur votre page, chargez le script API depuis l'URL du serveur Docs hébergeant votre éditeur. Si la zone d'édition est vide, vérifiez d'abord que le navigateur peut ouvrir cette URL, que l'application et Docs utilisent des certificats HTTPS compatibles et que les outils de développement du navigateur n'affichent aucun blocage de contenu mixte ou de requête réseau. La documentation de DocsAPI.DocEditor explique le comportement des espaces réservés et des iframes.

Étape 4 : Enregistrer les mises à jour via le rappel

Lorsque la modification est terminée, Docs envoie une requête POST editorConfig.callbackUrl. La statusvaleur de cette requête détermine l'action à effectuer par votre gestionnaire. Le statut 2 indique que le document est prêt à être enregistré après la fermeture de la session de modification. Le statut 6 indique que l'état actuel a été enregistré de force, mais que la session de modification peut se poursuivre. Les autres valeurs indiquent un état de connexion, l'absence de modification ou une erreur ; ne considérez pas chaque notification comme l'ouverture d'un nouveau fichier.

Un gestionnaire de rappel doit analyser le corps JSON, valider la requête selon les paramètres de la boîte d'envoi JWT activés sur votre serveur Docs, associer le rappel à un document appartenant à l'intégration actuelle et gérer les états de sauvegarde de manière appropriée. En cas de statut 2 ou 6, téléchargez le document publié urldepuis le serveur Docs, vérifiez que le téléchargement a réussi et remplacez le fichier enregistré de manière atomique afin qu'un téléchargement partiel ne puisse pas corrompre l'original. Retournez la réponse de rappel attendue par l'API actuelle, généralement un objet JSON dont le errorstatut est défini 0après un traitement réussi.

<?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()Ces instructions sont des exemples et replaceAtomically()non des routines de production complètes. Utilisez un client HTTP avec gestion des délais d'attente, vérification TLS, limitation de la taille des réponses et contrôle des destinations sortantes ; n'accédez pas à une URL arbitraire sans précautions. Vérifiez la signature/le jeton du rappel à l'aide de la méthode documentée pour la version et la configuration exactes que vous utilisez. La documentation officielle du gestionnaire de rappel répertorie les statuts et indique quand l'URL du fichier modifié est présente.

Tester le chemin de sauvegarde complet

1. Ouvrez un petit fichier DOCX en tant qu'utilisateur disposant des autorisations nécessaires pour le modifier.
2. Apportez une modification visible, attendez que l'éditeur indique qu'elle est enregistrée, puis fermez le document.
3. Consultez les journaux PHP et Docs. Vérifiez que la fonction de rappel a bien été reçue et que votre route de stockage a téléchargé le fichier renvoyé.
4. Rouvrez le fichier depuis l'application et vérifiez que la modification est bien prise en compte. Testez ensuite séparément la fermeture du fichier sans modification et l'ouverture simultanée d'un second éditeur.

Le guide officiel sur le flux d'enregistrement indique que, dans la plupart des cas, l'enregistrement s'effectue environ 10 secondes après la fin de la modification ; la taille du fichier, sa complexité, le temps de conversion et les performances du serveur peuvent induire ce délai. Ne signalez pas l'enregistrement comme terminé simplement parce que l'iframe de l'éditeur s'est fermé ; vérifiez la notification et la version enregistrée.

Échecs d'intégration courants

• L'éditeur s'ouvre mais ne parvient pas à charger le fichier : testez-le document.urldepuis le réseau du serveur Docs, et pas seulement depuis votre navigateur de bureau.
• JWT rejeté : comparez le secret et la configuration HS256 des deux côtés ; vérifiez que le jeton signe l’objet de configuration exact envoyé.
• Les modifications disparaissent : vérifiez la disponibilité des rappels, la gestion de l’état, la récupération des URL de téléchargement temporaires et les autorisations de remplacement de fichiers.
• Une ancienne version apparaît : veuillez générer une nouvelle clé de document après chaque révision enregistrée et éviter de diffuser involontairement des URL sources mises en cache.
• Fonctionne en local, échoue en production : vérifiez les chemins des proxys inverses, les certificats TLS, le DNS du conteneur, les règles du pare-feu et le nom d’hôte public ou interne utilisé dans chaque URL.

Voici la procédure principale pour intégrer ONLYOFFICE Docs à une application PHP personnalisée : autoriser et servir le fichier source, signer une configuration d’éditeur par document, afficher l’éditeur API officiel, puis traiter de manière sécurisée les rappels d’enregistrement. Les détails de production (authentification, stockage, signature d’URL, vérification des rappels et politique de concurrence) doivent correspondre à votre application et à la version exacte de Docs que vous déployez.