Conecte um aplicativo PHP ao ONLYOFFICE Docs e salve as edições.

Uma aplicação PHP personalizada integra-se com o ONLYOFFICE Docs, fornecendo um URL de documento que o Docs pode buscar, carregando a API JavaScript do Docs no navegador e aceitando um retorno de chamada que armazena o arquivo editado. Mantenha a assinatura JWT no servidor PHP e torne tanto o URL do documento quanto o URL de retorno de chamada acessíveis a partir da rede onde o ONLYOFFICE Docs está em execução.

Muitas falhas de integração decorrem da confusão entre os endereços vistos pelo navegador, PHP e servidor de documentos. Teste cada rota da rede que o utiliza.

Prepare o aplicativo PHP e o servidor de documentos.

O ONLYOFFICE Docs fornece o editor de documentos. Seu aplicativo continua sendo o gerenciador de documentos e o serviço de armazenamento: ele autentica os usuários, decide quais arquivos eles podem abrir, fornece o arquivo de origem e salva o resultado. Instale o Servidor de Documentos separadamente e verifique seu /healthcheckendpoint antes de depurar o código do aplicativo.

Utilize três endereços acessíveis em sua configuração:

• URL da documentação: o endereço que o navegador do usuário utiliza para carregar o editor e sua API JavaScript.
• URL do documento: um endereço absoluto que o servidor de documentos pode usar para baixar o arquivo de origem do armazenamento PHP.
• URL de retorno: um endereço absoluto para o qual o servidor de documentos pode enviar uma solicitação POST após a edição, permitindo que o PHP armazene as alterações.

Por exemplo, https://docs.example.compode servir o editor, enquanto https://app.example.com/files/42/downloade https://app.example.com/onlyoffice/callbackapontam para o PHP. Teste a conectividade entre o navegador e a documentação, e vice-versa. Em um ambiente de produção, localhostsignifica a máquina ou o contêiner atual, portanto, geralmente é o endereço incorreto entre serviços.

Crie uma configuração de documento para um arquivo autorizado.

Para uma solicitação de abertura autenticada, carregue os metadados do arquivo e construa a configuração do editor no backend PHP. Defina a extensão do arquivo, o título, a URL de download absoluta e uma chave do documento. Mantenha essa chave estável para editores simultâneos da mesma versão; altere-a quando o PHP substituir o código-fonte por uma nova versão.

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

Garanta as permissões de arquivo antes de gerar a URL. Não exponha credenciais de armazenamento nem ignore a autorização; links privados ou locais também podem exigir um token, de acordo com as regras do ONLYOFFICE.

Consulte o guia de configuração de documentos e o guia de instalação auto-hospedada do ONLYOFFICE para obter informações sobre os campos obrigatórios e o caminho do script da API.

Carregue o editor e assine sua configuração.

JWT significa JSON Web Token, um token assinado que permite ao ONLYOFFICE verificar se a configuração não foi alterada durante a transmissão. A validação de JWT está habilitada por padrão nas instalações atuais; assine a configuração do editor com o segredo browser-token correspondente configurado na documentação. Se sua configuração usa um segredo outgoing-token separado, valide também os callbacks com esse segredo outbox. A partir da documentação 7.2, as instalações do Docker podem gerar um segredo automaticamente; portanto, defina e mantenha segredos estáveis ​​para produção.

O guia oficial de assinatura do ONLYOFFICE mostra o código PHP com o firebase/php-jwtpacote mantido. Instale-o com `npm install` composer require firebase/php-jwt, depois assine a configuração completa no painel administrativo antes de exibi-la novamente na página.

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

Mantenha o segredo fora do código do navegador e do controle de versão. Carregue https://docs.example.com/web-apps/apps/api/documents/api.jse passe o JSON assinado para 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>

Codifique JSON com segurança json_encodeou busque a configuração assinada de um endpoint da mesma origem; não concatene valores não confiáveis ​​em JavaScript. O guia de assinatura documenta o HMAC-SHA256. Para Docs 8.1 e versões posteriores com balanceamento de carga, o script da API pode incluir o shardkeyparâmetro de consulta documentado; um servidor único não precisa dele.

Salvar alterações por meio de um retorno de chamada PHP

Após a edição, o Servidor de Documentos envia uma solicitação POST para callbackUrl. O status 2 significa que a edição foi concluída e o arquivo está pronto para ser salvo; o status 6 é um resultado de salvamento forçado. O retorno de chamada inclui um URL de download temporário para o arquivo editado. Baixe-o e substitua atomicamente a versão armazenada ou crie uma nova versão de acordo com a política de revisão do seu aplicativo. Retorne {"error":0}somente após a gravação no armazenamento ser concluída com sucesso.

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

O exemplo pressupõe o Authorization: Bearercabeçalho JWT de saída padrão e o segredo de saída correspondente. Adapte-o caso seu servidor utilize um cabeçalho ou token de corpo diferente. O auxiliar de download deve permitir apenas o host do seu Docs, verificar a resposta e substituir o arquivo esperado com segurança. Nunca confie em uma URL arbitrária ou em uma chave de documento não assinada.

Após o salvamento bem-sucedido, retorne um JSON contendo as informações {"error":0}. Consulte a referência de retorno de chamada para obter informações sobre os status e payloads, e o ciclo de vida de salvamento para o momento do retorno de chamada.

Verifique a viagem completa de ida e volta

Abra um arquivo DOCX de teste como usuário autorizado, faça uma pequena edição e feche o editor. Confirme se a chave de retorno de chamada e o status correspondem ao arquivo pretendido, verifique se o seu aplicativo armazenou os novos bytes e, em seguida, reabra o documento. Se o carregamento falhar, verifique a rota do script da API e o token de configuração; se o salvamento falhar, verifique a acessibilidade do retorno de chamada, a validação do JWT, a resposta JSON e os logs de armazenamento do PHP.

A ONLYOFFICE publica um exemplo de integração em PHP e um aplicativo de exemplo em PHP, mas alerta explicitamente que as integrações de exemplo não possuem proteções de produção, como autorização de armazenamento e validação de solicitações de salvamento. Use-as para entender o fluxo da API e, em seguida, mantenha as verificações de acesso e a segurança de retorno de chamada do seu próprio aplicativo.