Conecta una aplicación PHP a ONLYOFFICE Docs y guarda los cambios.

Una aplicación PHP personalizada se integra con ONLYOFFICE Docs proporcionando una URL de documento que Docs puede obtener, cargando la API JavaScript de Docs en el navegador y aceptando una devolución de llamada que almacena el archivo editado. Mantenga la firma JWT en el servidor PHP y asegúrese de que tanto la URL del documento como la URL de devolución de llamada sean accesibles desde la red donde se ejecuta ONLYOFFICE Docs.

Muchos fallos de integración se deben a la confusión entre las direcciones que ven el navegador, PHP y el servidor de documentos. Pruebe cada ruta desde la red que la utiliza.

Prepara la aplicación PHP y el servidor de documentos.

ONLYOFFICE Docs proporciona el editor de documentos. Su aplicación sigue siendo el gestor y servicio de almacenamiento de documentos: autentica a los usuarios, decide qué archivos pueden abrir, proporciona el archivo de origen y guarda el resultado. Instale Document Server por separado y verifique su /healthcheckpunto final antes de depurar el código de la aplicación.

Utilice tres direcciones accesibles en su configuración:

• URL de la documentación: la dirección que utiliza el navegador del usuario para cargar el editor y su API de JavaScript.
• URL del documento: una dirección absoluta que el servidor de documentos puede usar para descargar el archivo fuente desde el almacenamiento PHP.
• URL de devolución de llamada: una dirección absoluta a la que el servidor de documentos puede enviar una solicitud POST después de editar, para que PHP pueda almacenar los cambios.

Por ejemplo, https://docs.example.compuede servir al editor, mientras que https://app.example.com/files/42/downloady https://app.example.com/onlyoffice/callbackapuntan a PHP. Prueba la accesibilidad del navegador a la documentación y de la documentación a PHP. En la implementación, localhostsignifica la máquina o contenedor actual, por lo que suele ser una dirección entre servicios incorrecta.

Cree una configuración de documento para un archivo autorizado.

Para una solicitud de apertura autenticada, carga los metadatos del archivo y configura el editor en el servidor PHP. Establece la extensión del archivo, el título, la URL de descarga absoluta y una clave de documento. Mantén esa clave estable para editores concurrentes de la misma versión; cámbiala cuando PHP reemplace el código fuente con una nueva versión.

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

Aplique los permisos de archivo antes de generar la URL. No exponga las credenciales de almacenamiento ni omita la autorización; los enlaces privados o locales también pueden requerir un token según las reglas de ONLYOFFICE.

Consulte la referencia de configuración de documentos y la guía de instalación autohospedada de ONLYOFFICE para obtener información sobre los campos obligatorios y la ruta del script de la API.

Carga el editor y firma su configuración.

JWT significa JSON Web Token, un token firmado que permite a ONLYOFFICE verificar que la configuración no se haya modificado durante la transmisión. La validación JWT está habilitada de forma predeterminada en las implementaciones actuales; firme la configuración del editor con el secreto browser-token correspondiente configurado en Docs. Si su configuración utiliza un secreto outgoing-token independiente, valide también las devoluciones de llamada con ese secreto outbox. A partir de Docs 7.2, las instalaciones de Docker pueden generar un secreto automáticamente, así que configure y conserve secretos estables para producción.

La guía oficial de firmas de ONLYOFFICE muestra el código PHP con el firebase/php-jwtpaquete mantenido. Instálelo con composer require firebase/php-jwt, luego firme la configuración completa en el backend antes de devolverla a la página:

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

Mantén el secreto fuera del código del navegador y del control de versiones. Carga https://docs.example.com/web-apps/apps/api/documents/api.jsy pasa el JSON firmado 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>

Codifique JSON de forma segura json_encodeo obtenga la configuración firmada desde un punto final del mismo origen; no concatene valores no confiables en JavaScript. La guía de firmas documenta HMAC-SHA256. Para Docs 8.1 y versiones posteriores con balanceo de carga, el script de la API puede incluir el parámetro de consulta documentado shardkey; un servidor único no lo necesita.

Guarda los cambios mediante una función de devolución de llamada de PHP.

Tras la edición, Document Server envía una solicitud POST callbackUrl. El estado 2 indica que la edición ha finalizado y el archivo está listo para guardarse; el estado 6 indica un guardado forzado. La devolución de llamada incluye una URL de descarga temporal para el archivo editado. Descárguelo y reemplace atómicamente la versión almacenada, o cree una nueva versión según la política de revisiones de su aplicación. Devuelva el resultado {"error":0}solo después de que la escritura en el almacenamiento se haya realizado correctamente.

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

El ejemplo asume el Authorization: Bearerencabezado JWT saliente predeterminado y la clave secreta de la bandeja de salida correspondiente. Adáptelo si su servidor utiliza un encabezado o token de cuerpo diferente. El asistente de descarga solo debe permitir el acceso a su servidor Docs, verificar la respuesta y reemplazar de forma segura el archivo esperado. Nunca confíe en una URL arbitraria ni en una clave de documento sin firmar.

Tras un guardado exitoso, devuelve un JSON que contiene {"error":0}. Consulta la referencia de la función de devolución de llamada para conocer los estados y las cargas útiles, y el ciclo de vida del guardado para conocer los tiempos de la función de devolución de llamada.

Verificar el viaje de ida y vuelta completo

Abra un archivo DOCX de prueba como usuario autorizado, realice una pequeña edición y cierre el editor. Confirme que la clave de devolución de llamada y el estado coinciden con el archivo deseado, verifique que su aplicación haya almacenado los nuevos bytes y vuelva a abrir el documento. Si la carga falla, revise la ruta del script de la API y el token de configuración; si el guardado falla, verifique la accesibilidad de la devolución de llamada, la validación JWT, la respuesta JSON y los registros de almacenamiento de PHP.

ONLYOFFICE publica un ejemplo de integración PHP y una aplicación de muestra PHP, pero advierte explícitamente que las integraciones de muestra carecen de protecciones de producción, como la autorización de almacenamiento y la validación de solicitudes de guardado. Úselas para comprender el flujo de la API y, a continuación, mantenga las comprobaciones de acceso y la seguridad de las devoluciones de llamada de su propia aplicación.