CodeIgniter 4'te üretim kullanımı

Bir bakışta

Üretim denetleyicileri, somut NextPDF hizmetlerini alır. Belgelenmiş özel durum hiyerarşisini açıkça işler ve gözlemlenebilirlik sinyalleri yayar. Uzun süren taşınabilir belge biçimi (PDF) işlerini, CodeIgniter 4 Queue üzerinden istek dışına taşıyın.

Kavramsal genel bakış

CodeIgniter 4, paketin hizmetlerini kendi konumlandırıcısı aracılığıyla çözümler. Hizmet konumlandırıcı deseninde bir nesne, bir kapsayıcı alır ve kendi bağımlılıklarını almak için bu kapsayıcıyı kullanır. PHP standart önerisi (PSR) kılavuzu bu deseni önermez (PSR-11 §1.3, SHOULD NOT kipi). Bu kılavuza uymak için her NextPDF hizmetini denetleyici sınırında bir kez çözümleyin, ardından somut nesneyi içeriye geçirin. Services sınıfını veya bir kapsayıcıyı etki alanı kodunuza geçirmeyin.

Her PHP örneği declare(strict_types=1); ifadesini kendi satırına koyar (PSR-12 §x1.x3.p34).

API yüzeyi

Üretim konusu	Doğrulanmış yüzey
Hizmetleri çözümleme	Services::pdf(false), Services::pdfDocument(false), Services::documentFactory()
Yanıt oluşturma	PdfResponse::download() / inline() → DownloadResponse
Hataları yakalama	NextPDF\Exception\NextPdfException (ekosistem temel türü)
Eşzamansız oluşturma	GeneratePdfJob, şurada kayıtlı: Config\Queue::$jobHandlers
Yol / çağrılabilir korumalar	GeneratePdfJob şunu oluşturur: InvalidArgumentException

Üretim denetleyicisi — hata işleme ve gözlemlenebilirlik

Çekirdek motor, tümü NextPDF\Exception\NextPdfException türünü genişleten özel durumlar üretir. Çekirdek ve uzantı hatalarını kapsamak için bu tek türü yakalayın. Bu catch bloğu bağlamı günlüğe kaydeder ve tanımlı bir hata yanıtı döndürür; asla boş bir catch kullanmaz.

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;
use CodeIgniter\HTTP\ResponseInterface;
use NextPDF\CodeIgniter\Config\Services;
use NextPDF\Exception\NextPdfException;
use Psr\Log\LoggerInterface;

final class InvoiceController extends BaseController
{
    public function download(int $id): DownloadResponse|ResponseInterface
    {
        /** @var LoggerInterface $logger */
        $logger = \service('logger');

        $start = \hrtime(true);

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

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

            $logger->info('pdf.invoice.generated', [
                'invoice_id' => $id,
                'elapsed_ms' => (\hrtime(true) - $start) / 1_000_000,
            ]);

            return $response;
        } 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]);
        }
    }
}

Services::pdf(false) her çağrıda yeni bir kitaplık örneği ve yeni bir temel belge döndürür. Eşzamanlı istekler belge durumunu asla paylaşmaz. Paketin işlevsel testleri bu davranışı doğrular.

İşçiler için güvenli hizmet ömürleri

Yazı tipi ve görüntü kayıtları, tasarım gereği işlem ömrü boyunca tekil örneklerdir. Yazı tipi kaydı bir kez hazırlanır ve kilitlenir. Görüntü kaydı, sınırlı bir LRU önbelleğidir. Uzun ömürlü bir işçide (CodeIgniter spark sunucusu, RoadRunner tarzı çalıştırıcı veya bir kuyruk işçisi) bu kasıtlıdır: maliyetli kayıtlar kalıcı kalır, her belge ise yeni oluşturulur. İstek veya iş kodunda paylaşılan bir belge (Services::pdfDocument(true)) talep etmeyin; bu yalnızca test sıfırlaması için vardır ve içeriği istekler arasında paylaşır.

CodeIgniter Queue ile eşzamansız oluşturma

GeneratePdfJob, PDF oluşturmayı codeigniter4/queue aracılığıyla istek dışında çalıştırır. Kuyruk çalışma zamanı iki ayar gerektirir. İki ayarı da doğru yapılandırın.

1. İş işleyicisini ada göre kaydedin

Kuyruk, bir işi sınıf dizesiyle değil, bir ad anahtarıyla çözümler. Kuyruk işleyicisi, gönderilen iş adını Config\Queue::$jobHandlers anahtarlarına göre doğrular. Bilinmeyen bir adı CodeIgniter\Queue\Exceptions\QueueException ile reddeder. İşi app/Config/Queue.php dosyasında kaydedin:

<?php

declare(strict_types=1);

namespace Config;

use CodeIgniter\Queue\Config\Queue as BaseQueue;
use NextPDF\CodeIgniter\Jobs\GeneratePdfJob;

final class Queue extends BaseQueue
{
    /** @var array<string, class-string> */
    public array $jobHandlers = [
        'generate-pdf' => GeneratePdfJob::class,
    ];
}

2. Kayıtlı ada göre gönderin

İşi gönderirken kayıtlı adı ikinci bağımsız değişken olarak verin. İlk bağımsız değişken kuyruk adıdır. Üçüncü bağımsız değişken ise iş verisi dizisidir.

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\ResponseInterface;

final class InvoiceController extends BaseController
{
    public function queueInvoice(int $id): ResponseInterface
    {
        \service('queue')->push('pdf-queue', 'generate-pdf', [
            'builder' => 'App\\PdfBuilders\\InvoiceBuilder::build',
            'outputPath' => WRITEPATH . 'pdfs/invoice-' . $id . '.pdf',
            'context' => ['invoice_id' => $id],
        ]);

        return $this->response
            ->setStatusCode(ResponseInterface::HTTP_ACCEPTED)
            ->setJSON(['status' => 'queued', 'invoice_id' => $id]);
    }
}

3. Oluşturucuyu App\PdfBuilders altında uygulayın

İş, oluşturucu çağrılabilirlerine yalnızca App\PdfBuilders ad alanında izin verir ve çıktı yollarını WRITEPATH/pdfs/ ile sınırlar. Oluşturucuyu statik bir yöntem olarak uygulayın. Yeni bir Document ile bağlam dizisini alır, ardından belgeyi döndürür.

<?php

declare(strict_types=1);

namespace App\PdfBuilders;

use NextPDF\Core\Document;

final class InvoiceBuilder
{
    /** @param array<string, mixed> $context */
    public static function build(Document $document, array $context): Document
    {
        $invoiceId = (int) ($context['invoice_id'] ?? 0);

        $document->addPage();
        $document->cell(0, 10, "Invoice #{$invoiceId}");

        return $document;
    }
}

İşçiyi çalıştırın

php spark queue:work pdf-queue

Her iş çalıştırması, Services::pdfDocument() ile yeni bir belgeyle başlar. Oluşturucuyu uygular, ardından doğrulanmış yola kaydeder. Paket testleri, art arda iki iş çalıştırmasının belge durumunu paylaşmadığını doğrular.

Uç durumlar ve tuzaklar

• Kuyruk, gönderim sırasında GeneratePdfJob::class değerini iş adı olarak reddeder; çünkü bu, kayıtlı 'generate-pdf' anahtarı değildir. Her zaman jobHandlers anahtarını gönderin.
• Oluşturucu dizesi tam olarak App\PdfBuilders\<Class>::<method> ile eşleşmelidir. İşlevler, diğer ad alanları veya ön ekli ya da son ekli yükler, herhangi bir kod çalışmadan önce InvalidArgumentException oluşturur.
• Çıktı yolu, WRITEPATH/pdfs/ içinde çözümlenmeli ve .pdf ile bitmelidir (büyük/küçük harfe duyarsız). Dizin geçişi ve kardeş dizin ön eki taşıyan yollar reddedilir.
• codeigniter4/queue, paketin yalnızca geliştirme bağımlılığıdır. İşçileri çalıştıran uygulamada bunu zorunlu bağımlılık olarak ekleyin.

Performans

Kayıtlar her işçi işlemi başına bir kez oluşturulur. Belge oluşturma maliyeti, bağdaştırıcıyla değil içerikle ölçeklenir. Büyük toplu işler için kuyruk yolunu kullanın; böylece istek işçileri yanıt verebilir durumda kalır. Ölçülebilir hedefi olan her tarifte bir performance_budget ayarlayın.

Güvenlik notları

Kuyruk işi, en yüksek riskli yüzeydir. Broker’a erişilebildiğinde, kuyruk yükleri saldırgan tarafından etkilenebilir. Çağrılabilir izin listesi ve yol kısıtlaması, doğrulanmış reddetme durumlarıyla birlikte /integrations/codeigniter/security-and-operations/ bölümünde ele alınmıştır.

Uyumluluk

• Denetleyiciler, PSR-11 §1.3 hizmet konumlandırıcı kılavuzuyla tutarlı biçimde, bir kapsayıcıyı değil somut hizmetleri alır.

Ticari bağlam

NextPDF çekirdeği Apache-2.0 lisansı altındadır. Kuyruk işlerinde imzalı ve PDF/A çıktısı üretmek için işçi ortamına NextPDF Pro veya Enterprise kurun. CodeIgniter paketi, ilgili hizmet yöntemlerini sunar. Karşılık gelen Premium paketi kurulana kadar null döndürürler. Bkz. </get-license/?intent=codeigniter-async-signing>.

Ayrıca bakınız

• /integrations/codeigniter/quickstart/ — bu denetleyicilerin en yalın sürümü.
• /integrations/codeigniter/configuration/ — imzalama, zaman damgası yetkilisi (TSA) ve yol yapılandırması.
• /integrations/codeigniter/security-and-operations/ — kuyruk tehdit modeli ve sıkılaştırma.
• /integrations/codeigniter/troubleshooting/ — kuyruk ve keşif hata modları.
• /integrations/codeigniter/integration/ — bağlantı başvurusu ve duman testi.