Gotenberg API referansı

Genel bakış

Gotenberg paketi tek bir hizmet köprüsü sağlar: GotenbergBridge. Bir Office belgesini (docx, xlsx, pptx, odt, ods, odp) harici bir Gotenberg hizmetine POST isteği göndererek PDF’ye (Taşınabilir Belge Biçimi) dönüştürür. Köprü, ilettiğiniz veya okuduğunuz değer nesneleriyle çalışır: GotenbergConfig (değişmez hizmet tanımlayıcısı ve sınırlar), OfficeFormat (desteklenen biçim enum’u), GotenbergConvertPayload (çok parçalı istek gövdesi) ve GotenbergConvertResult (ayrıştırılmış PDF yanıtı). İkinci katman olarak GotenbergSecurityPolicy, GotenbergResponseParser ve PinnedCurlTransport, köprünün dahili olarak yürüttüğü doğrulama, ayrıştırma ve sabitlenmiş aktarım mekanizmasını sağlar. Bu katmanı yalnızca özel bir aktarım veya test kodu yazdığınızda kullanın.

Buradan başlayın: HTTPS (Köprü Metni Aktarım Protokolü Güvenli) hizmet URL’nizi kullanarak bir GotenbergConfig oluşturun, ardından bunu PSR-18 istemciniz ve PSR-17 fabrikalarınızla birlikte bir GotenbergBridge nesnesine iletin. convertFile() ya da convertString() çağırın, ardından pdfData alanını, dönen GotenbergConvertResult değerinden okuyun.

Sık yapılan işler

Bu pakette en sık yapacağınız işler için bu doğrulanmış, çalıştırılabilir kod parçacıklarını kullanın.

Diskteki bir dosyayı PDF’ye dönüştürme

Köprüye bir yol verin. Biçimi uzantıdan algılar.

<?php

declare(strict_types=1);

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: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    responseFactory: $psrResponseFactory,
);

$result = $bridge->convertFile('/path/to/report.docx');

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

Ne yapar: URL’yi, yolu, boyutu ve dosya adını doğrular; tek bir çok parçalı istek gönderir; döndürülen PDF baytlarını diske yazar.

Bellekteki baytları PDF’ye dönüştürme

Baytlar zaten belleğinizdeyse convertString() kullanın. Biçim algılaması dosya adına dayanır.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

/** @var GotenbergBridge $bridge */
$result = $bridge->convertString($xlsxBytes, 'spreadsheet.xlsx');

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

Ne yapar: dosya adından xlsx biçimini algılar, baytları dönüştürür ve sonucu kullanmadan önce %PDF imzasıyla başladığını doğrular.

Dönüştürmeden önce hizmetin hazır olup olmadığını yoklama

Dönüştürme işini isAvailable() ile koşula bağlayın. URL’yi ağ trafiği olmadan doğrular, ardından bir HEAD isteğini /health adresine gönderir.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

Ne yapar: boş, HTTPS olmayan veya özel adresli URL’lerde ve herhangi bir ağ hatasında false döndürür (asla istisna fırlatmaz); böylece dönüştürmeyi başlatmadan önce hızlıca başarısız yanıt verebilirsiniz.

Köprü

Bu tablo köprü API yüzeyini kapsar. GotenbergBridge nesnesini oluştururken ya da dönüştürme ve hazırlık yöntemlerini çağırırken kullanın.

Sembol	Parametreler	Varsayılan davranış	Döndürür	İstisna veya başarısızlık durumu	Notlar
`new GotenbergBridge(GotenbergConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	Yapılandırma, PSR-18 istemcisi, PSR-17 fabrikaları, isteğe bağlı günlükleyici, isteğe bağlı HTML ilkesi, isteğe bağlı yanıt fabrikası.	Bir ilke sağlamazsanız `DefaultHtmlSecurityPolicy` kullanır.	`GotenbergBridge`	Konteyner bağlama hataları.	Sabitleme gerektiğinde, yanıt fabrikası sabitlenmiş cURL aktarımını etkinleştirir.
`GotenbergBridge::convertFile(string $filePath)`	Bir Office belgesinin dosya sistemi yolu.	Biçim algılaması için dosya uzantısını kullanır.	`GotenbergConvertResult`	`GotenbergConvertException`, `RuntimeException`, `ValueError`, desteklenmeyen biçim için.	Gerçek yolu çözümler; okunabilirliği, boyutu ve dosya adını denetler.
`GotenbergBridge::convertString(string $content, string $fileName)`	Ham baytlar ve özgün dosya adı.	Biçim algılaması için dosya adı uzantısını kullanır.	`GotenbergConvertResult`	Tıpkı `convertFile` gibi.	Uygulamanızda zaten dosya baytları varsa kullanın.
`GotenbergBridge::isAvailable()`	Yok.	Yapılandırma geçerli olduğunda `/health` adresine HEAD gönderir.	`bool`	Hatalarda `false` döndürür.	Yalnızca hazır olma sinyali.
`GotenbergBridge::getHtmlSecurityPolicy()`	Yok.	Yapılandırılmış ayrıştırma katmanı ilkesini döndürür.	`HtmlSecurityPolicyInterface`	Beklenmez.	Aktarım düzeyindeki güvenlik ilkesini tamamlar.

Yapılandırma ve yükler

Bu tablo, doğrudan oluşturduğunuz değer nesnelerini kapsar: GotenbergConfig hizmet tanımlayıcısı ile GotenbergConvertPayload/GotenbergConvertResult istek ve yanıt taşıyıcıları. İki dönüştürme giriş noktasının sağladığından daha ayrıntılı denetim gerektiğinde bunları kullanın.

Sembol	Parametreler	Varsayılan davranış	Döndürür	İstisna veya başarısızlık durumu	Notlar
`new GotenbergConfig(string $apiUrl = '', int $timeout = 30, int $maxFileSize = 52428800, string $apiKey = '', array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	API URL’si, zaman aşımı, en büyük dosya boyutu, taşıyıcı belirteç, sabitleme kümeleri.	Boş URL geçersizdir; varsayılan en büyük boyut 50 MiB’dir.	`GotenbergConfig`	Beklenmez.	API anahtarını gizli tutun.
`GotenbergConfig::fromArray(array $config)`	`api_url`, `timeout`, `max_file_size`, `api_key`, sabitleme dizileri.	Eksik isteğe bağlı değerler yapıcı varsayılanlarını kullanır.	`GotenbergConfig`	Beklenmez.	Dize listeleri dize olmayan değerleri yok sayar.
`GotenbergConfig::isValid()`	Yok.	API URL’si boş olmadığında geçerlidir.	`bool`	Beklenmez.	URL güvenliği, herhangi bir ağ işleminden önce doğrulanır.
`GotenbergConfig::allPublicKeyPins()`	Yok.	Birincil ve yedek sabitlemeleri birleştirir.	`list<string>`	Beklenmez.	Boş bir liste sabitlemeyi devre dışı bırakır.
`new GotenbergConvertPayload(string $fileName, string $fileContent, OfficeFormat $format, bool $landscape = false, string $nativePageRanges = '')`	Dosya adı, baytlar, biçim, yön bayrağı, sayfa aralıkları.	Dikey yön; tüm sayfalar.	`GotenbergConvertPayload`	Beklenmez.	Yük, çok parçalı form verisine dönüştürülür.
`GotenbergConvertPayload::toMultipartBody(string $boundary)`	Çok parçalı sınır.	Sayfa aralığı alanını yalnızca boş olmadığında ekler.	`string`	Beklenmez.	Sınırı köprü oluşturur.
`GotenbergConvertPayload::contentType(string $boundary)`	Çok parçalı sınır.	İçerik türü için `multipart/form-data` kullanır.	`string`	Beklenmez.	İsteğin `Content-Type` başlığı olarak ekleyin.
`new GotenbergConvertResult(string $pdfData, OfficeFormat $sourceFormat, float $renderTimeMs = 0.0)`	Dönüştürülmüş PDF baytları, kaynak biçim, isteğe bağlı işleme süresi.	İşleme süresi ölçülmediğinde `0.0` olur.	`GotenbergConvertResult`	Beklenmez.	Şu çağrı tarafından döndürülür: `GotenbergResponseParser::parse()`.
`GotenbergConvertResult::isValid()`	Yok.	Dönüştürülmüş PDF baytları boş olmadığında ve PDF verisine benzediğinde geçerlidir.	`bool`	Beklenmez.	Sonucu kalıcı hale getirmeden ya da akış olarak iletmeden önce denetleyin.
`GotenbergConvertResult::size()`	Yok.	Dönüştürülmüş PDF baytlarını sayar.	`int`	Beklenmez.	Kotalar, telemetri ve yanıt sınırları için kullanın.

Office biçimleri

Bu tablo OfficeFormat enum’unu kapsar. Bir uzantıyı bir biçime eşlemek, yükleme MIME türünü okumak ya da desteklenen altı biçimi denetlemek için kullanın.

Sembol	Parametreler	Varsayılan davranış	Döndürür	İstisna veya başarısızlık durumu	Notlar
`OfficeFormat::fromExtension(string $ext)`	Başında nokta olan ya da olmayan dosya uzantısı.	Büyük/küçük harfe duyarsız eşleşir.	`OfficeFormat`	`ValueError` (desteklenmeyen uzantı için).	Desteklenen değerler: `docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.
`OfficeFormat::mimeType()`	Yok.	Enum durumunu yükleme MIME türüne eşler.	`string`	Beklenmez.	Çok parçalı dosya bölümünde kullanılır.
`OfficeFormat::extension()`	Yok.	Desteklenen değeri döndürür.	`string`	Beklenmez.	Tanılamalarda ve dosya adlarında kullanışlıdır.

Güvenlik, ayrıştırma ve aktarım

Bu tablo, köprünün sizin adınıza çalıştırdığı dahili mekanizmayı kapsar. Bunu yalnızca özel aktarım yazdığınızda, paketin ayrıştırmasına hâlâ ihtiyaç duyan özel bir HTTP (Köprü Metni Aktarım Protokolü) çağrısı yaptığınızda ya da düşük düzeyli güvenlik ve sabitleme davranışını incelediğinizde kullanın.

Sembol	Parametreler	Varsayılan davranış	Döndürür	İstisna veya başarısızlık durumu	Notlar
`GotenbergSecurityPolicy::validateApiUrl(string $url)`	API temel URL’si.	Herhangi bir ağ işleminden önce hedefi ayrıştırır ve doğrular.	`array`	`RuntimeException` güvensiz veya geçersiz URL’ler için.	Sunucu taraflı istek sahteciliği (SSRF) türündeki uç nokta hatalarını dönüştürme kodunun dışında tutar.
`GotenbergSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	Ana bilgisayar ve sabitlenmiş İnternet Protokolü (IP) listesi.	Etki Alanı Adı Sistemi (DNS) sabitleme beklentilerini doğrular.	`void`	`RuntimeException` (sabitlemeler güncelliğini yitirdiğinde veya geçersiz olduğunda).	Sabitlenmiş dağıtımlarda ve işletimsel tanılamalarda kullanın.
`GotenbergSecurityPolicy::validateFileSize(int $size, int $maxSize)`	Gerçek boyut ve yapılandırılmış en büyük değer.	Yapılandırılmış sınırdaki veya altındaki dosyaları kabul eder.	`void`	`RuntimeException` (dosya çok büyük olduğunda).	İstek oluşturulmadan önce uygulayın.
`GotenbergSecurityPolicy::validateFileName(string $name)`	Özgün dosya adı.	Güvensiz veya desteklenmeyen dosya adı biçimlerini reddeder.	`void`	`RuntimeException` geçersiz adlar için.	Hatalı biçimlendirilmiş çok parçalı dosya adlarını önler.
`GotenbergResponseParser::parse(ResponseInterface $response, OfficeFormat $format)`	PSR-7 yanıtı ve beklenen Office biçimi.	Başarılı bir yanıttan dönüştürülmüş PDF baytlarını çıkarır.	`GotenbergConvertResult`	`GotenbergConvertException` (başarısız yanıtlar veya geçersiz PDF çıktısı için).	Dosya ve dize dönüştürmeleri için merkezi ayrıştırıcıdır.
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	PSR-17 fabrikaları, sabitlenmiş IP’ler, sabitlenmiş ortak anahtarlar, zaman aşımı.	Sabitleme yoktur; zaman aşımı 30 saniyedir.	`PinnedCurlTransport`	Beklenmez.	Yalnızca cURL düzeyinde sabitleme gerektiğinde kullanın.
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	PSR-7 isteği.	Yapılandırılmış zaman aşımı ve sabitleme denetimleriyle cURL üzerinden gönderir.	`ResponseInterface`	`GotenbergConvertException` (cURL/aktarım hatasında).	Sabitleme başka bir HTTP istemcisine devredilemediğinde kullanın.
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	İstek, ana bilgisayar ve bağlantı noktası.	cURL seçenek dizisini oluşturur; bu diziyi `sendRequest()` kullanır.	`array`	Geçersiz istek veya sabitleme yapılandırması hatalarında.	Düşük düzeyli tanılama ve test kancasıdır.

Geliştirme notları

Gotenberg’i harici bir hizmet sınırı olarak değerlendirin. Zaman aşımını, boyutu, URL’yi ve sabitleme ilkesini bilinçli biçimde ayarlayın.
convertFile(), istek oluşturulmadan önce dosyanın tamamını belleğe okur.
Dosya içeriği yerine dosya adı ve içerik uzunluğu gibi meta verileri günlüğe kaydedin.