CodeIgniter geliştirici kılavuzu

Genel bakış

CodeIgniter paketi, tek bir Portable Document Format (PDF) belgesiyle çalışmak için hizmet fabrikaları, yardımcı işlevler ve hafif bir Pdf kitaplık sarmalayıcısı sağlar. Sarmalayıcıyı denetleyicilerde kullanın. CodeIgniter kuyruk yüklerinin serileştirilebilir veri olması gerektiğinden, kuyruk işleri statik oluşturucu çağrılabilirleri kullanır.

Denetleyici akışlarını, hizmetleri, kuyruk oluşturucularını ve testleri nextpdf/codeigniter çevresinde tasarlarken bu kılavuzu kullanın.

Mimari sınırı

Katman	Sahibi	Sorumluluk	Buraya koymayın
Denetleyici	Uygulama	Yetkilendirmeyi yapın, bir oluşturucu ya da hizmet çağırın ve bir DownloadResponse döndürün.	Paylaşılan yerleşim mantığı.
Kitaplık sarmalayıcısı	nextpdf/codeigniter	Tek bir Document nesnesini sarmalayın; yanıt ve kaydetme yardımcıları sağlayın.	Uzun ömürlü belge depolama.
Hizmet fabrikası	nextpdf/codeigniter	Paylaşılan kayıt defterleri ve yeni belgeler oluşturun.	İşe özgü depolama kökleri.
Kuyruk oluşturucu	Uygulama	Statik çağrılabilir girdiden belge oluşturun.	Serileştirilemeyen istek nesneleri ya da durum.
Çekirdek motor	nextpdf/nextpdf	PDF’yi oluşturun ve serileştirin.	CodeIgniter yanıtı ya da kuyruk ilkesi.

Çalışma zamanı yaşam döngüsü

Aşama	Davranış	Geliştirici eylemi
Otomatik yükleme kaydı	Registrar::Autoload(), modül için yardımcı yüklemeyi kaydeder.	Modülü CodeIgniter yapılandırması aracılığıyla yükleyin.
Hizmet çözümlemesi	Services::pdf(), varsayılan olarak yeni bir belgeyi saran bir sarmalayıcı döndürür.	İstek başına bir kez çözümleyin.
Yazma	Uygulama kodu, çekirdek belge çağrılarına erişmek için Pdf::document() işlevini kullanır.	Belge oluşturma kodunu hizmetlerde ya da oluşturucularda tutun.
Yanıt	PdfResponse, bir DownloadResponse döndürür.	PDF başlıklarını paketin ayarlamasına izin verin.
Kuyruk yürütme	GeneratePdfJob::process(), oluşturucuyu ve çıktı yolunu doğrular, ardından kaydeder.	Kuyruk oluşturucularını App\PdfBuilders altına koyun.

Önerilen uygulama yapısı

Yol	Amaç
app/PdfBuilders/*	Statik, kuyruğa uygun oluşturucular; GeneratePdfJob bunları kabul eder.
app/Libraries/*	Yinelenen belge iş akışları çevresinde isteğe bağlı uygulama sarmalayıcıları.
app/Services/*	Alan verilerini alma ve depolama ilkesi.
app/Config/NextPdf.php	Paket yapılandırması için uygulamaya özel geçersiz kılmalar.
tests/app/PdfBuilders/*	Oluşturucu ve kuyruk yükü testleri.

Kısa akışlar için paket yardımcılarını kullanın. Belge oluşturma mantığı doğrudan test edebileceğiniz bir sınıfa ait olduğunda açık hizmet çağrıları kullanın.

<?php

namespace App\Controllers;

final class InvoiceController extends BaseController
{
    public function download(int $id)
    {
        $pdf = pdf();
        $pdf->document()
            ->setTitle('Invoice ' . $id)
            ->addPage()
            ->writeHtml('<h1>Invoice ' . $id . '</h1>');

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

Kuyruk oluşturucu deseni

Kuyruk oluşturucuları statik, belirlenimci olmalı ve App\PdfBuilders altında konumlandırılmalıdır. Bağlam dizisini serileştirilebilecek ve denetlenebilecek kadar yalın tutun.

<?php

namespace App\PdfBuilders;

use NextPDF\Core\Document;

final class InvoiceBuilder
{
    public static function build(Document $document, array $context): Document
    {
        $document->setTitle((string) $context['title'])
            ->addPage()
            ->writeHtml((string) $context['html']);

        return $document;
    }
}

İş, çıktıyı yapılandırılmış uygulama PDF diziniyle sınırlar. Uygulamanız kiracıya özgü depolamaya gereksinim duyuyorsa, bu ilkeyi tek bir hizmette toplayın ve işi göndermeden önce test edin.

Genişletme noktaları

Genişletme noktası	Şunun için kullanın	Kısıt
Services::pdfDocument()	Belge oluşturmayı özelleştirin.	Yeni bir belge döndürmelidir.
Services::fontRegistry()	Yazı tiplerini ısıtın ve kayıt defterine erişin.	Güvenli olmayan yolları reddedin ve ısıtma işleminden sonra kayıt defterini kilitli tutun.
Services::pdfSigner()	İsteğe bağlı dijital imzalamayı etkinleştirin.	İmzalama devre dışı olduğunda null döndürün.
NextPDF\CodeIgniter\Libraries\Pdf	Denetleyiciye dönük belge işlemlerini sarmalayın.	Bir sarmalayıcı tek bir belgeye eşlenir.
App\PdfBuilders::*	Kuyruğa uygun belge oluşturucuları.	Statik çağrılabilir dize gereklidir.
app/Config/NextPdf.php	Uygulama varsayılanları ve tümleştirme ayarları.	Üretim değerlerini açıkça belirtin.

Geliştirme iş akışı

1. Önce pdf() ya da service('pdf') çağıran bir denetleyici oluşturun.
2. Yinelenen belge oluşturma mantığını app/PdfBuilders içine ya da bir uygulama hizmetine taşıyın.
3. Oluşturma işlemi istek yolu için fazla yavaş kaldığında GeneratePdfJob kullanın.
4. Kuyruk bağlamını serileştirilebilir ve küçük tutun.
5. İlkeyi bilinçli olarak genişletmediğiniz sürece çıktıyı onaylanmış PDF depolama kökü altında depolayın.
6. Yardımcılar, hizmetler, kuyruk yükleri ve güvenli olmayan yollar için testler ekleyin.

Hata işleme

Hata	Nerede işlenmelidir	Önerilen yanıt
Eksik uzantı ya da güvenli olmayan yazı tipi yolu	Hizmet fabrikası.	Hizmet çözümleme sırasında erken hata verin.
Geçersiz oluşturucu çağrılabiliri	Kuyruk işi doğrulaması.	İşi reddedin ve oluşturucu dizesini gizli bilgiler olmadan günlüğe kaydedin.
Güvenli olmayan çıktı yolu	Depolama hizmeti ve kuyruk işi.	Göndermeden önce reddedin ve iş doğrulamasını koruyun.
Yanıt serileştirme hatası	Denetleyici ya da çerçevenin hata işlemesi.	Kısmi bir yanıt gövdesi göndermeyin.
İsteğe bağlı Premium sınıfı kullanılamıyor	Hizmet yöntemi dönüş değeri.	İsteğe bağlı e-fatura özelliklerini kullanmadan önce null değerini açıkça işleyin.

Güvenli varsayılanlar

Husus	Varsayılan	Ne zaman geçersiz kılınmalı
Kuyruk oluşturucu ad alanı	App\PdfBuilders.	Güvenlik ilkesini de güncellemediğiniz sürece varsayılanı koruyun.
Çıktı kökü	WRITEPATH/pdfs.	Yalnızca daha güçlü bir izin listesiyle geçersiz kılın.
Yanıt dosya adı	document.pdf.	Temizlenmiş iş dosyası adları kullanın.
Akış yöntemleri	Diğer çerçevelerle Application programming interface (API) eş değerliği.	CodeIgniter’da akışa bir bellek sınırı olarak güvenmeyin.
Belge hizmeti	Varsayılan olarak yeni.	İstek kodundan paylaşılan belge talep etmeyin.

Test denetim listesi

• Hizmet testleri, her Services::pdf() çözümlemesinin bağımsız bir belge döndürdüğünü doğrular.
• Yardımcı testleri, pdf() ve pdf_document() işlevlerinin yeni nesneler döndürdüğünü doğrular.
• Yanıt testleri, başlıkları ve dosya adı normalleştirmesini doğrular.
• Kuyruk testleri, geçersiz oluşturucu dizelerini ve güvenli olmayan çıktı yollarını kapsar.
• Oluşturucu testleri, temsili bağlam verileri kullanır.
• Yapılandırma testleri, yazı tipi yolunu, önbellek yolunu, imzalamanın devre dışı olduğu durumları ve Time-Stamp Authority (TSA)‘nin devre dışı olduğu durumları kapsar.