NextPDF Gotenberg entegrasyonu

Genel bakış

Bu sayfa, köprüyü uygulamanızın geri kalanıyla nasıl bağlayacağınızı gösterir. Kurun, bağlayın, ardından dönüştürülen Taşınabilir Belge Biçimi (PDF) çıktısını bir NextPDF son işleme hattına aktarın. Köprü, bir Office belgesini PDF’ye dönüştürür; işlem hattı ise dönüştürmeden sonraki her şeyi yürütür. Bu bağlantının tasarım gerekçesi için bkz. /integrations/gotenberg/boot-and-discovery/.

Kurulum

composer require nextpdf/gotenberg

Bu paket kurulduğunda, nextpdf/core ^3.0 paketinin yanı sıra PHP Standartları Önerisi (PSR) Köprü Metni Aktarım Protokolü (HTTP) sözleşmeleri de kurulur. Bir PSR-18 istemcisini ve PSR-17 fabrikalarını ayrı paketler halinde kurun. Köprü yalnızca arayüzlere bağımlıdır; bu nedenle somut kitaplıkları kendiniz seçebilirsiniz. Gotenberg hizmetini Güvenli Köprü Metni Aktarım Protokolü (HTTPS) üzerinden çalıştırma dahil, tüm kurulum adımları için bkz. /integrations/gotenberg/install/.

Bağlantı

Köprüyü bir yapılandırma nesnesi ve PSR ortak bileşenleriyle oluşturun. Ayrıca bir yanıt fabrikası enjekte edin; bu, Alan Adı Sistemi (DNS) ve Aktarım Katmanı Güvenliği (TLS) sabitlemesi yapılan aktarımı etkinleştirir:

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

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

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

Köprü, yapılandırılan URL için HTTPS gerektirir. Herhangi bir istek göndermeden önce düz http:// bağlantısını reddeder. Gotenberg’i TLS sonlandırmasının arkasında çalıştırın, ardından köprüyü HTTPS uç noktasına yönlendirin.

Kapsayıcı bağlamaları

Ana makine kapsayıcınıza üç giriş kaydedin: yapılandırma kaynağınızdan oluşturulan GotenbergConfig, PSR-17 fabrikalarınızla birlikte PSR-18 istemciniz ve bu bağımlılıklardan oluşturulan GotenbergBridge. Bu paket kendi bağlamalarını içermez. Çerçeveye özgü kayıt işlemi, özel çerçeve entegrasyon paketlerine aittir. Bkz. /integrations/gotenberg/boot-and-discovery/.

Yapılandırma

Hizmet tanımlayıcısına ait tüm alanlar ve sınırlar GotenbergConfig içinde bulunur. Bunlar uygulama programlama arayüzü (API) URL’sini, zaman aşımını, boyut üst sınırını, taşıyıcı belirtecini ve TLS sabitlerini kapsar. İstek başına seçenekler olan landscape ve nativePageRanges ise yük türü üzerinde bulunur. /integrations/gotenberg/configuration/, her alanı türü, varsayılan değeri ve etkisiyle birlikte açıklar.

Dönüştürülen PDF’yi bir NextPDF işlem hattına bağlama

Tipik bir uçtan uca akış:

1. Office belgesini convertFile() veya convertString() ile dönüştürün.
2. Ham PDF baytlarını içeren $result->pdfData değerini alın ve bir NextPDF belgesine yükleyin.
3. Sayfa birleştirme, filigran ekleme, PDF/A dönüştürme veya dijital imzalar gibi son işlemleri uygulayın.

Adım 3, köprüye değil NextPDF’e aittir. nextpdf/premium paketi imzalama, PDF/A profilleri ve filigran ekleme olanağı sağlar. Her hatayı ayrı ayrı tanılayabilmek için dönüştürme ve son işlemeyi ayrı aşamalar olarak tutun.

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Conversion-layer failure — handle per your retry policy.
    throw $e;
}

// $result->pdfData is now an ordinary PDF byte stream ready for
// NextPDF post-processing.

Pro sürümündeki PDF Gelişmiş Elektronik İmzalar (PAdES) desteği yalnızca B-B temel düzeyiyle sınırlıdır. B-T, B-LT veya B-LTA sağlamaz. Bir belgenin bu köprü üzerinden dönüştürülmesi, herhangi bir zaman damgası veya uzun süreli doğrulama yeteneği anlamına gelmez.

Duman testi

Bağlantıyı kurduktan sonra, gerçek bir belgeyi dönüştürmeden entegrasyonu doğrulayın:

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

isAvailable(), URL’yi ağ trafiği olmadan doğrular. Ardından bir HEAD isteğini <apiUrl>/health adresine gönderir. Bundan sonra, geçerli olduğu bilinen küçük bir belgeyi dönüştürün. Bu işlem, <apiUrl>/forms/libreoffice/convert adresine giden tam çok parçalı yolu kullanır ve yanıtı doğrular.

Genel API giriş noktaları

Bu entegrasyonun kullandığı genel API yüzeyi:

• GotenbergConfig — değişmez hizmet tanımlayıcısı ve sınırları; fromArray() bunu bir yapılandırma dizisinden oluşturur.
• GotenbergBridge::convertFile(string $path) — diskteki bir dosyayı dönüştürür.
• GotenbergBridge::convertString(string $bytes, string $fileName) — bellekte tutulan baytları dönüştürür.
• GotenbergBridge::isAvailable() — özel durum oluşturmayan hazır olma yoklaması.
• GotenbergConvertResult — pdfData, sourceFormat, isValid() ve size() değerlerini taşır.
• GotenbergConvertException — dönüştürme katmanı özel durum türü.

Sözleşmenin tamamı /integrations/gotenberg/configuration/ ve /integrations/gotenberg/troubleshooting/ içinde yer alır. Aktarım seçimini ve özel durum kataloğunu kapsar.

Ayrıca bkz.

• /integrations/gotenberg/boot-and-discovery/ — bağlantının neden böyle göründüğü.
• /integrations/gotenberg/quickstart/ — yönlendirmeli ilk dönüştürme.
• /integrations/gotenberg/production-usage/ — gizli bilgiler, yeniden denemeler, zaman aşımları, gözlemlenebilirlik.
• /integrations/gotenberg/install/ — paket ve Gotenberg hizmeti kurulumu.