CodeIgniter API başvurusu

Genel bakış

CodeIgniter paketi, denetleyicilere yönelik küçük bir uygulama programlama arabirimi (API) sunar. Tek bir belge için Pdf kütüphane sarmalayıcısını (Services::pdf() ve genel pdf() yardımcısı), oluşturulan bir belgeyi DownloadResponse (PdfResponse) yanıtına dönüştüren yanıt yardımcılarını, bunların arkasındaki Services fabrikalarını (yazı tipi ve görüntü kayıtları, belge fabrikası ve isteğe bağlı imzalayıcı ile zaman damgası yetkilisi (TSA) istemcisi), NextPdf yapılandırma sınıfını ve statik oluşturucu çağrılabilirleriyle eşzamansız üretim sağlayan GeneratePdfJob işini içerir.

Ana denetleyici akışından başlayın: Services::pdf() çağrısını yapın (ya da pdf() yardımcısını kullanın), $pdf->document() üzerinden içeriği ekleyin ve $pdf->download('file.pdf') döndürün. Bu akış, yaygın durumu kapsar. Başvuru tabloları API yüzeyine göre düzenlenmiştir; yaygın görevler bölümü, önce çalıştırılabilir biçimleri gösterir.

Yaygın görevler

Bunlar en yaygın üretim akışlarıdır. Her örnek, nextpdf/codeigniter kaynağına göre doğrulanmıştır.

Bir denetleyiciden indirilebilir bir PDF dosyası döndürmek için standart işleme yolunu kullanın:

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;
use NextPDF\CodeIgniter\Config\Services;

final class InvoiceController extends BaseController
{
    public function download(int $id): DownloadResponse
    {
        $pdf = Services::pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, "Invoice #{$id}");

        return $pdf->download("invoice-{$id}.pdf");
    }
}

Yaptığı iş: yeni bir Pdf örneğini, yeni bir Document çevresinde çözer, tek bir hücre yazar ve DownloadResponse yanıtını attachment düzeni ve paket güvenlik üst bilgileriyle döndürür.

Aynı sarmalayıcıyı kullanıp inline() (download() yerine) çağırarak bir PDF’yi tarayıcıda satır içi önizleyin:

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;

final class ReportController extends BaseController
{
    public function preview(): DownloadResponse
    {
        $pdf = pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, 'Monthly Report');

        return $pdf->inline('report.pdf');
    }
}

Yaptığı iş: genel pdf() yardımcısını (Services::pdf() ile eşdeğer) kullanır ve DownloadResponse yanıtını inline düzeniyle döndürür; böylece tarayıcı PDF’yi indirmek yerine görüntüler.

Kuyrukta bir PDF’yi GeneratePdfJob ve statik bir oluşturucu kullanarak eşzamansız üretin:

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Jobs\GeneratePdfJob;

service('queue')->push('pdf', GeneratePdfJob::class, [
    'builder'    => 'App\PdfBuilders\InvoiceBuilder::build',
    'outputPath' => WRITEPATH . 'pdfs/invoice-42.pdf',
    'context'    => ['invoice_id' => 42],
]);

Yaptığı iş: üretimi kuyruğa alır. İş, oluşturucuyu (App\PdfBuilders\...::method biçiminde statik bir çağrılabilir olmalıdır) ve çıktı yolunu (WRITEPATH/pdfs/ altında çözümlenmeli ve .pdf ile bitmelidir) doğrular, yeni bir belge oluşturur ve kaydeder.

Kütüphane sarmalayıcısı

Bir Pdf sarmalayıcınız olduğunda ve yanıt ya da kaydetme yöntemlerine ihtiyaç duyduğunuzda bu tabloyu kullanın.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumda hata verir veya başarısız olur	Notlar
`NextPDF\CodeIgniter\Libraries\Pdf` / `new Pdf(Document $document)`	`document`: yeni bir çekirdek belge.	Sağlanan belgeyi tek bir yanıt veya kaydetme işlemi için sarmalar.	`Pdf`	Beklenmez.	Çıktıdan sonra sarmalayıcıyı yeniden kullanmayın.
`Pdf::document()`	yok.	Sarmalanan belgeyi döndürür.	`NextPDF\Core\Document`	Beklenmez.	Çekirdek yazım API’lerini çağırmak için bunu kullanın.
`Pdf::inline(string $filename = 'document.pdf')`	`filename`: yanıt dosya adı.	Tarayıcının satır içi düzenini kullanır.	`CodeIgniter\HTTP\DownloadResponse`	Çekirdek serileştirme hataları.	Şuna devreder: `PdfResponse::inline()`.
`Pdf::download(string $filename = 'document.pdf')`	`filename`: yanıt dosya adı.	Tarayıcının ek düzenini kullanır.	`DownloadResponse`	Çekirdek serileştirme hataları.	Şuna devreder: `PdfResponse::download()`.
`Pdf::streamInline(string $filename = 'document.pdf')`	`filename`: yanıt dosya adı.	Diğer çerçeve paketleriyle API eşitliği sağlar.	`DownloadResponse`	Çekirdek serileştirme hataları.	CodeIgniter ikili çıktıyı doğal olarak işler.
`Pdf::streamDownload(string $filename = 'document.pdf')`	`filename`: yanıt dosya adı.	Diğer çerçeve paketleriyle API eşitliği sağlar.	`DownloadResponse`	Çekirdek serileştirme hataları.	Akışsız yanıtlarla aynı boyut denetimlerini kullanın.
`Pdf::save(string $path)`	`path`: dosya sistemi hedefi.	Sarmalanan belgeyi yazar.	`void`	Dosya sistemi veya çekirdek yazma hataları.	Kaydetmeden önce depolama köklerini doğrulayın.

Servisler ve yardımcılar

Paylaşım davranışı ve dönüş türü dahil olmak üzere belirli bir servis fabrikasına veya genel yardımcı işleve ihtiyaç duyduğunuzda bu tabloyu kullanın.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumda hata verir veya başarısız olur	Notlar
`Services::fontRegistry(bool $getShared = true)`	`getShared`: CodeIgniter paylaşılan servis bayrağı.	Paylaşılan bir kayıt döndürür; yapılandırılmış yazı tipleriyle ısıtır ve ardından kilitler.	`FontRegistryInterface`	`RuntimeException` — eksik uzantılar veya güvenli olmayan yazı tipi yolu durumunda.	Akış sarmalayıcılarını ve boş baytları şurada reddeder: `fontsPath`.
`Services::imageRegistry(bool $getShared = true)`	`getShared`: paylaşılan servis bayrağı.	Paylaşılan, sınırlandırılmış bir LRU görüntü kaydı döndürür.	`ImageRegistry`	Beklenmez.	Önbellek boyutu `imageCacheMb` ile denetlenir.
`Services::documentFactory(bool $getShared = true)`	`getShared`: paylaşılan servis bayrağı.	Paylaşılan kayıtları kullanan, paylaşılan bir fabrika döndürür.	`DocumentFactoryInterface`	Kayıt kurulum hataları.	Fabrika yeniden kullanılabilir; belgeler değildir.
`Services::tsaClient(bool $getShared = true)`	`getShared`: paylaşılan servis bayrağı.	Şu boş olduğunda `null` döndürür: `tsa.url`.	`TsaClient	null`	Köprü Metni Aktarım Protokolü (HTTP) istemcisi veya TSA yapılandırması hataları.
`Services::pdfSigner(bool $getShared = false)`	`getShared`: paylaşılan servis bayrağı.	İmzalama devre dışı bırakıldığında `null` döndürür.	`SignerInterface	null`	Sertifika veya imza düzeyi hataları.
`Services::pdfDocument(bool $getShared = false)`	`getShared`: paylaşılan servis bayrağı.	Yeni bir belge oluşturur, varsayılanları uygular ve isteğe bağlı olarak PDF/A’yı veya Artisan’ı yapılandırır.	`Document`	İsteğe bağlı uzantı veya belge yapılandırması hataları.	İstek güvenliği için varsayılan `false` değerini koruyun.
`Services::pdf(bool $getShared = false)`	`getShared`: paylaşılan servis bayrağı.	Yeni bir belge çevresinde yeni bir `Pdf` sarmalayıcısı oluşturur.	`NextPDF\CodeIgniter\Libraries\Pdf`	Belge kurulum hataları.	Denetleyiciye dönük ana servis.
`Services::eInvoiceEmbedder()`	yok.	Premium Pro e-fatura gömücü sınıfı yoksa `null` döndürür.	`EmbedderInterface	null`	İsteğe bağlı paket oluşturma hataları.
`Services::eInvoiceValidator()`	yok.	Premium Enterprise doğrulayıcı sınıfı yoksa `null` döndürür.	`ValidatorInterface	null`	İsteğe bağlı paket oluşturma hataları.
`Services::eInvoiceProfile()`	yok.	Premium Pro yüklü olduğunda EN16931 profilini döndürür.	`ProfileInterface	null`	İsteğe bağlı paket hataları.
`Services::schematronRunner()`	yok.	Premium Enterprise Schematron doğrulayıcısı yoksa `null` döndürür.	`SchematronRunnerInterface	null`	İsteğe bağlı paket oluşturma hataları.
`Registrar::Autoload()`	yok.	Paket yardımcısını CodeIgniter’ın otomatik yükleme yapılandırmasına ekler.	`array`	Beklenmez.	Modül yüklendiğinde `pdf()` ve `pdf_document()` işlevlerini etkinleştirir.
`pdf()`	yok.	Şunu çağırır: `Services::pdf(false)`.	`Pdf`	Belge kurulum hataları.	Denetleyiciler için kolaylık yardımcısı.
`pdf_document()`	yok.	Şunu çağırır: `Services::pdfDocument(false)`.	`Document`	Belge kurulum hataları.	Çekirdek belge API’si tercih edildiğinde kolaylık yardımcısı.

HTTP yanıtları

Hâlihazırda oluşturulmuş bir Document olduğunda ve DownloadResponse yanıtını Pdf sarmalayıcısını kullanmak yerine kendiniz oluşturmak istediğinizde bu tabloyu kullanın.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumda hata verir veya başarısız olur	Notlar
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: oluşturulmuş belge; `filename`: yanıt dosya adı.	Belirtilen `.pdf` uzantısını ve satır içi düzeni sağlar.	`DownloadResponse`	Çekirdek serileştirme hataları.	PDF içerik türünü ve savunma amaçlı üst bilgileri ekler.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Aynısı `inline` ile; düzeni ektir.	Belirtilen `.pdf` uzantısını sağlar.	`DownloadResponse`	Aynısı `inline` ile.	Tarayıcı indirmeleri için kullanın.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Aynısı `inline` ile.	CodeIgniter 4 (CI4) üzerinde `inline` ile aynı davranışı gösterir.	`DownloadResponse`	Aynısı `inline` ile.	Çerçeveler arası API eşliği için vardır.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Aynısı `download` ile.	CI4 üzerinde `download` ile aynı davranışı gösterir.	`DownloadResponse`	Aynısı `download` ile.	Çerçeveler arası API eşliği için vardır.

Kuyruk işi

Eşzamansız üretimi bağlarken tam iş veri anahtarlarına ve oluşturucu çağrılabilir sözleşmesine ihtiyaç duyduğunuzda bu tabloyu kullanın.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumda hata verir veya başarısız olur	Notlar
`GeneratePdfJob::process()`	İş veri anahtarları: `builder`, `outputPath` ve isteğe bağlı `context`.	Atlanırsa boş bir bağlam dizisi kullanır.	`void`	`InvalidArgumentException` — güvenli olmayan oluşturucu veya çıktı yolu durumunda; çekirdek yazma hataları.	Oluşturucu `App\PdfBuilders\...\*::method` olmalıdır.
Oluşturucu çağrılabiliri	`Document $doc`, `array $context`.	İş verisi dışında varsayılan bağlam yoktur.	`Document`	Oluşturucuya özgü özel durumlar.	CI4 kuyruk yükleri serileştirilmiş veri olduğundan statik bir çağrılabilir gerektirir.

Yapılandırma

Sayfa biçimi, yollar, imzalama, TSA veya belge meta verilerine ilişkin varsayılanları NextPdf yapılandırma sınıfında değiştirdiğinizde bu tabloyu kullanın.

Özellik	Tür	Varsayılan davranış	Notlar
`pageFormat`	`string`	`A4`.	Varsayılan sayfa biçimini ayarlar.
`orientation`	`string`	`P`.	Varsayılan yönelimi ayarlar.
`unit`	`string`	`mm`.	Varsayılan birimi ayarlar.
`pdfa`	`string	null`	`null`.
`fontsPath` / `cachePath`	`string`	`WRITEPATH . 'fonts'` ve `WRITEPATH . 'cache/nextpdf'`.	Yolları uygulamanın denetimindeki depolama içinde tutun.
`signature`	`array`	Şu düzeyle devre dışı: `B-B`.	Sertifika, anahtar, parola, ek sertifikalar ve düzey.
`tsa`	`array`	Tekdüzen kaynak konumlandırıcı (URL) değeri `null` olduğunda devre dışıdır; zaman aşımı 30 saniyedir.	Kimlik bilgileri, karşılıklı aktarım katmanı güvenliği (mTLS) dosyaları, ortak anahtar sabitlemeleri ve HTTP ilkesi.
`ocspCache`	`array`	86400 saniyelik yaşam süresi (TTL) ile etkin.	Mevcut olduğunda imza doğrulama akışları tarafından kullanılır.
`preloadFonts`	`list<string>`	Boş.	Kayıt kilitlenmeden önce önceden ısıtılır.
`imageCacheMb`	`int`	`50`.	İşlem ömrü boyunca süren görüntü önbelleğini denetler.
`fontCacheLocking`	`bool`	`true`.	Yazı tipi kaydı değişikliklerini istek işleme dışında tutar.
`artisan`	`array`	Yapılandırılıp kurulmadığı sürece Chrome işleyicisi devre dışıdır.	Şuna eşlenir: `ChromeRendererConfig::fromArray()`.
`defaults`	`array`	Oluşturucu `NextPDF`, boş yazar, dil `en`, varsayılan kenar boşlukları ve varsayılan yazı tipi.	`Services::pdfDocument()` yalnızca `creator`, `language` ve (boş olmadığında) `author` değerlerini uygular; `margin_top`/`right`/`bottom`/`left`, `font_family`, `font_size`, `trim_box` ve `bleed_box` tanımlı varsayılanlardır, ancak şu anda bunları uygulamaz.

Geliştirme notları

GeneratePdfJob, çıktıyı WRITEPATH . 'pdfs' ile sınırlar ve .pdf gerektirir.
Değiştirilmiş kuyruk yüklerinden gelebilecek rastgele kod yürütmeyi önlemek için, App\PdfBuilders dışındaki oluşturucu çağrılabilirleri reddedilir.
Denetleyici akışları için service('pdf') veya paket yardımcısını kullanın; uzun süren üretim için kuyruk işlerini kullanın.