Connectez une application PHP à ONLYOFFICE Docs et enregistrez les modifications.

Une application PHP personnalisée s'intègre à ONLYOFFICE Docs en fournissant une URL de document que Docs peut récupérer, en chargeant l'API JavaScript de Docs dans le navigateur et en recevant une fonction de rappel qui enregistre le fichier modifié. La signature JWT doit être conservée sur le serveur PHP, et l'URL du document ainsi que l'URL de rappel doivent être accessibles depuis le réseau où ONLYOFFICE Docs est exécuté.

De nombreux échecs d'intégration proviennent d'une confusion entre les adresses vues par le navigateur, PHP et le serveur de documents. Testez chaque route depuis le réseau qui l'utilise.

Préparer l'application PHP et le serveur de documents

ONLYOFFICE Docs fournit l'éditeur de documents. Votre application reste le gestionnaire de documents et le service de stockage : elle authentifie les utilisateurs, détermine les fichiers qu'ils peuvent ouvrir, fournit le fichier source et enregistre le résultat. Installez Document Server séparément, puis vérifiez son /healthcheckpoint de terminaison avant de déboguer le code de votre application.

Utilisez trois adresses accessibles dans votre configuration :

• URL de la documentation : l’adresse utilisée par le navigateur de l’utilisateur pour charger l’éditeur et son API JavaScript.
• URL du document : adresse absolue que le serveur de documents peut utiliser pour télécharger le fichier source depuis le stockage PHP.
• URL de rappel : une adresse absolue à laquelle le serveur de documents peut envoyer des données après modification afin que PHP puisse enregistrer les changements.

Par exemple, https://docs.example.comon peut servir l'éditeur, tandis que `<serveur>` https://app.example.com/files/42/downloadet https://app.example.com/onlyoffice/callback`<script>` pointent vers PHP. Testez la connectivité entre le navigateur et la documentation, et entre la documentation et PHP. En déploiement, `<serveur>` localhostdésigne la machine ou le conteneur actuel ; il s'agit donc généralement d'une adresse inter-services incorrecte.

Créer une configuration de document pour un fichier autorisé

Pour une requête ouverte authentifiée, chargez les métadonnées du fichier et configurez l'éditeur côté serveur PHP. Définissez l'extension du fichier, son titre, son URL de téléchargement absolue et une clé de document. Conservez cette clé pour les éditeurs simultanés de la même version ; modifiez-la lorsque PHP remplace le code source par une nouvelle version.

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

Vérifiez les permissions d'accès aux fichiers avant de générer l'URL. Ne divulguez pas les identifiants de stockage et ne contournez pas l'autorisation ; les liens privés ou locaux peuvent également nécessiter un jeton conformément aux règles d'ONLYOFFICE.

Consultez le guide de configuration des documents et le guide d'installation auto-hébergé d'ONLYOFFICE pour connaître les champs obligatoires et le chemin d'accès au script API.

Chargez l'éditeur et signez sa configuration

JWT signifie JSON Web Token, un jeton signé permettant à ONLYOFFICE de vérifier que la configuration n'a pas été modifiée lors de sa transmission. La validation JWT est activée par défaut dans les déploiements actuels ; signez la configuration de l'éditeur avec le secret de jeton de navigateur correspondant configuré dans la documentation. Si votre configuration utilise un secret de jeton sortant distinct, validez également les rappels avec ce secret. À partir de la version 7.2 de la documentation, les installations Docker peuvent générer un secret automatiquement ; assurez-vous donc de définir et de conserver des secrets stables pour la production.

Le guide officiel de signature ONLYOFFICE présente le code PHP avec le firebase/php-jwtpackage maintenu. Installez-le composer require firebase/php-jwt, puis signez la configuration complète dans l'interface d'administration avant de la renvoyer à la page :

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

Ne comportez aucun secret dans le code du navigateur ni dans le système de gestion de versions. Chargez https://docs.example.com/web-apps/apps/api/documents/api.jset transmettez le JSON signé à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>

Encodez le JSON de manière sécurisée json_encodeou récupérez la configuration signée depuis un point de terminaison de même origine ; n’intégrez pas de valeurs non fiables dans le JavaScript. Le guide de signature décrit HMAC-SHA256. Pour les serveurs Docs 8.1 et versions ultérieures avec répartition de charge, le script API peut inclure le shardkeyparamètre de requête documenté ; un serveur unique n’en a pas besoin.

Enregistrer les modifications via un rappel PHP

Après modification, le serveur de documents envoie une requête POST callbackUrl. Le statut 2 indique que la modification est terminée et que le fichier est prêt à être enregistré ; le statut 6 correspond à un enregistrement forcé. La réponse inclut une URL de téléchargement temporaire pour le fichier modifié. Téléchargez-le et remplacez instantanément la version enregistrée, ou créez une nouvelle version conformément à la politique de révision de votre application. Ne retournez {"error":0}que lorsque l'écriture dans le stockage a réussi.

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

Cet exemple suppose l'utilisation Authorization: Bearerde l'en-tête JWT sortant par défaut et du secret de boîte d'envoi correspondant. Adaptez-le si votre serveur utilise un en-tête ou un jeton de corps différent. L'assistant de téléchargement doit autoriser uniquement votre hébergeur de documents, vérifier la réponse et remplacer le fichier attendu en toute sécurité. Ne faites jamais confiance à une URL arbitraire ni à une clé de document non signée.

Après une sauvegarde réussie, renvoyez un JSON contenant les données {"error":0}. Consultez la documentation relative aux rappels pour connaître les statuts et les charges utiles, ainsi que le cycle de vie de la sauvegarde pour connaître le moment du rappel.

Vérifiez l'aller-retour complet

Ouvrez un fichier DOCX de test en tant qu'utilisateur autorisé, effectuez une modification mineure, puis fermez l'éditeur. Vérifiez que la clé de rappel et le statut correspondent au fichier attendu, assurez-vous que votre application a bien enregistré les nouveaux octets, puis rouvrez le document. En cas d'échec du chargement, vérifiez la route du script API et le jeton de configuration ; en cas d'échec de l'enregistrement, vérifiez l'accessibilité du rappel, la validation JWT, la réponse JSON et les journaux de stockage PHP.

ONLYOFFICE propose un exemple d'intégration PHP et une application PHP d'exemple, mais précise que ces exemples d'intégration ne comportent pas les protections nécessaires à la production, telles que l'autorisation de stockage et la validation des requêtes d'enregistrement. Utilisez-les pour comprendre le flux de l'API, puis mettez en place les contrôles d'accès et la sécurité des rappels propres à votre application.