ONLYOFFICE Docs를 사용자 지정 PHP 애플리케이션과 통합하는 방법

통합 경계부터 살펴보겠습니다. 사용자 정의 PHP 애플리케이션은 문서 바이트를 편집기로 직접 전송하지 않습니다. 애플리케이션은 사용자를 인증하고, 파일을 저장하고, ONLYOFFICE Docs 서버에서 가져올 수 있는 URL을 제공하며, Docs 게시물이 업데이트를 저장하는 콜백 엔드포인트를 노출합니다. 브라우저는 Docs API 스크립트를 로드하고 페이지 요소에 편집기를 생성합니다. 이 패턴은 브라우저와 두 서버 모두 필요한 URL에 접근할 수 있는 경우 자체 호스팅 Docs 서버에서 작동합니다.

관련 버전 참고 사항: ONLYOFFICE는 2026년 5월 19일에 Docs 9.4를 발표했습니다. 해당 발표에 따르면 오픈 소스 커뮤니티 에디션은 9.4 버전부터 기존의 20개 동시 연결 제한을 해제했습니다. 이는 커뮤니티 에디션 사용자의 배포 시 고려 사항 중 하나를 변경합니다. 접근 가능한 스토리지 및 콜백 엔드포인트, JWT 서명, 라이선스 검토는 여전히 필요합니다. 배포하려는 Docs 빌드의 정확한 릴리스 및 라이선스 조건을 확인하십시오. 아래 통합은 현재 문서화된 Docs API 흐름을 따릅니다.

네 개의 화면 이미지는 개념적인 예시이며, 실제 제품 스크린샷이 아닙니다. 문서 목록과 PHP 프로젝트 레이아웃은 애플리케이션별로 다르며, 편집기 인터페이스는 Docs 버전 및 구성에 따라 달라질 수 있습니다.

무엇이든 연결하기 전에

PHP 애플리케이션, ONLYOFFICE Docs 서버, 그리고 애플리케이션에서 관리하는 문서 저장소가 필요합니다. Docs와 PHP 애플리케이션은 별도의 호스트 또는 컨테이너에서 실행될 수 있습니다. 사용자의 브라우저는 편집기 자산을 다운로드하기 위해 Docs 서버에 접속해야 합니다. 또한, Docs 서버는 애플리케이션의 문서 URL과 콜백 URL에 접속할 수 있어야 합니다. localhost컨테이너 환경에서 호스트 이름이 요청을 보내는 컨테이너를 가리키게 되어 다른 서비스가 아닌 호스트 이름을 사용하는 경우 오류가 발생하는 경우가 많습니다.

공개 엔드포인트에는 HTTPS를 사용하고, JWT 비밀 키는 소스 코드 관리 시스템 외부에 저장하며, 문서 권한이 애플리케이션 사용자에게 어떻게 매핑될지 결정하세요. 로컬 개발 환경에서는 Docs가 개발 파일을 가져올 수 있도록 개인 네트워크 또는 터널이 필요할 수 있습니다. 프로덕션 환경에서는 안정적이고 인증된 경로를 사용해야 합니다. ONLYOFFICE Docs Docker 설치 가이드에서 설치 및 JWT 구성에 대한 자세한 내용을 확인할 수 있습니다. 가이드에 제공된 샘플 비밀 키는 예시일 뿐이므로, 실제 사용자의 개인 비밀 키로 교체하고 Docs 구성과 일관성을 유지해야 합니다.

1단계: 문서 및 네트워크 경로 정의

먼저 Docs에서 가져올 수 있는 안정적인 절대 URL을 통해 문서를 제공하십시오. 편집기가 PHP 세션 경로 또는 브라우저 전용 상대 URL을 가리키도록 설정하지 마십시오. 대신, 인증된 애플리케이션 경로를 생성하십시오. 예를 들어 `.`과 같은 경로를 생성해야 합니다 https://app.example.com/docs/42/download. 해당 경로는 바이트를 반환하기 전에 로그인한 사용자의 문서 접근 권한을 확인해야 합니다. Docs 서버에서 사용자의 브라우저 세션을 재사용할 수 없는 경우, 수명이 짧은 범위 지정 다운로드 URL을 제공하거나 다른 서버 간 인증 메커니즘을 사용하십시오.

또한, `.`과 같은 콜백 경로를 생성해야 합니다 https://app.example.com/onlyoffice/callback?document=42. 이 경로는 Docs 서버에서 POST 요청을 수신하고, 대상 파일을 안전하게 식별하며, Docs 서버 네트워크에서 접근 가능해야 합니다. Docs에서 POST로 전송하는 URL 매개변수는 편집된 문서의 임시 다운로드 링크이며, 데이터베이스에 저장된 파일이 아닙니다. 콜백 함수는 해당 바이트를 가져와 저장소에 기록해야 합니다.

ONLYOFFICE는 편집기와 문서 저장 서비스를 별개의 구성 요소로 설명합니다. Docs는 편집 서비스를 제공하고, 통합 솔루션은 문서 관리 및 저장 기능을 제공합니다. 엔드포인트와 네트워크 설계를 선택하기 전에 공식 "작동 방식" 개요를 참조하십시오 .

2단계: PHP로 에디터 설정을 구축합니다.

Word 문서의 경우, 구성에는 소스 파일 형식, 고유 문서 키, 제목, 다운로드 가능한 URL, 편집 모드 및 콜백 URL이 포함됩니다. 문서 키는 중요합니다. 이 키를 통해 Docs는 편집 세션을 식별하고 캐시된 문서를 재사용할 수 있습니다. 파일을 편집하고 저장한 후에는 새 키를 생성하고, 동일한 활성 문서 세션에 참여할 클라이언트에는 같은 키를 재사용하십시오. 키는 문서에 명시된 문자 및 길이 제한을 준수해야 합니다.

아래 예제는 Composer와 Firebase PHP-JWT 라이브러리를 사용하는 것을 전제로 합니다. 모든 예제 URL과 스토리지 조회 부분을 사용자의 인증 지원 서비스로 대체하십시오.

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

해당 document.url키는 브라우저뿐 아니라 Docs 서버에서도 읽을 수 있어야 합니다. 또한 document.key저장된 리비전을 추적해야 합니다. 소스 파일이 변경된 후 오래된 키를 재사용하면 Docs에서 캐시된 콘텐츠를 열 수 있습니다. 토큰은 서명된 JSON Web Token(JWT) 형식이어야 하며, 이는 공유 비밀 키를 보유한 서버에서 구성이 제공되었음을 증명하는 표준 형식입니다. 서명 비밀 키는 PHP 서버에 보관해야 하며, JavaScript나 HTML에 절대 포함해서는 안 됩니다.

코드 이름 docsDownloadUrl(), callbackUrl(), 및 editingKey()는 ONLYOFFICE PHP 내장 함수가 아니라 애플리케이션 메서드입니다. 정확한 구현은 스토리지 시스템, 웹 프레임워크 및 접근 제어 모델에 따라 달라집니다. ONLYOFFICE는 공식 PHP 통합 SDK와 다국어 예제를 제공하지만, 해당 저장소의 데모 애플리케이션은 프로덕션 환경에 맞게 수정해야 하는 테스트 예제라고 명시적으로 설명하고 있습니다. 공식 JWT 서명 가이드 와 공식 통합 예제를 참조하십시오 .

3단계: Docs API를 로드하고 편집기를 렌더링합니다.

PHP 경로에서 사용자 인증이 완료된 후에만 서명된 구성을 페이지에 렌더링합니다. JavaScript 컨텍스트를 위해 JSON을 이스케이프 처리하고, 편집기 컨테이너의 높이를 충분히 확보하여 사용하기 편리하게 만듭니다. 브라우저는 api.js문서 서버에서 구성 정보를 가져오고, 생성자는 자리 표시자 요소를 편집기 iframe으로 대체합니다.

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

위의 태그는 코드로 읽을 수 있도록 이스케이프 처리된 샘플 마크업으로 표시됩니다. 실제 페이지에서는 에디터를 제공하는 Docs 서버의 URL에서 API 스크립트를 로드하세요. 에디터 영역이 비어 있는 경우, 먼저 브라우저에서 해당 URL을 열 수 있는지, 앱과 Docs에서 호환되는 HTTPS 인증서를 사용하는지, 그리고 브라우저 개발자 도구에 혼합 콘텐츠 또는 네트워크 요청 차단이 없는지 확인하세요. DocsAPI.DocEditor 설명서에서 플레이스홀더 및 iframe 동작에 대한 설명을 확인할 수 있습니다.

4단계: 콜백을 통해 업데이트를 저장합니다.

편집이 종료되면 Docs는 POST 요청을 보냅니다 editorConfig.callbackUrl. status이 요청에 대한 응답 값은 핸들러에서 수행할 작업을 결정합니다. 상태 코드 2는 편집이 종료된 후 문서를 저장할 준비가 되었음을 의미합니다. 상태 코드 6은 강제 저장 작업을 통해 현재 상태가 저장되었지만 편집 세션은 계속될 수 있음을 의미합니다. 다른 값은 연결, 변경 없음 또는 오류 상태를 나타냅니다. 모든 콜백을 새 파일로 처리하지 마십시오.

콜백 핸들러는 JSON 본문을 파싱하고, Docs 서버에서 활성화된 JWT 아웃박스 설정에 따라 요청의 유효성을 검사하고, 콜백을 현재 통합이 소유한 문서에 매핑하고, 저장 상태를 의도적으로 처리해야 합니다. 상태 코드 2 또는 6인 경우, Docs 서버에서 게시된 파일을 다운로드하고 다운로드 성공 여부를 확인한 후, 저장된 파일을 원자적으로 교체하여 부분 다운로드로 인해 원본 파일이 손상되는 것을 방지합니다. 현재 API에서 예상하는 콜백 응답(일반적으로 처리 성공 후 값이 설정된 urlJSON 객체)을 반환합니다 .error0

<?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()이러한 코드는 임시 코드일 뿐 replaceAtomically(), 완전한 프로덕션 루틴이 아닙니다. 타임아웃, TLS 검증, 응답 크기 제한 및 제어된 아웃바운드 대상을 사용하는 HTTP 클라이언트를 사용하십시오. 안전 장치 없이 임의의 URL을 가져오지 마십시오. 실행 중인 문서 버전 및 구성에 맞는 방법을 사용하여 콜백의 서명/토큰을 확인하십시오. 공식 콜백 핸들러 참조에는 상태와 편집된 파일 URL이 존재하는 시점이 나와 있습니다.

전체 저장 경로를 테스트하세요

1. 편집 권한이 있는 사용자로 작은 DOCX 파일을 엽니다.
2. 눈에 보이는 변경 사항을 적용하고, 편집기에서 저장되었다는 표시가 나타날 때까지 기다린 후 문서를 닫으세요.
3. PHP 및 Docs 로그를 검사하십시오. 콜백이 도착했고 스토리지 경로에서 반환된 파일을 다운로드했는지 확인하십시오.
4. 해당 애플리케이션에서 파일을 다시 열고 변경 사항이 유지되는지 확인하십시오. 변경 없이 파일을 닫는 경우와 두 번째 편집기를 동시에 실행하는 경우를 각각 별도로 테스트하십시오.

공식 저장 흐름 가이드에 따르면 대부분의 경우 편집이 끝난 후 약 10초 후에 저장이 완료됩니다. 파일 크기, 복잡성, 변환 시간 및 서버 성능에 따라 지연 시간이 달라질 수 있습니다. 편집기 iframe이 닫혔다고 해서 사용자에게 "저장됨"이라고 표시하지 마십시오. 콜백 함수 호출 및 저장된 수정 버전을 확인해야 합니다.

일반적인 통합 오류

• 편집기가 열리지만 파일을 로드할 수 없습니다.document.url 데스크톱 브라우저뿐만 아니라 Docs 서버 네트워크에서도 테스트해 보세요 .
• JWT가 거부되었습니다. 양쪽의 비밀 키와 HS256 구성을 비교하고, 토큰이 전송되는 정확한 구성 객체를 나타내는지 확인하십시오.
• 변경 사항이 사라집니다. 콜백 연결 가능성, 상태 처리, 임시 다운로드 URL 가져오기 및 파일 교체 권한을 확인하십시오.
• 이전 버전이 표시됩니다. 저장된 수정 후 새 문서 키를 발급하여 캐시된 소스 URL이 의도치 않게 제공되는 것을 방지하십시오.
• 로컬 환경에서는 작동하지만 프로덕션 환경에서는 작동하지 않습니다. 리버스 프록시 경로, TLS 인증서, 컨테이너 DNS, 방화벽 규칙, 그리고 각 URL에 사용된 공용 호스트 이름과 내부 호스트 이름을 점검하십시오.

ONLYOFFICE Docs를 사용자 지정 PHP 애플리케이션과 통합하는 핵심 경로는 다음과 같습니다. 소스 파일을 인증하고 제공하고, 문서별 편집기 구성에 서명하고, 공식 API 편집기를 렌더링한 다음, 저장 콜백을 안전하게 처리합니다. 프로덕션 환경의 세부 정보(인증, 저장소, URL 서명, 콜백 검증 및 동시 실행 정책)는 사용자의 애플리케이션 및 배포하는 정확한 Docs 버전과 일치해야 합니다.