CodeIgniter 4 için NextPDF'i yapılandırma

Bir bakışta

NextPDF yapılandırması NextPDF\CodeIgniter\Config\NextPdf sınıfında yer alır; bu sınıf, CodeIgniter BaseConfig alt sınıfıdır. Değerleri app/Config/ içinde sınıfı genişleterek ya da .env anahtarlarını nextpdf. önekiyle ayarlayarak geçersiz kılabilirsiniz. Varsayılanlar ek yapılandırma olmadan çalışır.

Kavramsal genel bakış

NextPdf, türlenmiş bir BaseConfig sınıfıdır. Bu sınıf, kasıtlı olarak final değildir. CodeIgniter’da uygulama yapılandırması paket sınıfını genişletir; böylece uygulamanız varsayılanları geçersiz kılabilir. CodeIgniter yapılandırmayı oluştururken BaseConfig, iç içe geçmiş dizi anahtarları dâhil her genel özellik için ortam geçersiz kılmalarını çözümler.

Varsayılan yazı tipi ve önbellek yolları CodeIgniter’in WRITEPATH sabitini kullanır: WRITEPATH . 'fonts' ve WRITEPATH . 'cache/nextpdf'.

Yapılandırma anahtarları

Aşağıdaki her anahtar, NextPdf sınıfının bir genel özelliğidir. Varsayılanlar paket kaynağına göre doğrulanmıştır.

Sayfa ve belge varsayılanları

Anahtar	Tür	Varsayılan	Açıklama
`pageFormat`	`string`	`A4`	Sayfa biçimi.
`orientation`	`string`	`P`	`P` dikey, `L` yatay anlamına gelir.
`unit`	`string`	`mm`	Ölçü birimi.
`defaults.creator`	`string`	`NextPDF`	Taşınabilir Belge Biçimi (PDF) oluşturucusu üst verisi.
`defaults.author`	`string`	`''`	Yazar üst verisi; boş olduğunda atlanır.
`defaults.language`	`string`	`en`	Belgenin dil etiketi.
`defaults.margin_top`	`float`	`10.0`	Üst kenar boşluğu.
`defaults.margin_right`	`float`	`10.0`	Sağ kenar boşluğu.
`defaults.margin_bottom`	`float`	`10.0`	Alt kenar boşluğu.
`defaults.margin_left`	`float`	`10.0`	Sol kenar boşluğu.
`defaults.font_family`	`string`	`dejavusans`	Varsayılan yazı tipi ailesi.
`defaults.font_size`	`float`	`12.0`	Varsayılan yazı tipi boyutu.
`defaults.trim_box`	`list<float>\|null`	`null`	Ayarlanırsa kırpma kutusu.
`defaults.bleed_box`	`list<float>\|null`	`null`	Ayarlanırsa taşma kutusu.

Paket, defaults.creator ve defaults.language anahtarlarını her belgeye uygular. defaults.author anahtarını yalnızca değer boş olmadığında uygular.

Yollar ve önbellekler

Anahtar	Tür	Varsayılan	Açıklama
`fontsPath`	`string`	`WRITEPATH/fonts`	Yazı tipi dosyası dizini.
`cachePath`	`string`	`WRITEPATH/cache/nextpdf`	Önbellek dizini.
`preloadFonts`	`list<string>`	`[]`	Önyükleme sırasında hazırlanan mutlak yazı tipi yolları.
`imageCacheMb`	`int`	`50`	En son kullanılan (LRU) görüntü önbelleği bütçesi, megabayt (MB) cinsinden.
`fontCacheLocking`	`bool`	`true`	Ön ısıtmadan sonra yazı tipi önbelleğini kilitler.

Yazı tipi kayıt defteri, fontsPath yolunda bir akış sarmalayıcı (://) ya da boş bayt bulunursa bunu reddeder ve çalışma zamanı hatası oluşturur. Bkz.: /integrations/codeigniter/security-and-operations/.

Arşivleme ve renk (NextPDF Pro)

Anahtar	Tür	Varsayılan	Açıklama
`pdfa`	`string\|null`	`null`	PDF/A sürümü: `4`, `4e`, `4f`.
`iccProfile.rgb`	`string\|null`	`null`	Kırmızı, yeşil ve mavi (RGB) Uluslararası Renk Konsorsiyumu (ICC) profili yolu.
`iccProfile.cmyk`	`string\|null`	`null`	Camgöbeği, macenta, sarı ve anahtar (CMYK) ICC profili yolu.

pdfa yalnızca NextPDF Pro kurulu olduğunda ve arşivleme yeteneği kullanılabilir olduğunda etkili olur. Yalnızca çekirdek sürümde bu anahtar yok sayılır.

Dijital imza (NextPDF Pro / Enterprise)

Anahtar	Tür	Varsayılan	Açıklama
`signature.enabled`	`bool`	`false`	İmzalayıcı hizmetini etkinleştirir.
`signature.certificate`	`string\|null`	`null`	Sertifika dosyası yolu.
`signature.private_key`	`string\|null`	`null`	Özel anahtar dosyası yolu.
`signature.password`	`string`	`''`	Özel anahtar parolası.
`signature.extra_certs`	`list<string>`	`[]`	Ek zincir sertifikası yolları.
`signature.level`	`string`	`B-B`	İmza düzeyi tanımlayıcısı.

Services::pdfSigner() varsayılan olarak null döndürür; bunun tek istisnası signature.enabled değerinin true olması ve signature.certificate değerinin boş olmamasıdır. Varsayılan düzey B-B değeridir. NextPDF Pro, B-B temel imzasını sağlar. Uzun vadeli doğrulama düzeyleri ayrı bir Enterprise yeteneğidir ve burada değil, Premium referansında belgelenmiştir.

PDF Gelişmiş Elektronik İmzaları (PAdES) B-T, Core motoru tarafından üretilir. CodeIgniter tümleştirmesi kendi başına B-T eklemez ve Pro, yalnızca B-B temelini sunar. Bu belge, Pro B-T desteğine ulaşırsa ve ulaştığında güncellenecektir.

Zaman damgası otoritesi

Anahtar	Tür	Varsayılan	Açıklama
`tsa.url`	`string\|null`	`null`	Zaman Damgası Otoritesi (TSA) uç noktası URL’si.
`tsa.username`	`string`	`''`	TSA temel kimlik doğrulama kullanıcı adı.
`tsa.password`	`string`	`''`	TSA temel kimlik doğrulama parolası.
`tsa.cert`	`string\|null`	`null`	İstemci sertifikası yolu.
`tsa.key`	`string\|null`	`null`	İstemci anahtarı yolu.
`tsa.timeout`	`int`	`30`	Saniye cinsinden istek zaman aşımı.
`tsa.pinned_public_keys`	`list<string>`	`[]`	Sabitlenmiş TSA açık anahtarları.
`tsa.warn_on_key_rotation`	`bool`	`true`	TSA anahtarı döndürüldüğünde uyarır.
`tsa.allow_insecure_http`	`bool`	`false`	TSA için düz metin HTTP’ye izin verir.

Services::tsaClient() çağrısı null döndürür; bunun koşulu, tsa.url değerinin null ya da boş bir dize olmasıdır. Zaman damgası gerektiren bir imza düzeyi seçtiğinizde, imzalayıcı TSA istemcisini otomatik olarak ekler.

OCSP önbelleği

Anahtar	Tür	Varsayılan	Açıklama
`ocspCache.enabled`	`bool`	`true`	Çevrim içi sertifika durumu protokolü (OCSP) yanıt önbelleğini etkinleştirir.
`ocspCache.ttl`	`int`	`86400`	Saniye cinsinden önbellek yaşam süresi (TTL).
`ocspCache.directory`	`string\|null`	`null`	Önbellek dizini; null olduğunda motor varsayılanı kullanılır.

Chrome HTML işleyicisi (NextPDF Artisan)

Anahtar	Tür	Varsayılan	Açıklama
`artisan.chrome_binary`	`string\|null`	`null`	Chrome/Chromium ikili dosyasının yolu.
`artisan.render_timeout`	`int`	`30`	Saniye cinsinden işleme zaman aşımı.
`artisan.default_css`	`string`	`''`	Varsayılan stil sayfası.
`artisan.no_sandbox`	`bool`	`false`	Chrome’a `--no-sandbox` geçirir.
`artisan.max_html_size`	`int`	`5000000`	Bayt cinsinden en büyük girdi HTML boyutu.

Chrome işleyicisi, belge için yalnızca artisan.chrome_binary ayarlandığında ve nextpdf/artisan kurulu olduğunda yapılandırılır.

Şununla geçersiz kılma: `.env`

BaseConfig, ortam geçersiz kılmalarını özellik bazında çözümler. Arama anahtarı, küçük harfli kısa sınıf adıdır (nextpdf); ardından özellik yolu gelir. İç içe geçmiş dizi anahtarlarını adreslemek için noktaları kullanın. Hem noktalı hem de alt çizgili biçimler kabul edilir.

nextpdf.fontsPath = /var/www/writable/fonts
nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem
nextpdf.signature.private_key = /etc/nextpdf/key.pem
nextpdf.tsa.url = https://tsa.example.com/timestamp
nextpdf.artisan.chrome_binary = /usr/bin/chromium
nextpdf.defaults.creator = Acme Billing
nextpdf.defaults.language = zh-TW

Önek, küçük harfli kısa sınıf adıdır. Önek nextpdf olarak kalır — sınıf NextPdf biçiminde yazılmış olsa da. Tam nitelikli biçimi de kullanabilirsiniz (NextPDF\CodeIgniter\Config\NextPdf.fontsPath).

Sınıfı genişleterek geçersiz kılma

Türlenmiş, sürüm denetimli yapılandırma için paket sınıfını app/Config/ içinde genişletin. CodeIgniter, paket varsayılanı yerine uygulama sınıfını yükler. Bu dosya bir sınıf bildirir ve hiçbir yan etkiye yol açmaz. Böylece dosya, bir dosyanın ya sembolleri bildirmesi ya da yan etkili mantık çalıştırması ama ikisini birden yapmaması yönündeki PSR-1 beklentisiyle uyumlu kalır (PSR-1 §x1.x1.p3).

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

final class NextPdf extends BaseNextPdf
{
    public int $imageCacheMb = 100;

    public string $fontsPath = WRITEPATH . 'fonts';

    /** @var array{creator: string, author: string, language: string, margin_top: float, margin_right: float, margin_bottom: float, margin_left: float, font_family: string, font_size: float, trim_box: list<float>|null, bleed_box: list<float>|null} */
    public array $defaults = [
        'creator' => 'Acme Billing',
        'author' => 'Acme, Inc.',
        'language' => 'en',
        'margin_top' => 12.0,
        'margin_right' => 12.0,
        'margin_bottom' => 12.0,
        'margin_left' => 12.0,
        'font_family' => 'dejavusans',
        'font_size' => 11.0,
        'trim_box' => null,
        'bleed_box' => null,
    ];
}

Sınır durumları ve tuzaklar

İç içe geçmiş tek bir anahtarı .env ile geçersiz kılmak yalnızca o anahtarı değiştirir; dizinin geri kalanı varsayılan değerlerini korur.
.env değerleri dizedir. CodeIgniter, true/false ile sayısal dizeleri tür dönüşümüne tabi tutar. Birebir dize olarak kalması gereken değerleri tırnak içine alın.
Sınıfı kısmi bir defaults dizisiyle genişletmek tüm dizinin yerini alır. Yukarıda gösterildiği gibi her anahtarı dâhil edin.

Güvenlik notları

Sertifika ve anahtar yollarını kaynak denetiminin dışında tutun. Bunları .env ya da bir gizli bilgi yöneticisi aracılığıyla sağlayın. tsa.allow_insecure_http üretimde false olarak kalmalıdır. Bkz.: /integrations/codeigniter/security-and-operations/.

Uygunluk

Uygulama yapılandırmasını genişleten dosya bir sınıf bildirir ve hiçbir yan etkiye yol açmaz (PSR-1 §x1.x1.p3).

Ticari bağlam

NextPDF çekirdeği Apache-2.0 lisanslıdır. signature.* ve pdfa anahtarları yalnızca NextPDF Pro ya da Enterprise kurulu olduğunda etkili olur. CodeIgniter paketi ilgili hizmet yöntemlerini sunar. Bu yöntemler, eşleşen Premium paketi kurulana kadar null döndürür. Bkz.: </get-license/?intent=codeigniter-signing>.

Ayrıca bakınız

/integrations/codeigniter/install/ — paketi kurun.
/integrations/codeigniter/quickstart/ — ilk PDF’iniz.
/integrations/codeigniter/production-usage/ — DI ile bağlanan denetleyiciler ve kuyruk işleri.
/integrations/codeigniter/security-and-operations/ — imzalama ve yol yapılandırmasını sertleştirme.