NextPDF Gotenberg kurulumu

Bir bakışta

Köprünün kurulumu iki parçadan oluşur: Composer ile kurduğunuz PHP paketi ve onun PHP Standard Recommendation (PSR) HTTP bağımlılıkları; bir de paketin çağırdığı Gotenberg hizmeti. Köprü, işi bu hizmete göndererek dosyaları dönüştürür; bu nedenle erişilebilir bir Gotenberg örneği olmadan dönüştürme yapamaz.

Dönüştürme kodunu yazmadan önce bu iki bölümü de tamamlayın.

Gereksinimler

Gereksinim	Kısıtlama	Neden
PHP	>=8.4 <9.0	Paketin composer.json dosyasında bildirilir.
NextPDF core	^3.0	Paketin composer.json dosyasında doğrudan bağımlılık olarak bildirilir.
PSR-18 HTTP istemcisi	^1.0	Köprü istekleri, enjekte edilen bir Psr\Http\Client\ClientInterface üzerinden gönderir.
PSR-17 HTTP fabrikaları	^1.1	Köprü istekleri ve akışları, enjekte edilen PSR-17 fabrikalarıyla oluşturur.
PSR-3 günlükleyici	^3.0 (isteğe bağlı)	İstek düzeyinde hata ayıklama günlükleri için bir günlükleyici enjekte edebilirsiniz.
Gotenberg hizmeti	HTTPS üzerinden erişilebilir	Dönüştürmeyi bu paket değil, harici hizmet gerçekleştirir.

Köprü, bir PSR-18 istemcisini veya PSR-17 fabrikalarını paketle birlikte sunmaz. Uygulamanızın ihtiyaçlarına uygun olanları seçin. Örneğin, Guzzle tabanlı bir istemciyi kendi PSR-17 fabrikalarıyla eşleştirin veya Symfony HTTP istemcisini nyholm/psr7 ile kullanın. Köprü belirli bir kitaplığa değil, arabirimlere bağımlı olduğundan ilgili PSR sözleşmelerine uyan herhangi bir uygulama çalışır.

1. Adım — paketi kurma

Paketi Composer ile ekleyin:

composer require nextpdf/gotenberg

Composer, nextpdf/core ^3.0 bağımlılığını ve PSR HTTP sözleşmelerini çözer: psr/http-client, psr/http-factory ve psr/log. Ancak somut bir HTTP istemcisini kesinlikle kurmaz.

2. Adım — bir PSR-18 istemcisi ve PSR-17 fabrikaları kurma

Bir PSR-18 istemcisi ve onunla eşleşen PSR-17 fabrikaları kümesini kurun. Guzzle ile:

composer require guzzlehttp/guzzle guzzlehttp/psr7

Veya Symfony HTTP istemcisi ve Nyholm PSR-7 ile:

composer require symfony/http-client nyholm/psr7

Bu uygulamaları köprü yapıcısına aktarın. Köprü hiçbir zaman kendi başına bir HTTP istemcisi oluşturmaz. Köprüyü bağlarken kullanılacak uygulamayı siz seçersiniz. Yapıcının biçimi için /integrations/gotenberg/configuration/ sayfasına, eksiksiz bir bağlama örneği için /integrations/gotenberg/quickstart/ sayfasına bakın.

3. Adım — bir Gotenberg hizmeti ayağa kaldırma

Köprü, Gotenberg’in LibreOffice dönüştürme rotasını çağırır; bu nedenle köprünün erişebileceği bir Gotenberg örneği çalıştırın. Üst akış projesi bir konteyner görüntüsü yayımlar. Yerel geliştirme için şunu kullanın:

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

Bu, Gotenberg’i düz HTTP üzerinden 3000 bağlantı noktasında sunar. Bunu yalnızca yerel geliştirme için kullanın. Köprü, yapılandırılan API URL’si için HTTPS gerektirir ve herhangi bir istek göndermeden önce düz http:// adresini reddeder. Yerel denemelerin dışındaki tüm durumlarda Gotenberg’i Transport Layer Security (TLS) sonlandırması yapan bir ters proxy’nin veya hizmet ağının arkasına yerleştirin, ardından köprüyü HTTPS uç noktasına yönlendirin. /integrations/gotenberg/security-and-operations/ sayfası üretim dağıtım biçimini, ağa açılma durumunu ve kimlik doğrulamayı kapsar.

Burada gösterilen görüntü etiketi (gotenberg/gotenberg:8), üst akış Gotenberg ana sürüm hattına karşılık gelir. Bu projenin README dosyası ve entegrasyon temel çizgisi bu hattı temel alır. Üretimde, değişken bir ana etiketi izlemek yerine belirli bir yama etiketine sabitleyin. Ayrıca rota yollarını (/forms/libreoffice/convert, /health) dağıttığınız Gotenberg sürümüne göre doğrulayın. Köprü bu iki yolu varsayar ve hizmet hakkında başka hiçbir varsayımda bulunmaz.

4. Adım — bağlamayı doğrulama

Bu noktada paket ve bir HTTP istemcisi kurulmuş olur; Gotenberg de HTTPS üzerinden erişilebilirdir. Gerçek bir dönüştürme çalıştırmadan önce, köprünün yerleşik sağlık yoklamasıyla hizmete erişebildiğini doğrulayın:

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

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

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
);

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable — check the URL, TLS, and network path.');
}

isAvailable() önce yapılandırılan URL’yi doğrular. false değerini; boş bir URL, HTTPS olmayan bir URL veya özel adresli bir URL için ağ trafiği göndermeden döndürür. Ardından bir HEAD isteğini <apiUrl>/health adresine gönderir ve durum kodu 500 değerinin altındaysa hizmeti kullanılabilir olarak bildirir. Bir ağ hatası oluşursa, köprü bunu yakalar ve bir istisna atmak yerine hizmeti kullanılamaz olarak bildirir.

Sürüm notu

Bu belge paketi ^3.0 hattındaki haliyle açıklar. Bu hat, composer.json gereksinimiyle ve 3.x’in desteklendiği, 2.x’in desteklenmediği SECURITY.md destek matrisiyle eşleşir. Depo içindeki iskelet sayfalarda yer alan daha eski 0.x referansları, 3.0 hattından öncesine aittir. composer.json kısıtı bunların yerine geçer.

Ayrıca bakın

• /integrations/gotenberg/overview/ — köprünün ne yaptığı ve hangi biçimleri dönüştürdüğü.
• /integrations/gotenberg/configuration/ — yapıcının her bağımsız değişkeni ve yapılandırma alanı.
• /integrations/gotenberg/quickstart/ — eksiksiz ve çalıştırılabilir bir ilk dönüştürme.
• /integrations/gotenberg/security-and-operations/ — Gotenberg bağımlılığının güvenli bir şekilde nasıl işletileceği.
• /integrations/gotenberg/boot-and-discovery/ — çerçeve otomatik bağlaması.