Подключите PHP-приложение к ONLYOFFICE Docs и сохраняйте внесенные изменения.

Пользовательское PHP-приложение интегрируется с ONLYOFFICE Docs, предоставляя URL-адрес документа, который может быть получен из Docs, загружая JavaScript API Docs в браузер и принимая обратный вызов, который сохраняет отредактированный файл. Подпись JWT сохраняется на PHP-сервере, а URL-адрес документа и URL-адрес обратного вызова доступны из сети, где работает ONLYOFFICE Docs.

Многие сбои интеграции возникают из-за путаницы адресов, которые видят браузер, PHP и сервер документов. Проверьте каждый маршрут из сети, которая его использует.

Подготовьте PHP-приложение и сервер документов.

ONLYOFFICE Docs предоставляет редактор документов. Ваше приложение остается менеджером документов и службой хранения: оно аутентифицирует пользователей, определяет, какие файлы они могут открывать, предоставляет исходный файл и сохраняет результат. Установите Document Server отдельно, а затем проверьте его /healthcheckконечную точку, прежде чем отлаживать код приложения.

В конфигурации укажите три доступных адреса:

• URL документации: адрес, который браузер пользователя использует для загрузки редактора и его JavaScript API.
• URL документа: абсолютный адрес, который сервер документов может использовать для загрузки исходного файла из хранилища PHP.
• URL обратного вызова: абсолютный адрес, на который сервер документов может отправить POST-запрос после редактирования, чтобы PHP мог сохранить изменения.

Например, https://docs.example.comможет обслуживать редактор, в то время как https://app.example.com/files/42/downloadи https://app.example.com/onlyoffice/callbackуказывают на PHP. Проверяется доступность браузера к документации и документации к PHP. При развертывании localhostозначает текущую машину или контейнер, поэтому обычно это неправильный межсервисный адрес.

Создайте конфигурацию документа для авторизованного файла.

Для авторизованного запроса на открытие файла загрузите метаданные файла и создайте конфигурацию редактора на бэкэнде PHP. Укажите расширение файла, заголовок, абсолютный URL-адрес для скачивания и ключ документа. Сохраняйте этот ключ неизменным для одновременно работающих редакторов одной и той же версии; изменяйте его, когда PHP заменит исходный код на новую версию.

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

Перед генерацией URL-адреса проверьте права доступа к файлам. Не раскрывайте учетные данные хранилища и не обходите авторизацию; для частных или локальных ссылок также может потребоваться токен в соответствии с правилами ONLYOFFICE.

Для получения информации о необходимых полях и пути к скрипту API см. справочник по настройке документов ONLYOFFICE и руководство по самостоятельной установке .

Загрузите редактор и подпишите его конфигурацию.

JWT означает JSON Web Token (веб-токен JSON), подписанный токен, позволяющий ONLYOFFICE проверить, не был ли изменен в процессе передачи. Проверка JWT включена по умолчанию в текущих развертываниях; подпишите конфигурацию редактора соответствующим секретным ключом токена браузера, настроенным в документации. Если в вашей настройке используется отдельный секретный ключ исходящего токена, проверяйте обратные вызовы также с помощью этого секретного ключа исходящего канала. Начиная с версии документации 7.2, установки Docker могут автоматически генерировать секрет, поэтому устанавливайте и сохраняйте стабильные секреты для производственной среды.

В официальном руководстве по подписи ONLYOFFICE представлен PHP-код с поддерживаемым firebase/php-jwtпакетом. Установите его с помощью команды `npm install` composer require firebase/php-jwt, затем подпишите всю конфигурацию в бэкэнде, прежде чем вернуть страницу:

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

Не допускайте попадания секрета в код браузера и систему контроля версий. Загрузите https://docs.example.com/web-apps/apps/api/documents/api.jsи передайте подписанный JSON в 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>

Безопасно кодируйте JSON json_encodeили получайте подписанную конфигурацию из конечной точки того же источника; не объединяйте недоверенные значения в JavaScript. В руководстве по подписи описан HMAC-SHA256. Для балансировки нагрузки в Docs 8.1 и более поздних версиях скрипт API может включать описанный shardkeyпараметр запроса; для одного сервера он не требуется.

Сохранение изменений осуществляется через PHP-функцию обратного вызова.

После редактирования Document Server отправляет POST-запрос callbackUrl. Статус 2 означает, что редактирование завершено и файл готов к сохранению; статус 6 — результат принудительного сохранения. Функция обратного вызова включает временный URL-адрес для загрузки отредактированного файла. Загрузите его и атомарно замените сохраненную версию или создайте новую версию в соответствии с политикой версий вашего приложения. Вернитесь {"error":0}только после успешной записи в хранилище.

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

В примере предполагается стандартный исходящий Authorization: BearerJWT-заголовок и соответствующий секретный ключ для исходящих сообщений. Адаптируйте его, если ваш сервер использует другой заголовок или токен тела запроса. Вспомогательная функция загрузки должна разрешать загрузку только с вашего сервера Docs, проверять ответ и безопасно заменять ожидаемый файл. Никогда не доверяйте произвольному URL-адресу или неподписанному ключу документа.

После успешного сохранения верните JSON, содержащий {"error":0}. Обратитесь к справочнику по функциям обратного вызова для получения информации о статусах и полезных нагрузках, а также к жизненному циклу сохранения для определения времени вызова функций обратного вызова.

Проверьте полный маршрут туда и обратно.

Откройте тестовый файл DOCX от имени авторизованного пользователя, внесите небольшие изменения и закройте редактор. Убедитесь, что ключ обратного вызова и статус соответствуют нужному файлу, проверьте, что ваше приложение сохранило новые байты, затем снова откройте документ. Если загрузка не удалась, проверьте маршрут скрипта API и токен конфигурации; если сохранение не удалось, проверьте доступность обратного вызова, проверку JWT, ответ JSON и журналы хранилища PHP.

ONLYOFFICE публикует пример интеграции с PHP и демонстрационное PHP-приложение, но прямо предупреждает, что в примерах интеграции отсутствуют средства защиты, необходимые для работы в производственной среде, такие как авторизация хранилища и проверка запросов на сохранение. Используйте их, чтобы понять поток API, а затем сохраните проверки доступа и безопасность обратных вызовов вашего собственного приложения.