PHP 앱을 ONLYOFFICE Docs에 연결하고 편집 내용을 저장하세요.

사용자 정의 PHP 애플리케이션은 ONLYOFFICE Docs에서 가져올 수 있는 문서 URL을 제공하고, 브라우저에서 Docs JavaScript API를 로드하며, 편집된 파일을 저장하는 콜백 함수를 수락함으로써 ONLYOFFICE Docs와 통합됩니다. JWT 서명은 PHP 서버에서 유지하고, 문서 URL과 콜백 URL 모두 ONLYOFFICE Docs가 실행되는 네트워크에서 접근 가능하도록 설정하십시오.

통합 오류의 상당수는 브라우저, PHP 및 문서 서버에서 인식하는 주소가 혼동되어 발생합니다. 네트워크에서 사용하는 각 경로를 테스트하십시오.

PHP 애플리케이션과 문서 서버를 준비하세요.

ONLYOFFICE Docs는 문서 편집기를 제공합니다. 사용자의 애플리케이션은 문서 관리자 및 저장 서비스 역할을 계속 수행해야 합니다. 즉, 사용자를 인증하고, 사용자가 열 수 있는 파일을 결정하고, 소스 파일을 제공하고, 결과를 저장해야 합니다. 문서 서버는 별도로 설치한 후 /healthcheck애플리케이션 코드를 디버깅하기 전에 엔드포인트를 확인하십시오.

구성에서 연결 가능한 주소를 세 개 사용하십시오.

• Docs URL: 사용자의 브라우저가 편집기와 해당 JavaScript API를 로드하는 데 사용하는 주소입니다.
• 문서 URL: 문서 서버가 PHP 저장소에서 소스 파일을 다운로드하는 데 사용할 수 있는 절대 주소입니다.
• 콜백 URL: 문서 서버가 편집 후 PHP가 변경 사항을 저장할 수 있도록 POST 요청을 보낼 절대 주소입니다.

예를 들어, https://docs.example.com는 에디터를 제공하고 는 PHP를 가리킬 수 있습니다 https://app.example.com/files/42/download. https://app.example.com/onlyoffice/callback브라우저에서 문서로, 문서에서 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의 약자로, ONLYOFFICE가 전송 중에 구성이 변경되지 않았는지 확인할 수 있도록 하는 서명된 토큰입니다. 현재 배포 환경에서는 JWT 유효성 검사가 기본적으로 활성화되어 있습니다. Docs에 구성된 브라우저 토큰 시크릿과 일치하는 시크릿으로 에디터 구성에 서명하세요. 설정에서 별도의 발신 토큰 시크릿을 사용하는 경우, 해당 발신 토큰 시크릿으로 콜백 유효성 검사도 수행해야 합니다. Docs 7.2부터 Docker 설치 환경에서는 시크릿을 자동으로 생성할 수 있으므로, 프로덕션 환경에서는 안정적인 시크릿을 설정하고 보관하세요.

ONLYOFFICE 공식 서명 가이드에는 유지 관리되는 firebase/php-jwt패키지의 PHP 코드가 나와 있습니다. 해당 패키지를 설치한 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 콜백을 통해 변경 사항을 저장합니다.

편집이 완료되면 문서 서버는 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 흐름을 이해하는 데 사용한 후, 자체 애플리케이션의 액세스 검사 및 콜백 보안을 유지하십시오.