NextPDF Gotenberg hızlı başlangıcı

Bir bakışta

Bu adım adım kılavuz, bir .docx dosyasını Portable Document Format (PDF) biçimine nasıl dönüştüreceğinizi gösterir. Tamamladığınızda elinizde üç şey olur: çalışan bir köprü örneği, doğrulanmış bir hizmet bağlantısı ve diskte bir PDF. Programın tamamı, depoda examples/convert-office-to-pdf.php konumunda yer alır. Aşağıdaki kod parçacıkları bu programdan alınmıştır.

Bu öğretici, çalışan en basit akışla başlar. Gizli bilgilerin kaynağını belirleme, yeniden denemeler, zaman aşımları ve gözlemlenebilirlik gibi üretim konuları /integrations/gotenberg/production-usage/ sayfasında ele alınır.

Başlamadan önce

Devam etmeden önce şu üç noktayı doğrulayın:

1. Daha önce composer require nextpdf/gotenberg komutunu çalıştırmış ve bir PHP Standards Recommendation (PSR)-18 istemcisi ile PSR-17 fabrikalarını kurmuş olmalısınız. Bkz. /integrations/gotenberg/install/.
2. Bir Gotenberg hizmetine Hypertext Transfer Protocol Secure (HTTPS) üzerinden erişilebilmelidir. Köprü, herhangi bir istek süreç dışına çıkmadan önce düz http:// adresini reddeder.
3. Şu biçimlerden birinde bir örnek dosyanız olmalıdır: .docx, .xlsx, .pptx, .odt, .ods veya .odp. Diğer uzantılar ValueError ile sonuçlanır.

Adım 1 — hizmeti tanımlayın

GotenbergConfig değiştirilemez bir değer nesnesidir. En azından Gotenberg hizmetinizin HTTPS temel URL’sine ihtiyaç duyar:

use NextPDF\Gotenberg\GotenbergConfig;

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

cURL’e sabitlenmiş aktarım, timeout değerini saniye cinsinden aktarım zaman aşımı olarak kullanır. apiKey boş değilse köprü bunu Authorization: Bearer <token> olarak gönderir. Gotenberg dağıtımınız bir belirteç gerektirmiyorsa apiKey değerini boş bırakın.

Adım 2 — köprüyü bağlayın

Yapılandırmayı ve PSR bileşenlerini köprüye iletin. Domain Name System (DNS) ve Transport Layer Security (TLS) sabitlemesiyle cURL aktarımını etkinleştirmek için ek olarak bir responseFactory ekleyin:

use NextPDF\Gotenberg\GotenbergBridge;

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

Köprü, sizin için asla bir Hypertext Transfer Protocol (HTTP) istemcisi oluşturmaz. Kurduğunuz PSR-18 istemcisini ve PSR-17 fabrikalarını kullanın. Örnek dosya, Guzzle bağlantısını bir yorumda gösterir.

Adım 3 — kullanılabilirliği kontrol edin

Bir dosyayı dönüştürmeden önce hizmeti kontrol edin. Yoklama, ağ trafiği oluşturmadan URL’yi doğrular; ardından bir HEAD isteğini <apiUrl>/health adresine gönderir:

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

URL boşsa, HTTPS kullanmıyorsa veya özel bir adrese işaret ediyorsa ya da herhangi bir ağ hatası oluşursa isAvailable() false döndürür (asla istisna fırlatmaz). 500 değerinin altında olan ve /health adresinden gelen bir durum kodu, hizmetin kullanılabilir olduğu anlamına gelir.

Adım 4 — dönüştürün

Diskteki bir yolu kullanarak convertFile() işlevini çağırın. Köprü, dizin geçişini engellemek için yolu standart biçime getirir. Uzantıyı desteklenen biçimlerden biriyle eşleştirir, boyutu ve dosya adını denetler, ardından <apiUrl>/forms/libreoffice/convert adresine çok parçalı bir istek gönderir:

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

Halihazırda bellekte bulunan baytları dönüştürmek için convertString() işlevini kullanın. Köprünün uzantıyı algılayabilmesi için özgün dosya adını iletin:

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

Adım 5 — sonucu kullanın

Sonuç üç şey içerir: PDF baytları, kaynak biçim ve bir geçerlilik denetimi:

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(), gövde boş değilken ve %PDF ile başladığında doğrudur. size() bayt uzunluğunu döndürür. Bu noktadan itibaren PDF, son işleme için NextPDF uygulamasına iletebileceğiniz sıradan bir akıştır.

Programın tamamı

Eksiksiz ve çalıştırılabilir program, paket deposunda examples/convert-office-to-pdf.php konumunda yer alır. Bağımsız değişken ayrıştırmayı, ortam tabanlı yapılandırmayı, durum yoklamasını, kapsamlı hata işlemeyi ve yazma adımını içerir. Şununla çalıştırın:

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

Sırada ne var

• /integrations/gotenberg/configuration/ — her seçeneği ve aktarımı seçme kurallarını inceleyin.
• /integrations/gotenberg/production-usage/ — gizli bilgileri, yeniden denemeleri, zaman aşımlarını, günlük kaydını ve eşzamanlılığı ele alın.
• /integrations/gotenberg/troubleshooting/ — bu kodun fırlatabileceği her istisnayı ve ne anlama geldiğini öğrenin.
• /integrations/gotenberg/integration/ — hizmet aracılığıyla bir NextPDF işleme hattını yürütün.