Gotenberg geliştirici kılavuzu

Bir bakışta

Gotenberg paketi, PDF dönüştürme işlemini harici bir hizmete gönderir. Uygulama kodunda bu hizmet sınırını belirgin tutun: girdiyi doğrulayın, yükü oluşturun, isteği gönderin, sonucu ayrıştırın ve hizmet hatalarını ele alın.

Office’ten PDF’ye dönüştürme iş akışları, yükleme uç noktaları, hizmet sağlık denetimleri veya nextpdf/gotenberg çevresindeki taşıma ilkesini oluştururken bu kılavuzu kullanın.

Mimari sınır

Katman	Sahibi	Sorumluluk	Buraya koymayın
Yükleme veya belge kaynağı	Uygulama	İstek sahibini yetkilendirin, kaynağı doğrulayın ve dönüştürme ilkesini seçin.	Hizmet uç noktası veya taşıma sabitleme kararları.
Biçim algılama	`nextpdf/gotenberg`	Güvenli uzantıları `OfficeFormat` ile eşleyin.	Uygulama doğrulaması yapılmadan bildirilen ortam türlerine güvenmek.
Köprü	`nextpdf/gotenberg`	Çok parçalı isteği oluşturun, Gotenberg’i çağırın ve PDF yanıtını ayrıştırın.	Etki alanı sorguları veya depolama ilkesi.
Gotenberg hizmeti	dağıtım	Office belgesini PDF’ye dönüştürün.	PHP uygulaması yetkilendirmesi.
Çekirdek motor	`nextpdf/nextpdf`	Gerektiğinde dönüştürülen PDF verilerini içe aktarın veya birleştirin.	Ofis dönüştürmesi.

Çalışma zamanı yaşam döngüsü

Aşama	Davranış	Geliştirici eylemi
Yapılandırma oluşturma	API uç noktası, zaman aşımı, en büyük boyut, API anahtarı ve sabitler yapılandırmadan yüklenir.	Hizmet uç noktasını ve belirteci kaynak kodun dışında tutun.
Girdi doğrulama	Dosya yolu, dosya boyutu, dosya adı, uzantı ve URL güvenliği denetlenir.	Desteklenmeyen girdiyi göndermeden önce reddedin.
Yük oluşturma	`GotenbergConvertPayload` çok parçalı form verileri oluşturur.	Özgün dosya adını yalnızca güvenli olduğunda koruyun.
Hizmet isteği	Köprü, isteği `/forms/libreoffice/convert` adresine gönderir.	Zaman aşımını ve taşıma ilkesini yapılandırın.
Sonuç ayrıştırma	`GotenbergResponseParser::parse()` PDF baytlarını ve meta verileri döndürür.	PDF olmayan yanıtları ve hata yanıtlarını dönüştürme hataları olarak ele alın.

Önerilen uygulama yapısı

Yol	Amaç
`app/Pdf/Conversion/*`	Şunun çevresindeki uygulama sarmalayıcısı: `GotenbergBridge`.
`app/Pdf/Uploads/*`	Yükleme doğrulaması, depolama ve dosya adı ilkesi.
`app/Pdf/ConversionPolicy/*`	Boyut, biçim ve hizmet seçim ilkesi.
`tests/Pdf/Conversion/*`	Biçim, dosya, hizmet ve taşıma testleri.

Dosya doğrulamasını dönüştürme işleminden ayrı tutun. Dönüştürme hizmetiniz zaten yetkilendirilmiş girdiler almalı, ancak yine de derinlemesine savunma için paket doğrulamasına dayanmalıdır.

<?php

use NextPDF\Gotenberg\GotenbergBridge;

final readonly class OfficeConversionService
{
    public function __construct(
        private GotenbergBridge $bridge,
    ) {}

    public function convertUploadedFile(string $safePath): string
    {
        $result = $this->bridge->convertFile($safePath);

        if (!$result->isValid()) {
            throw new RuntimeException('The conversion service did not return a valid PDF.');
        }

        return $result->pdfData;
    }
}

Dönüştürme desenleri

Desen	API	Şu durumda kullanın	Kısıt
Dosya yolunu dönüştür	`GotenbergBridge::convertFile()`	Belge zaten diskte depolanmıştır.	Yol okunabilir ve ilke tarafından onaylanmış olmalıdır.
Bellekteki baytları dönüştür	`GotenbergBridge::convertString()`	Uygulamanızda bir yüklemeden veya nesne deposundan gelen baytlar zaten vardır.	Dosya adı yine de biçim algılamayı belirler.
Yükü doğrudan oluştur	`GotenbergConvertPayload`	Testler veya özel taşıma kodu için çok parçalı baytlara ihtiyacınız vardır.	Sınır oluşturmayı kullanıcı girdisinin dışında tutun.
Yanıtı doğrudan ayrıştır	`GotenbergResponseParser::parse()`	Özel HTTP çağrıları yine de paket ayrıştırması gerektirir.	Beklenen `OfficeFormat` değerini geçirmeniz gerekir.

Sağlık ve hazır olma durumu

GotenbergBridge::isAvailable() bir hazır olma sinyalidir, çalışma zamanındaki tek korumanız değildir. Bir hizmet hazır olma denetimini geçebilir ve yine de sonraki dönüştürmede başarısız olabilir.

Denetim	Amaç	İşletim notu
Yapılandırma geçerliliği	Eksik API uç noktasını algılayın.	Bunu uygulama başlatma veya dağıtım denetimleri sırasında çalıştırın.
`/health` kullanılabilirliği	Hizmete erişilip erişilemediğini algılayın.	Bunu hazır olma panoları için kullanın.
Küçük fikstür dönüştürmesi	Bozuk LibreOffice davranışını veya hizmet gerilemesini algılayın.	Bunu her istekte değil, zamanlanmış duman testlerinde çalıştırın.
Zaman aşımı izleme	Yavaş hizmet davranışını algılayın.	Bunu biçime ve dosya boyutuna göre izleyin.

Genişletme noktaları

Genişletme noktası	Şunun için kullanın	Kısıt
PSR-18 `ClientInterface`	Özel HTTP istemci davranışı.	PSR-18 yanıt ve özel durum semantiklerine uymalıdır.
PSR-17 fabrikaları	İstek ve akış oluşturma.	Köprü oluşturma için gereklidir.
`HtmlSecurityPolicyInterface`	HTML girdileri için ayrıştırma katmanı ilkesi.	Gotenberg güvenlik ilkesini tamamlar.
`ResponseFactoryInterface`	Sabitlenmiş cURL taşıma yanıtı oluşturma.	Yalnızca paket taşıma yolunu kullandığınızda gereklidir.
`GotenbergSecurityPolicy`	URL, dosya boyutu, dosya adı ve sabit doğrulaması.	Uygulama yetkilendirmesini bu katmanın dışında tutun.

Geliştirme iş akışı

Fikstürleri anlaşılır tutmak için testlerde convertString() ile başlayın.
Yalnızca dosya sistemi yolları denetim altına alındıktan sonra convertFile() ekleyin.
En büyük dosya boyutunu hizmet ve altyapı sınırlarının altında tutun.
Hata işlemenin yerine geçmesi için değil, hazır olma sinyalleri için isAvailable() yöntemini kullanın.
Dosya adını, biçimi, boyutu, durumu ve süreyi günlüğe kaydedin. Belge baytlarını günlüğe kaydetmeyin.
Yükleme uç noktalarını açığa çıkarmadan önce zaman aşımı ve hata modu testleri ekleyin.

Hata işleme

Hata	Nerede işlenmelidir	Önerilen yanıt
Desteklenmeyen uzantı	Biçim algılama.	Hizmete göndermeden önce reddedin.
Güvenli olmayan dosya adı	Güvenlik ilkesi.	Reddedin ve yükleme adlandırma ilkesini normalleştirin.
Aşırı büyük dosya	Yükleme ilkesi ve paket doğrulaması.	Büyük yükleri okumadan veya göndermeden önce reddedin.
Gotenberg kullanılamıyor	Köprü sınırı.	Uygun olduğunda yeniden denenebilen bir uygulama hatası döndürün.
PDF olmayan yanıt	Yanıt ayrıştırıcısı.	Bunu bir dönüştürme hatası olarak ele alın ve hizmet durumunu yakalayın.
Sabit veya URL doğrulama hatası	Taşıma ilkesi.	Hata durumunda kapalı kalacak şekilde başarısız olun ve operatörleri uyarın.

Güvenli varsayılanlar

Konu	Varsayılan	Ne zaman geçersiz kılınmalı
Zaman aşımı	`30` saniye.	Yalnızca gerçek hizmet gecikmesini ölçtükten sonra artırın.
En büyük dosya boyutu	`52,428,800` bayt.	Herkese açık veya çok kiracılı uç noktalar için azaltın.
API anahtarı	Boş.	Özel Gotenberg dağıtımları için ayarlayın.
Desteklenen biçimler	`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.	Biçimleri yalnızca `OfficeFormat` ve ayrıştırıcı bunları desteklediğinde ekleyin.
Sabit kümeleri	Boş.	Sabitleri yedek sabitler ve bir döndürme yordamıyla ekleyin.

Test denetim listesi

Biçim testleri, desteklenen ve desteklenmeyen uzantıları kapsar.
Dosya testleri eksik dosyaları, okunamayan dosyaları, aşırı büyük dosyaları ve güvenli olmayan dosya adlarını kapsar.
Hizmet testleri, 2xx olmayan yanıtları, geçersiz yanıt gövdelerini ve taşıma özel durumlarını kapsar.
Güvenlik testleri, ilke tarafından yasaklandığında özel veya geçersiz hizmet URL’lerini kapsar.
Zaman aşımı testleri, yapılandırılan zaman aşımının taşıma katmanına aktarıldığını doğrular.
Fikstür testleri, örnek belgeleri küçük ve hassas olmayan tutar.