NextPDF Gotenberg — szybki start

W skrócie

W tym przewodniku przekonwertujesz jeden plik .docx na dokument w formacie Portable Document Format (PDF). Po ukończeniu otrzymasz trzy rzeczy: działającą instancję mostka, zweryfikowane połączenie z usługą oraz plik PDF zapisany na dysku. Pełny program znajduje się w repozytorium pod ścieżką examples/convert-office-to-pdf.php. Poniższe fragmenty kodu pochodzą z tego programu.

Samouczek prowadzi przez najprostszą działającą ścieżkę. Zagadnienia produkcyjne, w tym obsługa sekretów, ponawianie prób, limity czasu oraz obserwowalność, omówiono w /integrations/gotenberg/production-usage/.

Zanim zaczniesz

Zanim przejdziesz dalej, upewnij się, że:

1. Polecenie composer require nextpdf/gotenberg zostało wykonane, a klient zgodny z PHP Standards Recommendation (PSR)-18 oraz fabryki PSR-17 są zainstalowane. Zobacz /integrations/gotenberg/install/.
2. Usługa Gotenberg jest dostępna przez Hypertext Transfer Protocol Secure (HTTPS). Mostek odrzuca zwykłe http://, zanim jakiekolwiek żądanie opuści proces.
3. Masz przykładowy plik w jednym z tych formatów: .docx, .xlsx, .pptx, .odt, .ods lub .odp. Przy innych rozszerzeniach operacja kończy się błędem ValueError.

Krok 1 — opisz usługę

GotenbergConfig to niezmienny obiekt wartości. W minimalnej konfiguracji wymaga bazowego adresu URL HTTPS usługi Gotenberg:

use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(
    apiUrl: 'https://gotenberg.example.com',
    timeout: 60,
    apiKey: $apiKey,
);

Transport oparty na cURL stosuje wartość timeout jako limit czasu transferu w sekundach. Jeśli apiKey nie jest pusty, mostek wysyła go jako Authorization: Bearer <token>. Pozostaw apiKey pusty, jeśli wdrożenie Gotenberg nie wymaga tokenu.

Krok 2 — połącz mostek

Przekaż mostkowi konfigurację oraz komponenty PSR. Wstrzyknij również responseFactory, aby włączyć transport cURL z przypinaniem Domain Name System (DNS) oraz Transport Layer Security (TLS):

use NextPDF\Gotenberg\GotenbergBridge;

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

Mostek nigdy nie tworzy automatycznie klienta Hypertext Transfer Protocol (HTTP). Użyj zainstalowanego klienta PSR-18 oraz fabryk PSR-17. W pliku przykładowym pokazano w komentarzu połączenie z Guzzle.

Krok 3 — sprawdź dostępność

Sprawdź usługę, zanim przekonwertujesz plik. Sonda weryfikuje adres URL bez generowania ruchu sieciowego, a następnie wysyła żądanie HEAD do <apiUrl>/health:

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable.');
}

Dla pustego adresu URL, adresu innego niż HTTPS lub adresu prywatnego, a także przy dowolnym błędzie sieci, isAvailable() zwraca false i nigdy nie zgłasza wyjątku. Status poniżej 500 zwrócony z /health oznacza, że usługa jest dostępna.

Krok 4 — konwertuj

Wywołaj convertFile(), podając ścieżkę na dysku. Mostek normalizuje ścieżkę, aby zablokować przechodzenie po katalogach. Mapuje rozszerzenie na obsługiwany format, sprawdza rozmiar i nazwę pliku, a następnie wysyła żądanie wieloczęściowe do <apiUrl>/forms/libreoffice/convert:

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Bad config, HTTP failure, non-200, wrong Content-Type, or non-PDF body.
    throw $e;
} catch (\RuntimeException $e) {
    // Non-HTTPS URL, private address, oversized input, or unsafe filename.
    throw $e;
} catch (\ValueError $e) {
    // Extension is not one of the six recognised Office formats.
    throw $e;
}

Aby przekonwertować bajty, które są już w pamięci, użyj convertString(). Przekaż oryginalną nazwę pliku, aby mostek mógł wykryć rozszerzenie:

$pdf = $bridge->convertString($docxBytes, 'report.docx');

Krok 5 — wykorzystaj wynik

Wynik zawiera trzy rzeczy: bajty pliku PDF, format źródłowy oraz sprawdzenie poprawności:

if (! $result->isValid()) {
    throw new \RuntimeException('Result is not a valid PDF.');
}

\file_put_contents('/path/to/report.pdf', $result->pdfData);

\printf(
    "Converted %s (%d bytes)\n",
    $result->sourceFormat->value,
    $result->size(),
);

isValid() ma wartość true, gdy treść nie jest pusta i zaczyna się od %PDF. size() zwraca długość w bajtach. Od tego momentu plik PDF jest zwykłym strumieniem, który można przekazać do NextPDF w celu dalszego przetwarzania.

Kompletny program

Pełny, gotowy do uruchomienia program znajduje się w pliku examples/convert-office-to-pdf.php w repozytorium pakietu. Obejmuje analizę argumentów, konfigurację sterowaną zmiennymi środowiskowymi, sondę kondycji, wyczerpującą obsługę błędów oraz zapis wyniku. Uruchom go tak:

GOTENBERG_URL=https://gotenberg.example.com \
php examples/convert-office-to-pdf.php report.docx report.pdf

Co dalej

• /integrations/gotenberg/configuration/ — przejrzyj wszystkie opcje i reguły wyboru transportu.
• /integrations/gotenberg/production-usage/ — skonfiguruj obsługę sekretów, ponawianie prób, limity czasu, rejestrowanie oraz współbieżność.
• /integrations/gotenberg/troubleshooting/ — poznaj wszystkie wyjątki, które ten kod może zgłosić, oraz ich znaczenie.
• /integrations/gotenberg/integration/ — steruj potokiem renderowania NextPDF za pośrednictwem usługi.