Преобразование сложных Word‑документов в готовый к использованию в вебе HTML является частой потребностью современных PHP приложений. GroupDocs.Conversion Cloud SDK for PHP предоставляет мощный API, который выполняет большую часть работы в облаке. В этом руководстве мы демонстрируем преобразование DOCX в HTML в PHP с использованием SDK. Вы узнаете, как настроить библиотеку, запустить полный пример кода и выполнить то же преобразование с помощью вызовов cURL.

Как конвертировать DOCX в HTML в PHP - пошагово

  1. Установите SDK через Composer: Добавьте библиотеку в ваш проект с помощью официальной команды Composer.
composer require groupdocs-conversion-cloud
  1. Инициализация конфигурации: Создайте объект Configuration и задайте ваш App SID и App Key.
$config = new GroupDocs\Conversion\Cloud\Configuration();
$config->setAppSid('YOUR_APP_SID');
$config->setAppKey('YOUR_APP_KEY');
  1. Настройте параметры конвертации HTML: Отрегулируйте настройки, такие как извлечение изображений и обработка номеров страниц.
$htmlOptions = new GroupDocs\Conversion\Cloud\Model\HtmlConvertOptions();
$htmlOptions->setExtractImages(true);
$htmlOptions->setPreserveOriginalPageNumbers(false);
$htmlOptions->setZipOutput(false);
$htmlOptions->setShowHiddenText(false);
$htmlOptions->setRenderToSinglePage(false);
  1. Создать параметры конвертации: Определите исходный файл, целевой формат и прикрепите параметры HTML.
$convertSettings = new GroupDocs\Conversion\Cloud\Model\ConvertSettings();
$convertSettings->setFilePath('sample.docx');
$convertSettings->setOutputPath('output.html');
$convertSettings->setFormat('html');
$convertSettings->setOptions($htmlOptions);
  1. Выполнить преобразование: Вызовите метод convertDocument и обработайте результат.
$convertApi = new GroupDocs\Conversion\Cloud\Api\ConvertApi($config);
try {
    $result = $convertApi->convertDocument($convertSettings);
    echo "Conversion succeeded. HTML file saved to: " . $result->getPath() . PHP_EOL;
} catch (Exception $e) {
    echo "Conversion failed: " . $e->getMessage() . PHP_EOL;
}

Для получения более подробной информации о каждом классе и методе, обратитесь к справке API.

Полный пример кода: Генерация HTML из DOCX в PHP

Следующий пример демонстрирует полное сквозное преобразование с использованием SDK.

<?php
require __DIR__ . '/vendor/autoload.php';

use GroupDocs\Conversion\Cloud\Configuration;
use GroupDocs\Conversion\Cloud\Api\ConvertApi;
use GroupDocs\Conversion\Cloud\Model\ConvertSettings;
use GroupDocs\Conversion\Cloud\Model\HtmlConvertOptions;

$config = new Configuration();
$config->setAppSid('YOUR_APP_SID');
$config->setAppKey('YOUR_APP_KEY');

$convertApi = new ConvertApi($config);

$inputFilePath  = 'sample.docx';
$outputFilePath = 'output.html';

$htmlOptions = new HtmlConvertOptions();
$htmlOptions->setExtractImages(true);               // extract images to separate files
$htmlOptions->setPreserveOriginalPageNumbers(false);
$htmlOptions->setZipOutput(false);                  // generate plain HTML, not a zip archive
$htmlOptions->setShowHiddenText(false);
$htmlOptions->setRenderToSinglePage(false);

$convertSettings = new ConvertSettings();
$convertSettings->setFilePath($inputFilePath);
$convertSettings->setOutputPath($outputFilePath);
$convertSettings->setFormat('html');
$convertSettings->setOptions($htmlOptions);

try {
    $result = $convertApi->convertDocument($convertSettings);
    echo "Conversion succeeded. HTML file saved to: " . $result->getPath() . PHP_EOL;
} catch (Exception $e) {
    echo "Conversion failed: " . $e->getMessage() . PHP_EOL;
}

Примечание: Этот пример кода демонстрирует базовую функциональность. Прежде чем использовать его в вашем проекте, убедитесь, что обновили пути к файлам (sample.docx, output.html) в соответствии с фактическим расположением, проверьте, что все необходимые зависимости правильно установлены, и тщательно протестируйте в вашей среде разработки. Если возникнут проблемы, обратитесь к официальной документации или свяжитесь с службой поддержки для получения помощи.

Преобразование файлов DOCX в HTML с помощью cURL и REST API

SDK также предлагает REST‑endpoint, который можно вызвать с помощью cURL. Ниже приведён типичный рабочий процесс.

  1. Получить токен доступа
    Замените YOUR_CLIENT_ID и YOUR_CLIENT_SECRET вашими учетными данными.

    curl -X POST "https://api.groupdocs.cloud/v2.0/oauth2/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'

  2. Загрузить файл DOCX
    Используйте токен из предыдущего шага.

    curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/storage/file/sample.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "file=@sample.docx"

  3. Start the Conversion
    Request conversion to HTML.

    curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "filePath": "sample.docx",
           "outputPath": "output.html",
           "format": "html",
           "options": {
               "extractImages": true,
               "zipOutput": false
           }
         }'

  4. Скачать полученный HTML

    curl -X GET "https://api.groupdocs.cloud/v2.0/conversion/storage/file/output.html" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o output.html

Для полного списка параметров см. официальную документацию API.

Установка и настройка GroupDocs.Conversion Cloud SDK for PHP

composer require groupdocs-conversion-cloud

Скачайте последнюю версию пакета со страницы релизов. SDK требует PHP 7.4 или новее и активный аккаунт GroupDocs Cloud с действительными учетными данными.

require __DIR__ . '/vendor/autoload.php';

use GroupDocs\Conversion\Cloud\Configuration;

$config = new Configuration();
$config->setAppSid('YOUR_APP_SID');   // obtain from your GroupDocs Cloud dashboard
$config->setAppKey('YOUR_APP_KEY');

GroupDocs.Conversion Cloud SDK for PHP Возможности преобразования DOCX в HTML

  • Извлечение изображений - extractImages позволяет извлекать встроенные картинки в отдельные файлы, сохраняя точность макета.
  • Управление номерами страниц - preserveOriginalPageNumbers можно отключить, чтобы получить непрерывный поток HTML.
  • Простой вывод HTML - Установка zipOutput в false генерирует один HTML‑файл вместо архива ZIP , упрощая последующую обработку.
  • Обработка скрытого текста - showHiddenText определяет, будет ли скрытый контент отображаться в итоговом HTML.
  • Отображение в один‑страничный режим - renderToSinglePage может объединять все страницы в один HTML‑документ для более простого встраивания.

Все функции описаны в документации.

Заключение

Преобразование DOCX в HTML в PHP становится простым с помощью GroupDocs.Conversion Cloud SDK for PHP. Библиотека обрабатывает сложное форматирование, извлечение изображений и управление страницами без необходимости установки Microsoft Office на сервере. После выполнения описанных выше шагов вы можете интегрировать конвертацию DOCX в HTML в любой PHP‑ориентированный процесс, независимо от того, предпочитаете ли вы вызовы нативного SDK или RESTful запросы cURL. Не забудьте получить соответствующую лицензию для использования в продакшн; детали ценообразования доступны на странице временной лицензии. Начните конвертировать уже сегодня и предоставьте пользователям богатый, готовый к веб‑использованию контент.

Часто задаваемые вопросы

  • Как реализовать преобразование DOCX в HTML в PHP без установки дополнительного программного обеспечения?
    Облачный SDK выполняет всю обработку на серверах GroupDocs, поэтому вам нужна только PHP‑библиотека и ваши учетные данные.

  • Могу ли я конвертировать несколько файлов DOCX в одном запросе?
    API поддерживает пакетное преобразование, перебирая файлы в вашем коде; каждый вызов возвращает свой собственный HTML‑результат.

  • Что происходит с изображениями внутри файла DOCX?
    При включённом extractImages изображения сохраняются как отдельные файлы и включаются в сгенерированный HTML, что позволяет обслуживать их напрямую.

  • Есть ли способ настроить генерируемый HTML‑макет?
    Вы можете пост‑обрабатывать вывод HTML или изменить параметры конвертации, такие как renderToSinglePage, чтобы влиять на структуру.

Читать дальше