Gotenberg ile Office belgelerini PDF'ye dönüştürün

Bir bakışta

Gotenberg köprüsü, Office belgesini PDF’ye dönüştürür. Belgeyi HTTPS üzerinden bir Gotenberg mikrohizmetine gönderir ve PDF baytlarını döndürür. Hizmeti değişmez bir GotenbergConfig ile tanımlar, bir PSR-18 istemcisini ve PSR-17 fabrikalarını GotenbergBridge içine bağlar, hizmet sağlığını denetler ve diskten ya da bellekteki baytlardan dosya dönüştürürsünüz. Bu kılavuz uzantı tabanlı biçim algılamayı, sağlık yoklamasını, tipli hata sözleşmesini ve NextPDF son işlemeye devri kapsar.

Önkoşullar şunlardır:

NextPDF core ve nextpdf/gotenberg kuruludur.
Bir Gotenberg hizmetine HTTPS üzerinden erişilebilir. Köprü, herhangi bir istek süreçten ayrılmadan önce düz bir http:// URL’sini reddeder.
Bir PSR-18 istemcisi ile PSR-17 istek ve akış fabrikaları kuruludur. DNS ve TLS sabitleme için ayrıca bir PSR-17 yanıt fabrikası sağlarsınız.
Girdi, tanınan altı Office biçiminden biridir: .docx, .xlsx, .pptx, .odt, .ods veya .odp. Köprü, başka herhangi bir uzantıyı bir ValueError ile reddeder.

Bu, uygulamaya yönelik bir kılavuzdur. Eksiksiz, çalıştırılabilir bir program için Gotenberg hızlı başlangıç sayfasını okuyun.

Kurulum

Köprüyü, bir PSR-18 istemcisini ve PSR-17 fabrikalarını kurun.

composer require nextpdf/gotenberg guzzlehttp/guzzle

HTTPS üzerinden erişilebilen bir Gotenberg hizmeti çalıştırın. Tüm taşıyıcı belirteçlerini bir gizli anahtar yöneticisinden veya enjekte edilmiş bir ortam değerinden alın. Köprü ortam değişkenlerini hiçbir zaman okumaz ve hiçbir zaman bir HTTP istemcisi oluşturmaz; ikisini de siz sağlarsınız.

Kavramsal genel bakış

GotenbergBridge::convertFile() diskteki bir yolu alır. Yol geçişini engellemek için yolu kanonikleştirir, dosya uzantısını desteklenen bir biçimle eşler, boyutu ve dosya adını denetler ve <apiUrl>/forms/libreoffice/convert adresine bir multipart isteği gönderir. convertString() zaten elinizde tuttuğunuz baytlar için aynı yolu izler; uzantının algılanabilmesi için özgün dosya adını kullanır.

Biçim algılama uzantıya dayanır. Köprü .docx, .xlsx, .pptx, .odt, .ods ve .odp uzantılarını kendi biçimleriyle eşler ve başka her şeyi herhangi bir ağ trafiğinden önce bir ValueError ile reddeder. Sonuç nesnesi, algılanan kaynak biçimini bir enum değeri olarak sunar.

Köprü, doğrulamayla çevrelenmiş tek bir eşzamanlı HTTP gidiş dönüşü yapar. Yeniden denemez, kuyruğa almaz, önbelleğe almaz veya hız sınırlaması uygulamaz; bu denetimler köprünün çevresindeki uygulamaya aittir. Her dönüştürmeyi, işlettiğiniz ancak süreç içinde denetlemediğiniz bir hizmete yapılan uzak çağrı olarak ele alın ve onun gecikme ile hata kiplerine göre tasarlayın.

Köprü hataları tipli istisnalar olarak bildirir ve hiçbir zaman kısmi veya doğrulanmamış bir sonuç döndürmez:

Bir 200 olmayan durum, Content-Type başlığında application/pdf bulunmaması veya %PDF ile başlamayan bir gövde, GotenbergConvertException tetikler. Köprü, yalnızca üç denetimin de geçmesi durumunda bir sonuç döndürür.
Ağ hatası veya zaman aşımı dahil olmak üzere bir PSR-18 istemci hatası, özgün istisna nedeni korunarak GotenbergConvertException içine sarmalanır.
Doğrulama hataları (HTTPS olmayan URL, özel veya ayrılmış adres, aşırı büyük girdi, güvenli olmayan dosya adı) herhangi bir ağ trafiğinden önce RuntimeException tetikler.
Tanınmayan bir dosya uzantısı, herhangi bir ağ trafiğinden önce ValueError tetikler.

API yüzeyi

// Configuration (final readonly):
new GotenbergConfig(
    string       $apiUrl,                   // required, must be HTTPS
    int          $timeout          = 30,    // hard transfer timeout, seconds
    int          $maxFileSize      = 52_428_800, // 50 MiB
    string       $apiKey           = '',    // #[SensitiveParameter]; Bearer when non-empty
    list<string> $pinnedPublicKeys = [],    // sha256/<base64>
    list<string> $backupPublicKeys = [],
)
GotenbergConfig::fromArray(array $config): self
GotenbergConfig::isValid(): bool

// The bridge:
new GotenbergBridge(
    GotenbergConfig             $config,
    ClientInterface             $httpClient,       // PSR-18
    RequestFactoryInterface     $requestFactory,   // PSR-17
    StreamFactoryInterface      $streamFactory,    // PSR-17
    ?LoggerInterface            $logger = null,    // PSR-3
    ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null,
    ?ResponseFactoryInterface   $responseFactory = null, // enables pinned transport
)
GotenbergBridge::isAvailable(): bool
GotenbergBridge::convertFile(string $path): GotenbergConvertResult
GotenbergBridge::convertString(string $bytes, string $originalFilename): GotenbergConvertResult

Sonuç nesnesi pdfData alanını, sourceFormat enum’unu, isValid() yöntemini (gövde boş değilse ve %PDF ile başlıyorsa true) ve size() yöntemini sunar. Alanların tam başvurusu, fromArray() anahtar eşlemesi ve taşıma seçimi kuralları için Ayrıca bakınız bölümünde bağlantısı verilen Gotenberg yapılandırma sayfasına bakın.

Kod örneği — hızlı başlangıç

Hizmeti tanımlayın, köprüyü bağlayın, kullanılabilirliğini yoklayın ve bir dosya dönüştürün.

<?php

declare(strict_types=1);

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

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

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

$bridge = new GotenbergBridge(
    config:          $config,
    httpClient:      $httpClient,      // your PSR-18 client
    requestFactory:  $requestFactory,  // your PSR-17 factory
    streamFactory:   $streamFactory,   // your PSR-17 factory
    responseFactory: $responseFactory, // enables the pinned transport
);

// Probe before converting. The probe validates the URL with no network
// traffic, then sends a HEAD to <apiUrl>/health.
if (!$bridge->isAvailable()) {
    throw new RuntimeException('Gotenberg is not reachable.');
}

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $exception) {
    // Bad config, HTTP failure, non-200, wrong Content-Type, or non-PDF body.
    throw $exception;
}

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

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

Yapılandırma sınıfı NextPDF\Gotenberg\GotenbergConfig sınıfıdır (yukarıdaki satır, kodunuzun içe aktarması gereken tam ad alanını kullanır). isAvailable(), boş, HTTPS olmayan veya özel adresli bir URL için ya da herhangi bir ağ hatası için false döndürür ve hiçbir zaman istisna fırlatmaz; 500 değerinin altında, /health uç noktasından dönen bir durum, kullanılabilir anlamına gelir.

Kod örneği — üretim

Üretim ortamındaki bir dönüştürme, her hata türünü ayrı ayrı yakalar, yalnızca koşullar uygun olduğunda yeniden dener ve eşzamanlılığı çağıran tarafta sınırlandırır. Aşağıdaki yakalama sırası kapsamlıdır.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConvertException;
use Psr\Log\LoggerInterface;
use RuntimeException;
use ValueError;

final readonly class OfficeConverter
{
    public function __construct(
        private GotenbergBridge $bridge,
        private LoggerInterface $logger,
    ) {}

    public function convert(string $path): string
    {
        try {
            $result = $this->bridge->convertFile($path);
        } catch (GotenbergConvertException $exception) {
            // Transport, non-200, wrong Content-Type, or non-PDF body.
            // Retry only on transport-level or 502/503/504 causes, with
            // bounded exponential backoff and jitter — never blind retries.
            $this->logger->error('gotenberg.convert.failed', [
                'path'      => basename($path),
                'exception' => $exception::class,
            ]);
            throw $exception;
        } catch (ValueError $exception) {
            // Extension is not one of the six recognized Office formats.
            $this->logger->warning('gotenberg.convert.unsupported_format', [
                'path' => basename($path),
            ]);
            throw $exception;
        } catch (RuntimeException $exception) {
            // Non-HTTPS URL, private address, oversized input, or unsafe name.
            $this->logger->error('gotenberg.convert.rejected', [
                'path'      => basename($path),
                'exception' => $exception::class,
            ]);
            throw $exception;
        }

        if (!$result->isValid()) {
            throw new RuntimeException('Gotenberg returned an invalid PDF body.');
        }

        return $result->pdfData;
    }
}

Yalnızca taşıma düzeyinde bir GotenbergConvertException (sarmalanmış bir PSR-18 istemci istisnası) ve geçici sunucu hataları (502, 503, 504) için yeniden deneyin. 400 sınıfı bir yanıt genellikle girdinin yanlış olduğu anlamına gelir, bu nedenle yeniden deneme de aynı şekilde başarısız olur. Toplam deneme sayısını ve geçen toplam süreyi sınırlayın. Sürmekte olan dönüştürme sayısını, Gotenberg dağıtımınızın taşıyabileceği kapasiteye göre sınırlayın. Köprünün kendisi durumsuzdur ve birçok işçiden güvenle kullanılabilir, ancak hizmetin sınırlı bir dönüştürme kapasitesi vardır.

Uç durumlar ve dikkat edilecekler

Biçim algılama uzantıya göredir. .docx uzantılı bir dosyanın .txt olarak yeniden adlandırılması bir ValueError ile reddedilir; .txt uzantılı bir dosyanın .docx olarak yeniden adlandırılması ise Gotenberg’e gönderilir ve orada başarısız olur. Yüklemeleri kabul ederken dosya adına değil, gerçek biçime güvenin.
fromArray() tasarım gereği hoşgörülüdür. Hatalı biçimlendirilmiş girdi için sessizce varsayılan değerleri kullanır. Eksik bir URL’nin dönüştürme başına bir istisna olarak değil, bir yapılandırma hatası olarak erken ortaya çıkması için kaynak diziyi önyükleme yolunuzda doğrulayın.
Boyut üst sınırı süreç içinde uygulanır. maxFileSize (varsayılan 50 MiB) istek gönderilmeden önce denetlenir, bu nedenle aşırı büyük bir dosya hiçbir zaman hizmet kapasitesi tüketmez. Üst sınırı belgelerinizin gereksinimlerine uyacak şekilde düşürün; daha küçük bir üst sınır, daha düşük maliyetli bir reddetme denetimidir.
Yoklama bedelsiz değildir. isAvailable() yöntemini her dönüştürmeden önce değil, bir hazır olma veya sağlık uç noktasından çağırın. Bunu her dönüştürmede çalıştırmak, hiçbir yarar sağlamadan hizmete yönelik istek oranınızı ikiye katlar.
Süreç içi önbelleğe alma yoktur. Aynı belge tekrar tekrar dönüştürülüyorsa, ortaya çıkan PDF’yi girdinin içerik karmasıyla anahtarlanmış olarak uygulamanızda önbelleğe alın.
renderTimeMs alanını ayarlamak size kalmıştır. Tümleştirmeniz onu ölçüp ayarlamadıkça sonucun zamanlama alanı 0.0 değerindedir. Bu sayıya ihtiyacınız varsa çağrı süresini kendiniz ölçün.

Performans

İstek süresince bir dönüştürme, Gotenberg tarafında bir bağlantıyı ve bir LibreOffice işçisini tutar; Office dönüştürmesi de zaman alır. timeout değerini, gerçek belgeleriniz için ölçülen dönüştürme gecikmesine göre ve ek pay bırakarak ayarlayın. Bunu, herhangi bir üst ağ geçidinin veya PHP max_execution_time değerinin altında tutun; böylece köprü önce zaman aşımına uğrar ve sonlandırılmış bir süreç yerine tipli bir istisna alırsınız. Eşzamanlılığı, hizmet kapasitesine göre boyutlandırılmış bir kuyruk, semafor veya işçi havuzuyla sınırlayın. Süreç içi önbellek yoktur; aynı girdiyi tekrar tekrar dönüştürüyorsanız uygulama düzeyinde önbellek ekleyin.

Güvenlik notları

Gönderimden önce HTTPS ve adres denetimi. Köprü, herhangi bir istek süreçten ayrılmadan önce HTTPS olmayan bir URL’yi ve özel veya ayrılmış adres alanına çözümlenen bir hedefi reddeder. Yeniden denenen her çağrı bu doğrulamayı yeniden çalıştırır, bu nedenle bir yeniden deneme SSRF korumasını atlayamaz.
İstek üzerine sabitlenmiş taşıma. Bir yanıt fabrikası ve sabitlemeler sağladığınızda (veya çözümlenmiş bir IP kümesi olduğunda), köprü bağlantıyı çözümlenmiş adreslere bağlar, SPKI sabitlemesini zorunlu kılar, eşi ve ana makineyi doğrular, zaman aşımını uygular ve yönlendirme izlemeyi devre dışı bırakır. Sertifika rotasyonundan önce bir yedek sabitleme yapılandırın.
Bir yüklemenin bildirilen içerik türüne güvenmeyin. Kullanıcı yüklemelerini kabul ederken gerçek dosya türünü kendiniz doğrulayın; uzantıdan biçime eşleme bir yönlendirme kararıdır, bir özgünlük denetimi değildir.
Gizli anahtarlar gizlenir ve değişmezdir. apiKey, #[SensitiveParameter] taşır ve yapılandırma final readonly niteliğindedir. Belirteci bir gizli anahtar yöneticisinden alın; onu asla depoya commit etmeyin. Günlüğe kaydedilen dönüştürme girdisi URL’yi, dosya adını, biçimi ve içerik uzunluğunu içerir — asla dosya içeriğini veya belirteci içermez.
Asla boş bir catch bloğu yazmayın. Her örnek belirli türü yakalar ve bağlamla birlikte günlüğe kaydeder.

Eksiksiz güvenlik ve dağıtım modeli için Gotenberg güvenlik ve işletim sayfasına bakın. PSR-18 taşıma sözleşmesi ve içerik türüne güvenme rehberliği, yukarı akıştaki üretim kullanımı sayfasında kendi maddelerine sabitlenmiştir.

Uygunluk

Bu kılavuz kendi başına hiçbir normatif standart iddiasında bulunmaz. Köprünün PSR-18 taşıma davranışı (bir istemci yalnızca bir yanıtı gönderemediğinde veya ayrıştıramadığında istisna fırlatır; bir 4xx/5xx normal bir dönüş değeridir), dosya yükleme doğrulama rehberliği ve TLS sabitleme modeli, yukarı akıştaki Gotenberg üretim kullanımı ve yapılandırma sayfalarında PSR-18, OWASP ve RFC 7469 standartlarına sabitlenmiştir. Bu Cookbook sayfası kullanımı yeniden ifade eder ve bu alıntıları o sayfalara bırakır. Köprü PDF baytları üretir ve durur. İmzalama, PDF/A profilleri ve filigran ekleme, NextPDF son işleme konularıdır ve ticari sürüm yeteneğidir; bu köprünün bir parçası değildir.

Ayrıca bakınız

Bir denetleyiciden oluşturulmuş bir PDF döndürme — dönüştürülmüş bir PDF’i HTTP yanıtı olarak döndürün.
Gotenberg hızlı başlangıç — eksiksiz, çalıştırılabilir dönüştürme programı.
Gotenberg yapılandırması — her alan, fromArray() eşlemesi ve taşıma seçimi.
Gotenberg üretim kullanımı — gizli anahtarlar, zaman aşımları, yeniden denemeler, eşzamanlılık ve son işleme sınırı.