Jak zintegrować dokumenty ONLYOFFICE z niestandardową aplikacją PHP

Zacznij od granicy integracji: niestandardowa aplikacja PHP nie wysyła bajtów dokumentu bezpośrednio do edytora. Twoja aplikacja uwierzytelnia użytkownika, przechowuje plik, udostępnia adres URL, który serwer ONLYOFFICE Docs może pobrać, i udostępnia punkt końcowy wywołania zwrotnego, w którym posty Docs zapisują aktualizacje. Przeglądarka ładuje skrypt API Docs i tworzy edytor w elemencie strony. Ten wzorzec działa z samodzielnie hostowanym serwerem Docs, gdy przeglądarka i oba serwery mogą dotrzeć do wymaganych adresów URL.

Istotna informacja o wersji: ONLYOFFICE ogłosił wydanie Docs 9.4 19 maja 2026 r. W ogłoszeniu czytamy, że wersja Community Edition (oprogramowanie open source) zniosła dotychczasowy limit 20 jednoczesnych połączeń, począwszy od wersji 9.4. Zmienia to jeden z aspektów wdrożenia dla użytkowników Community; nie eliminuje to potrzeby dostępności punktów końcowych pamięci masowej i wywołań zwrotnych, podpisywania JWT ani weryfikacji licencji. Sprawdź warunki wydania i licencji dla konkretnej kompilacji Docs, którą planujesz wdrożyć. Poniższa integracja jest zgodna z aktualnym udokumentowanym przepływem API Docs.

Cztery ilustracje ekranowe to przykłady koncepcyjne, a nie zrzuty ekranu produktów. Lista dokumentów i układ projektu PHP są specyficzne dla danej aplikacji, a interfejs edytora może się różnić w zależności od wersji i konfiguracji Dokumentów.

Zanim cokolwiek podłączysz

Potrzebujesz aplikacji PHP, serwera ONLYOFFICE Docs oraz magazynu dokumentów kontrolowanego przez Twoją aplikację. Docs i aplikacja PHP mogą działać na oddzielnych hostach lub kontenerach. Przeglądarka użytkownika musi połączyć się z serwerem Docs, aby pobrać zasoby edytora. Serwer Docs musi osobno połączyć się z adresem URL dokumentu i adresem URL wywołania zwrotnego Twojej aplikacji. Nazwa hosta, taka jak ta, localhostczęsto nie działa w konfiguracji kontenera, ponieważ wskazuje na kontener wysyłający żądanie, a nie na inną usługę.

Użyj protokołu HTTPS dla publicznych punktów końcowych, przechowuj swój sekret JWT poza kontrolą źródła i zdecyduj, jak uprawnienia dokumentów są mapowane na użytkowników aplikacji. W przypadku lokalnego rozwoju może być potrzebna prywatna sieć lub tunel, aby Docs mógł pobrać plik deweloperski; środowisko produkcyjne powinno korzystać ze stabilnych, uwierzytelnionych tras. Oficjalny podręcznik instalacji Dockera w ONLYOFFICE Docs wyjaśnia instalację i konfigurację JWT. Przykładowe sekrety są przykładowe — zastąp je prywatnym sekretem i zachowaj spójność z konfiguracją Docs.

Krok 1: Zdefiniuj trasy dokumentów i sieci

Zacznij od udostępnienia dokumentu pod stabilnym, bezwzględnym adresem URL, który Docs może pobrać. Nie kieruj edytora na ścieżkę sesji PHP ani na względny adres URL tylko dla przeglądarki. Zamiast tego utwórz uwierzytelnioną ścieżkę aplikacji, taką jak https://app.example.com/docs/42/download. Przed zwróceniem bajtów, ścieżka ta powinna sprawdzić dostęp zalogowanego użytkownika do dokumentu 42. Jeśli serwer Docs nie może ponownie wykorzystać sesji przeglądarki użytkownika, wyślij krótkotrwały, ograniczony adres URL pobierania lub inny mechanizm autoryzacji między serwerami.

Utwórz również trasę wywołania zwrotnego, taką jak https://app.example.com/onlyoffice/callback?document=42. Musi ona akceptować żądanie POST z serwera Docs, bezpiecznie identyfikować plik docelowy i być dostępna z sieci serwera Docs. Parametr adresu URL, który Docs odsyła, to tymczasowy link do pobrania edytowanego dokumentu; nie jest to zapisany plik w bazie danych. Wywołanie zwrotne musi pobrać te bajty i zapisać je w pamięci masowej.

ONLYOFFICE opisuje edytor i usługę przechowywania dokumentów jako oddzielne elementy: Docs zapewnia usługę edycji, a integrator zapewnia menedżera dokumentów i ich przechowywanie. Zapoznaj się z oficjalnym opisem „Jak to działa” przed wyborem punktu końcowego i projektu sieci.

Krok 2: Zbuduj konfigurację edytora w PHP

W przypadku dokumentu Word konfiguracja identyfikuje typ pliku źródłowego, unikalny klucz dokumentu, tytuł, adres URL do pobrania, tryb edytora i adres URL wywołania zwrotnego. Klucz jest ważny: pozwala Docs zidentyfikować sesję edycji i ponownie wykorzystać dokument z pamięci podręcznej. Generuj nowy klucz po edycji i zapisaniu pliku; ponownie wykorzystaj ten sam klucz dla klientów, którzy mają dołączyć do tej samej aktywnej sesji dokumentu. Klucz powinien mieścić się w udokumentowanych limitach znaków i długości.

Poniższy przykład zakłada korzystanie z Composera i biblioteki Firebase PHP-JWT. Zastąp każdy przykładowy adres URL i wyszukiwanie w pamięci własnymi usługami obsługującymi autoryzację.

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

Musi document.urlbyć czytelny dla serwera Docs, a nie tylko dla przeglądarki. Powinien document.keyśledzić zapisaną wersję: jeśli ponownie użyjesz nieaktualnego klucza po zmianach w pliku źródłowym, Docs może otworzyć zawartość z pamięci podręcznej. Token to podpisany token JSON Web Token (JWT), standardowy format potwierdzający, że konfiguracja pochodzi z serwera przechowującego współdzielony klucz tajny. Klucz tajny podpisu pozostaje na serwerze PHP; nigdy nie umieszczaj go w JavaScript ani HTML.

Nazwy kodowe docsDownloadUrl(), callbackUrl(), i editingKey()to metody aplikacji, a nie wbudowane funkcje PHP w ONLYOFFICE. Dokładna implementacja zależy od systemu pamięci masowej, frameworka webowego i modelu kontroli dostępu. ONLYOFFICE publikuje oficjalny pakiet SDK do integracji PHP oraz przykłady wielojęzyczne, ale repozytorium wyraźnie opisuje aplikacje demonstracyjne jako przykłady testowe, które wymagają zmian w środowisku produkcyjnym. Zapoznaj się z oficjalnym przewodnikiem po podpisach JWT i oficjalnymi przykładami integracji .

Krok 3: Załaduj API Dokumentów i wyrenderuj edytor

Wyświetl podpisaną konfigurację na stronie dopiero po autoryzacji użytkownika przez trasę PHP. Ukryj kod JSON dla kontekstu JavaScript i ustaw kontener edytora na tyle wysoki, aby był użyteczny. Przeglądarka pobiera dane api.jsz serwera Docs; konstruktor zastępuje element zastępczy ramką iframe edytora.

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

Powyższe tagi są wyświetlane jako przykładowe znaczniki z zaszyfrowanymi znakami, dzięki czemu można je odczytać jako kod. Na swojej prawdziwej stronie załaduj skrypt API z adresu URL serwera Dokumentów obsługującego Twój edytor. Jeśli obszar edytora jest pusty, najpierw sprawdź, czy przeglądarka może otworzyć ten adres URL, czy aplikacja i Dokumenty korzystają ze zgodnych certyfikatów HTTPS oraz czy narzędzia programistyczne przeglądarki nie wyświetlają żadnych zablokowanych żądań dotyczących mieszanej zawartości ani żądań sieciowych. Dokumentacja DocsAPI.DocEditor wyjaśnia działanie symbolu zastępczego i ramki iframe.

Krok 4: Zapisz aktualizacje za pomocą wywołania zwrotnego

Po zakończeniu edycji Docs wysyła żądanie POST do editorConfig.callbackUrl. statusWartość ta określa, co powinien zrobić program obsługi. Status 2 oznacza, że ​​dokument jest gotowy do zapisania po zakończeniu edycji. Status 6 oznacza, że ​​bieżący stan został zapisany poprzez operację wymuszonego zapisu, a sesja edycji może być kontynuowana. Pozostałe wartości wskazują stan połączenia, braku zmian lub błędu; nie traktuj każdego wywołania zwrotnego jako nowego pliku.

Obsługa wywołania zwrotnego powinna analizować treść JSON, weryfikować żądanie zgodnie z ustawieniami skrzynki nadawczej JWT włączonymi na serwerze Docs, mapować wywołanie zwrotne na dokument będący własnością bieżącej integracji oraz celowo obsługiwać stany zapisu. W przypadku statusu 2 lub 6, należy pobrać opublikowany plik z serwera Docs, sprawdzić, czy pobieranie zakończyło się powodzeniem, i atomowo zastąpić zapisany plik, aby częściowe pobranie nie uszkodziło oryginału. Po pomyślnym przetworzeniu urlnależy zwrócić odpowiedź wywołania zwrotnego oczekiwaną przez bieżące API, zazwyczaj obiekt JSON z wartością errorustawioną na .0

<?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()i replaceAtomically()są symbolami zastępczymi, a nie kompletnymi procedurami produkcyjnymi. Używaj klienta HTTP z limitami czasu, weryfikacją TLS, limitami rozmiaru odpowiedzi i kontrolowanymi miejscami docelowymi wychodzącymi; nie pobieraj dowolnego adresu URL bez zabezpieczeń. Sprawdź podpis/token wywołania zwrotnego za pomocą metody udokumentowanej dla konkretnej wersji i konfiguracji Docs, którą uruchamiasz. Oficjalny dokument referencyjny obsługi wywołania zwrotnego zawiera listę statusów i informacje o obecności adresu URL edytowanego pliku.

Przetestuj pełną ścieżkę zapisu

1. Otwórz mały plik DOCX jako użytkownik, który ma uprawnienia do jego edycji.
2. Wprowadź widoczną zmianę, poczekaj, aż edytor poinformuje o jej zapisaniu, i zamknij dokument.
3. Sprawdź logi PHP i Docs. Upewnij się, że wywołanie zwrotne dotarło i że trasa pamięci masowej pobrała zwrócony plik.
4. Otwórz plik ponownie z poziomu aplikacji i sprawdź, czy zmiana została zachowana. Przetestuj osobno zamknięcie bez zmian i drugi edytor jednocześnie.

Oficjalny przewodnik po procesie zapisywania (save-flow) wskazuje, że w większości przypadków zapisywanie kończy się około 10 sekund po zakończeniu edycji; rozmiar pliku, złożoność, czas konwersji i wydajność serwera mogą wpływać na opóźnienie. Nie zgłaszaj użytkownikowi komunikatu „zapisano” tylko dlatego, że ramka iframe edytora została zamknięta — sprawdź wywołanie zwrotne i zapisaną wersję.

Typowe błędy integracji

• Edytor otwiera się, ale nie może załadować pliku: przetestuj go document.urlw sieci serwera Docs, a nie tylko w przeglądarce na komputerze.
• Odrzucono JWT: porównaj sekret i konfigurację HS256 po obu stronach; sprawdź, czy token podpisuje dokładny obiekt konfiguracji, który jest wysyłany.
• Zmiany znikają: sprawdzenie dostępności wywołania zwrotnego, obsługa statusu, pobieranie tymczasowych adresów URL pobierania i uprawnienia do zastępowania plików.
• Pojawia się stara wersja: wydaj nowy klucz dokumentu po zapisaniu wersji i unikaj przypadkowego podawania zbuforowanych adresów URL źródłowych.
• Działa lokalnie, nie działa w środowisku produkcyjnym: sprawdza ścieżki odwrotnego serwera proxy, certyfikaty TLS, kontener DNS, reguły zapory oraz publiczną i wewnętrzną nazwę hosta używaną w każdym adresie URL.

To podstawowa ścieżka integracji ONLYOFFICE Docs z niestandardową aplikacją PHP: autoryzacja i udostępnienie pliku źródłowego, podpisanie konfiguracji edytora dla każdego dokumentu, renderowanie oficjalnego edytora API, a następnie bezpieczne przetwarzanie wywołań zwrotnych save. Szczegóły produkcyjne – uwierzytelnianie, przechowywanie, podpisywanie adresów URL, weryfikacja wywołań zwrotnych i polityka współbieżności – muszą być zgodne z Twoją aplikacją i dokładną wersją Docs, którą wdrażasz.