CodeIgniter 4 için NextPDF

Bir bakışta

nextpdf/codeigniter paketi, NextPDF Taşınabilir Belge Biçimi (PDF) motorunu, çerçevenin Services katmanı aracılığıyla bir CodeIgniter 4 uygulamasına bağlar. PDF belgelerinizi denetleyicilerde, işlerde veya komutlarda oluşturup ardından bunları doğal CodeIgniter Hiper Metin Aktarım Protokolü (HTTP) yanıtları olarak döndürürsünüz.

Kurulum

composer require nextpdf/codeigniter

Paketin composer.json dosyası php >=8.4 <9.0, nextpdf/core ^3.0 || ^5.2 ve codeigniter4/framework ^4.6 gerektirir. Ayrıca nextpdf/artisan, nextpdf/premium ve codeigniter4/queue paketlerini de önerir. Gereksinimlerin tam tablosu, isteğe bağlı paketler ve doğrulama adımları için /integrations/codeigniter/install/ sayfasına bakın.

Kavramsal genel bakış

NextPDF, PHP 8.4 tabanlı bir PDF 2.0 motorudur. Çekirdek motor (nextpdf/core) çerçeveden bağımsızdır. HTTP, yönlendirme veya bağımlılık bağlama hakkında bilgi sahibi değildir. nextpdf/codeigniter, motoru bir CodeIgniter 4 uygulamasına bağlayan bağlayıcıdır. Bağlayıcı yerinde olduğunda, kayıt defterlerini, fabrikaları veya yanıt işlemeyi kendiniz bağlamanız gerekmez.

Paket, bir CodeIgniter 4 uygulamasına dört şey ekler:

• Bir Services sınıfı (NextPDF\CodeIgniter\Config\Services): CodeIgniter bunu otomatik olarak keşfeder. Adlandırılmış hizmetleri sunar: fontRegistry, imageRegistry, documentFactory, pdfDocument, pdf, tsaClient ve pdfSigner.
• Bir Pdf kitaplığı (NextPDF\CodeIgniter\Libraries\Pdf) — üst düzey bir denetleyici uygulama programlama arabirimi (API). Tek kullanımlık bir belgeyi sarar ve onu tek çağrıda bir yanıta dönüştürür.
• Bir PdfResponse yardımcısı (NextPDF\CodeIgniter\Http\PdfResponse): satır içi önizleme veya indirme için bir CodeIgniter DownloadResponse oluşturur. Sabit bir yanıt sertleştirme başlığı kümesi ekler.
• İki küresel yardımcı işlev, pdf() ve pdf_document(). Composer files otomatik yükleme girişi ve paket Registrar aracılığıyla kaydedilirler.

Paket, belge oluştururken isteğe bağlı NextPDF uzantılarını da algılar. nextpdf/artisan kurulu olduğunda ve bir Chrome ikili dosyası yapılandırıldığında, belge Chrome işleyicisini alır. NextPDF Pro kurulu olduğunda, PDF/A çıktısı ve dijital imzalama aynı Services yüzeyi aracılığıyla kullanılabilir. Algılama koşulludur ve sessiz gerçekleşir. Paket, mevcut olmayan bir uzantıyı asla gerektirmez.

Neden kapsayıcı bağlaması yerine Services sınıfı

CodeIgniter 4, bir PSR-11 bağımlılık enjeksiyonu kapsayıcısıyla gelmez. Bunun yerine Services bulucusu kullanır. Services bulucusu, statik fabrika yöntemlerine sahip, çerçeve tarafından keşfedilen bir sınıftır. Her yöntem, paylaşılan bir örnek ya da yeni bir örnek döndürür. PSR-11, hizmet bulucu desenini — bir nesnenin kendi bağımlılıklarını getirebilmesi için nesneye bir kapsayıcı geçirmeyi — PSR-11 §1.3 bölümünde SHOULD NOT kip fiiliyle önermez. Paket, CodeIgniter’ın bulucu kuralını izler. Ayrıca bulucu yüzeyini en aza indirir ve açık tutar: her hizmet, bir bool $getShared parametresine sahip adlandırılmış bir fabrika yöntemidir ve çağıranlar kapsayıcı tutamacı yerine somut nesneler alır.

Bu tasarım, CodeIgniter bütünleşmesini Laravel ve Symfony bütünleşmeleriyle tutarlı tutar. Her bütünleşme, aynı mantıksal hizmetleri kendi çerçevesinin deyimi aracılığıyla sunar.

API yüzeyi

Giriş noktası	Tür	Dönüş	Yaşam süresi
Services::fontRegistry()	hizmet	FontRegistryInterface	paylaşılan (ısıtılır, ardından kilitlenir)
Services::imageRegistry()	hizmet	ImageRegistry	paylaşılan (sınırlı, en uzun süredir kullanılmayan (LRU) önbelleği)
Services::documentFactory()	hizmet	DocumentFactoryInterface	paylaşılan (durumsuz)
Services::pdfDocument(false)	hizmet	NextPDF\Core\Document	çağrı başına yeni
Services::pdf(false)	hizmet	NextPDF\CodeIgniter\Libraries\Pdf	çağrı başına yeni
Services::tsaClient()	hizmet	?TsaClient	paylaşılan; zaman damgası yetkilisi (TSA) URL’si olmadığında null olur
Services::pdfSigner(false)	hizmet	?SignerInterface	yeni; imzalama devre dışı olduğunda null olur
pdf()	yardımcı	Pdf	çağrı başına yeni
pdf_document()	yardımcı	Document	çağrı başına yeni
PdfResponse::inline() / download()	statik	DownloadResponse	çağrı başına
GeneratePdfJob	kuyruk işi	—	gönderim başına bir

Kod örneği — hızlı başlangıç

Bir denetleyici, üç satırda bir PDF döndürür. Services::pdf(), yeni bir belgeyi saran yeni bir Pdf kitaplığı döndürür. Ardından download() bir CodeIgniter DownloadResponse oluşturur.

<?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");
    }
}

Tam çalıştırılabilir adım adım kılavuz /integrations/codeigniter/quickstart/ içinde yer alır. Yönlendirmeyi, satır içi önizlemeyi ve pdf() ile pdf_document() yardımcılarının kullanım çeşitlerini kapsar.

Kod örneği — üretim

Üretimde, Services::pdf(false) ile paylaşılmayan bir örnek isteyin. Tek temel istisna olan NextPDF\Exception\NextPdfException istisnasını yakalayın; her çekirdek ve uzantı hatası ondan türer. Hatayı yutmak yerine bağlamıyla birlikte günlüğe kaydedin.

try {
    $pdf = Services::pdf(false);
    $pdf->document()->addPage();
    $pdf->document()->cell(0, 10, "Invoice #{$id}");

    return $pdf->download("invoice-{$id}.pdf");
} catch (NextPdfException $e) {
    $logger->error('pdf.invoice.failed', [
        'invoice_id' => $id,
        'exception' => $e::class,
        'message' => $e->getMessage(),
    ]);

    return $this->response
        ->setStatusCode(ResponseInterface::HTTP_INTERNAL_SERVER_ERROR)
        ->setJSON(['error' => 'pdf_generation_failed', 'invoice_id' => $id]);
}

Eksiksiz üretim denetleyicisi /integrations/codeigniter/production-usage/ içinde yer alır. Gözlemlenebilirlik için zamanlama ölçümü, çalışan açısından güvenli yaşam süreleri ve eşzamansız oluşturma ekler.

Sınır durumları ve tuzaklar

• Yazı tipi ve görüntü kayıt defterleri, süreç yaşam süreli tekil örneklerdir. Bir belge asla paylaşılmaz. pdfDocument ve pdf her çağrıda yeni bir örnek döndürür, böylece bir istek içeriğini diğerine sızdıramaz. Services::pdf(false) ve pdf() her ikisi de yeni bir belgeyi saran yeni bir kitaplık döndürür.
• Paket, mbstring ve zlib PHP uzantılarını gerektirir. Yazı tipi kayıt defteri bunları süreç başına bir kez doğrular. Uzantılardan biri yoksa, yazı tipi kayıt defteri eksik uzantıyı adlandıran bir çalışma zamanı hatası oluşturur.
• İsteğe bağlı uzantı davranışı, aynı uygulamada neyin kurulu olduğuna bağlıdır. Yalnızca nextpdf/core mevcut olduğunda, imzalama ve PDF/A yolları null döndürür veya atlanır. Asla hata yükselterek başarısız olmazlar.

Performans

Bütünleşme, motorun kendisinin ötesinde ölçülebilir bir ek yük getirmez. Yazı tipi kayıt defteri bir kez ayrıştırılır ve ardından kilitlenir. Görüntü kayıt defteri, imageCacheMb ayarıyla (varsayılan olarak 50 MB) sınırlanan bir LRU önbellektir. PDF oluşturma maliyetini çekirdek motor ve belge içeriği belirler; bağlayıcı belirlemez. Bu belge kümesi için sayfa başına bütçe 1500 ms duvar süresi / 128 MB tepe değeridir. Gerçek tarifler kendi bütçelerini ön bilgide belirler.

Güvenlik notları

PdfResponse, yaydığı her PDF’ye sabit bir yanıt başlığı kümesi ekler: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy: default-src 'none', X-Robots-Tag: noindex, nofollow ve Referrer-Policy: no-referrer. Dosya adları temizlenir ve ASCII dışı adlar bir Yorum Talebi (RFC) 5987 genişletilmiş parametresiyle yayılır. Kuyruk işi, oluşturucu çağrılabilirleri App\PdfBuilders ad alanıyla kısıtlar ve çıktı yollarını WRITEPATH/pdfs/ ile sınırlar. Tam tehdit modeli için /integrations/codeigniter/security-and-operations/ sayfasına bakın.

Uyumluluk

• Modül keşfi, Composer’ın PSR-4 otomatik yüklemesine dayanır. Bir ad alanı öneki bir temel dizine eşlenir ve tam nitelikli sınıf adı bir dosya yoluna eşlenir (PSR-4 §x1.x3).
• Services tasarımı, PSR-11 §1.3 altında tartışılan bulucu kılavuzunu izler.

Ticari bağlam

NextPDF çekirdeği Apache-2.0 lisanslıdır. Dijital imzalar, PDF/A arşivleme ve Factur-X e-fatura gömme, NextPDF Pro ve NextPDF Enterprise tarafından sağlanır. CodeIgniter paketi, ilgili hizmet yöntemlerini sunar. Bu yöntemler, eşleşen Premium paketi aynı uygulamada kurulana kadar null döndürür.

Ayrıca bakın

• /integrations/codeigniter/install/ — paketi kurun ve doğrulayın.
• /integrations/codeigniter/quickstart/ — bir denetleyicideki ilk PDF.
• /integrations/codeigniter/configuration/ — her yapılandırma anahtarı.
• /integrations/codeigniter/boot-and-discovery/ — CodeIgniter’ın Services sınıfını nasıl bulduğu.
• /integrations/codeigniter/integration/ — bağlama referansı ve duman testi.