Połącz aplikację PHP z dokumentami ONLYOFFICE i zapisz zmiany

Niestandardowa aplikacja PHP integruje się z ONLYOFFICE Docs, udostępniając adres URL dokumentu, który Docs może pobrać, ładując interfejs API JavaScript Docs w przeglądarce i akceptując wywołanie zwrotne, które zapisuje edytowany plik. Zachowaj podpisywanie JWT na serwerze PHP i zapewnij, aby zarówno adres URL dokumentu, jak i adres URL wywołania zwrotnego były dostępne z sieci, w której działa ONLYOFFICE Docs.

Wiele błędów integracji wynika z pomieszania adresów widzianych przez przeglądarkę, PHP i serwer dokumentów. Przetestuj każdą trasę z sieci, która z niej korzysta.

Przygotuj aplikację PHP i serwer dokumentów

ONLYOFFICE Docs udostępnia edytor dokumentów. Twoja aplikacja pozostaje menedżerem dokumentów i usługą przechowywania: uwierzytelnia użytkowników, decyduje, które pliki mogą otwierać, dostarcza plik źródłowy i zapisuje wynik. Zainstaluj Serwer Dokumentów osobno, a następnie zweryfikuj jego /healthcheckpunkt końcowy przed debugowaniem kodu aplikacji.

Użyj w swojej konfiguracji trzech dostępnych adresów:

• Adres URL dokumentów: adres, którego przeglądarka użytkownika używa do załadowania edytora i jego interfejsu API JavaScript.
• Adres URL dokumentu: adres bezwzględny, którego serwer dokumentów może użyć do pobrania pliku źródłowego z pamięci masowej PHP.
• Adres URL wywołania zwrotnego: bezwzględny adres, na który serwer dokumentów może wysłać żądanie POST po edycji, dzięki czemu PHP może zapisać zmiany.

Na przykład, https://docs.example.commoże obsługiwać edytor, wskazując jednocześnie https://app.example.com/files/42/downloadna https://app.example.com/onlyoffice/callbackPHP. Przetestuj dostępność przeglądarki do Dokumentów i Dokumentów do PHP. We wdrożeniu localhostoznacza to bieżącą maszynę lub kontener, więc zazwyczaj jest to niewłaściwy adres międzyusługowy.

Zbuduj konfigurację dokumentu dla autoryzowanego pliku

W przypadku uwierzytelnionego żądania otwarcia, wczytaj metadane pliku i skompiluj konfigurację edytora w zapleczu PHP. Ustaw rozszerzenie pliku, tytuł, bezwzględny adres URL pobierania oraz klucz dokumentu. Zachowaj ten klucz stabilny dla współbieżnych edytorów tej samej wersji; zmień go, gdy PHP zastąpi kod źródłowy nową wersją.

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

Wymuś uprawnienia do pliku przed wygenerowaniem adresu URL. Nie ujawniaj danych uwierzytelniających do pamięci masowej ani nie omijaj autoryzacji; linki prywatne lub lokalne mogą również wymagać tokena zgodnie z zasadami ONLYOFFICE.

Informacje na temat wymaganych pól i ścieżki skryptu API można znaleźć w dokumencie ONLYOFFICE dotyczącym konfiguracji dokumentów oraz w podręczniku instalacji hostowanej samodzielnie .

Załaduj edytor i podpisz jego konfigurację

JWT oznacza JSON Web Token, podpisany token, który pozwala ONLYOFFICE zweryfikować, czy konfiguracja nie została zmieniona podczas przesyłania. Walidacja JWT jest domyślnie włączona w obecnych wdrożeniach; podpisz konfigurację edytora pasującym kluczem tajnym tokena przeglądarki skonfigurowanym w Docs. Jeśli Twoja konfiguracja używa oddzielnego klucza tajnego tokena wychodzącego, waliduj wywołania zwrotne również przy użyciu tego klucza tajnego skrzynki nadawczej. Od Docs 7.2 instalacje Dockera mogą automatycznie generować klucz tajny, więc ustaw i zachowaj stabilne klucze tajne na potrzeby produkcji.

Oficjalny przewodnik po podpisach ONLYOFFICE pokazuje kod PHP z obsługiwanym firebase/php-jwtpakietem. Zainstaluj go za pomocą composer require firebase/php-jwt, a następnie podpisz całą konfigurację w zapleczu, zanim przeniesiesz ją na stronę:

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

Zachowaj tajemnicę poza kodem przeglądarki i kontrolą źródła. Załaduj https://docs.example.com/web-apps/apps/api/documents/api.jsi przekaż podpisany plik JSON do 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>

Koduj JSON bezpiecznie json_encodelub pobieraj podpisaną konfigurację z punktu końcowego o tym samym źródle; nie łącz niezaufanych wartości z JavaScript. Przewodnik po podpisach dokumentuje HMAC-SHA256. W przypadku dokumentów Docs 8.1 i nowszych z równoważeniem obciążenia skrypt API może zawierać udokumentowany shardkeyparametr zapytania; pojedynczy serwer go nie potrzebuje.

Zapisz zmiany za pomocą wywołania zwrotnego PHP

Po edycji serwer dokumentów wysyła żądanie POST do callbackUrl. Status 2 oznacza, że ​​edycja jest zakończona i plik jest gotowy do zapisania; status 6 to wynik wymuszonego zapisu. Wywołanie zwrotne zawiera tymczasowy adres URL pobierania edytowanego pliku. Pobierz go i atomowo zastąp zapisaną wersję lub utwórz nową wersję zgodnie z polityką rewizji aplikacji. Zwróć {"error":0}dopiero po pomyślnym zapisie do pamięci masowej.

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

W przykładzie przyjęto domyślny wychodzący Authorization: Bearernagłówek JWT i pasujący do niego klucz skrzynki nadawczej. Dostosuj go, jeśli Twój serwer używa innego nagłówka lub tokenu body. Pomocnik pobierania powinien zezwalać tylko na dostęp do hosta Docs, sprawdzać odpowiedź i bezpiecznie zastępować oczekiwany plik. Nigdy nie ufaj dowolnemu adresowi URL ani niepodpisanemu kluczowi dokumentu.

Po pomyślnym zapisaniu zwróć JSON zawierający {"error":0}. Zapoznaj się z dokumentacją wywołania zwrotnego, aby uzyskać informacje o statusach i ładunkach, oraz z cyklem życia zapisu , aby uzyskać informacje o czasie wywołania zwrotnego.

Sprawdź całą trasę w obie strony

Otwórz testowy plik DOCX jako autoryzowany użytkownik, wprowadź niewielką edycję i zamknij edytor. Sprawdź, czy klucz wywołania zwrotnego i status odpowiadają żądanemu plikowi, sprawdź, czy aplikacja zapisała nowe bajty, a następnie ponownie otwórz dokument. Jeśli ładowanie się nie powiedzie, sprawdź ścieżkę skryptu API i token konfiguracyjny; jeśli zapisywanie się nie powiedzie, sprawdź osiągalność wywołania zwrotnego, walidację JWT, odpowiedź JSON i logi pamięci PHP.

ONLYOFFICE publikuje przykład integracji PHP i przykładową aplikację PHP, ale wyraźnie ostrzega, że ​​przykładowe integracje nie posiadają zabezpieczeń produkcyjnych, takich jak autoryzacja pamięci masowej i walidacja żądania zapisu. Wykorzystaj je, aby zrozumieć przepływ API, a następnie zachowaj kontrolę dostępu i zabezpieczenia wywołań zwrotnych we własnej aplikacji.