Gereksinimler ve Ön Hazırlık

Dinamik PDF üretimi için PHP 8.2 veya üzeri bir sürüm kullanmanız önerilir. PDF oluşturma motoru olarak sektör standardı olan Dompdf kütüphanesini kullanacağız. Bu kütüphane, HTML ve CSS kodlarınızı PDF belgesine dönüştürmek için oldukça esnek bir yapı sunar.

Projenize Dompdf'i dahil etmek için Composer paket yöneticisini kullanmalısınız. Terminal ekranınızda proje dizininize giderek şu komutu çalıştırın:

composer require dompdf/dompdf

Bu komut, gerekli tüm bağımlılıkları vendor dizinine indirecektir. Ayrıca, yerel geliştirme ortamınızda mbstring ve gd PHP eklentilerinin aktif olduğundan emin olun. Bu eklentiler, metin kodlaması ve görsel işleme süreçleri için zorunludur.

PDF Fatura Tasarımı İçin HTML Şablonu Oluşturma

Dinamik bir fatura oluşturmanın ilk adımı, verilerin yerleştirileceği bir HTML şablonu hazırlamaktır. Bu şablonu bir PHP değişkeni içerisinde tutabilir veya ayrı bir dosya olarak saklayıp file_get_contents() fonksiyonu ile okuyabilirsiniz.

Aşağıdaki örnekte, basit bir fatura yapısı bulunmaktadır. Tasarımda CSS kullanırken dikkat etmeniz gereken en önemli nokta, Dompdf'in modern CSS3 özelliklerinin tamamını desteklemeyebileceğidir; bu nedenle tablo (table) yapısını kullanmak en güvenli yöntemdir.

$html = '

    body { font-family: DejaVu Sans, sans-serif; }
    .fatura-tablosu { width: 100%; border-collapse: collapse; }
    .fatura-tablosu th, .fatura-tablosu td { border: 1px solid #ddd; padding: 8px; }

Fatura #{{fatura_no}}
Müşteri: {{musteri_adi}}

    

        
Ürün Adı
Fiyat
    
    

        
{{urun_adi}}
{{fiyat}} TL
    
';

PHP ile Verileri Dinamik Olarak Yerleştirme

HTML şablonunu oluşturduktan sonra, veritabanından gelen verileri bu şablona yerleştirmeniz gerekir. Bunun için str_replace() fonksiyonunu kullanarak şablon içerisindeki yer tutucuları (placeholder) gerçek verilerle değiştirebiliriz.

$veriler = [
    '{{fatura_no}}' => '2026-001',
    '{{musteri_adi}}' => 'Ahmet Yılmaz',
    '{{urun_adi}}' => 'Yıllık Yazılım Lisansı',
    '{{fiyat}}' => '1500.00'
];

$html_cikti = str_replace(array_keys($veriler), array_values($veriler), $html);

Bu yöntem, küçük ölçekli projeler için oldukça hızlıdır. Ancak daha karmaşık fatura yapıları için Twig veya Blade gibi bir şablon motoru kullanmanız, kodun okunabilirliğini ve yönetilebilirliğini artıracaktır.

Dompdf Kullanarak PDF Dosyasını Oluşturma

Verileri hazırladığımıza göre, artık bu HTML içeriğini PDF'e dönüştürme aşamasına geçebiliriz. Dompdf sınıfını kullanarak belgeyi oluşturup tarayıcıya indirme komutu göndereceğiz.

use Dompdf\Dompdf;

$dompdf = new Dompdf();
$dompdf->loadHtml($html_cikti);
$dompdf->setPaper('A4', 'portrait');
$dompdf->render();

// PDF'i tarayıcıya indirtmek için
$dompdf->stream("fatura_2026_001.pdf", ["Attachment" => true]);

stream() fonksiyonu, üretilen PDF dosyasını doğrudan kullanıcıya sunar. Eğer dosyayı sunucuda bir klasöre kaydetmek isterseniz, $dompdf->output() fonksiyonunu kullanarak dosya içeriğini alıp file_put_contents() ile kaydedebilirsiniz.

PDF Oluşturma Yöntemlerinin Karşılaştırılması

Güvenlik ve Performans İpuçları

Kritik Uyarı: PDF oluştururken kullanıcıdan gelen verileri asla doğrudan HTML şablonuna dahil etmeyin. XSS (Cross-Site Scripting) saldırılarına karşı verileri mutlaka htmlspecialchars() fonksiyonu ile temizleyin. Ayrıca, büyük boyutlu faturalar oluştururken bellek (memory) limitlerini kontrol edin.

Performans için, PDF oluşturma işlemini bir arka plan kuyruk sistemi (queue) ile yönetmek, kullanıcıyı bekletmemek adına en iyi uygulamadır. Özellikle toplu fatura kesme işlemlerinde bu yöntem sunucu yükünü dengeler.

Sıkça Sorulan Sorular

Dompdf ile Türkçe karakter sorunu nasıl çözülür?

Dompdf'in varsayılan fontları Türkçe karakterleri desteklemeyebilir. Şablonunuzda body { font-family: DejaVu Sans; } kullanarak bu sorunu kolayca aşabilirsiniz.

PDF dosyasını sunucuda nasıl saklarım?

$dompdf->output() fonksiyonundan dönen veriyi file_put_contents('faturalar/fatura_1.pdf', $pdf_icerigi) şeklinde kaydedebilirsiniz.

Faturaya nasıl logo ekleyebilirim?

Resimleri

PDF dosyasının boyutunu nasıl küçültebilirim?

Resimlerin çözünürlüklerini optimize edin ve gereksiz CSS sınıflarını şablonunuzdan temizleyin.

Aynı anda birden fazla fatura oluşturulabilir mi?

Evet, bir döngü içerisinde her bir fatura için ayrı bir Dompdf nesnesi oluşturarak toplu PDF üretimi yapabilirsiniz.

PDF Faturalara QR Kod Entegrasyonu ile Doğrulama

Modern e-fatura sistemlerinde, faturanın orijinalliğini doğrulamak için QR kod kullanımı standart hale gelmiştir. Dompdf içerisinde bir QR kod oluşturmak için phpqrcode gibi popüler kütüphaneleri kullanabilir ve oluşturulan görseli base64 formatında HTML şablonunuza gömebilirsiniz.

Aşağıdaki örnek, bir fatura verisini QR koda dönüştürüp PDF içine nasıl yerleştireceğinizi göstermektedir:

// QR kod kütüphanesini dahil edin
include 'phpqrcode/qrlib.php';

// Fatura verisini bir string haline getirin
$faturaVerisi = "Fatura No: INV-2023-001 | Tutar: 1500 TL | Tarih: 2023-10-27";

// QR kodu geçici bir dosyaya kaydedin
$tempFile = 'temp_qr.png';
QRcode::png($faturaVerisi, $tempFile, QR_ECLEVEL_L, 4);

// Görseli base64 formatına çevirerek HTML içine gömün
$type = pathinfo($tempFile, PATHINFO_EXTENSION);
$data = file_get_contents($tempFile);
$base64 = 'data:image/' . $type . ';base64,' . base64_encode($data);

$html = '
';
// Bu html değişkenini Dompdf loadHtml() metoduna gönderin

PDF Oluşturma Süreçlerinde Hata Ayıklama (Debugging)

PDF üretiminde en sık karşılaşılan sorunlar, CSS'in PDF motoru tarafından desteklenmemesi veya PHP bellek limitlerinin aşılmasıdır. Hata ayıklama sürecini hızlandırmak için şu adımları izleyebilirsiniz:

• Hata Raporlamayı Açın: Geliştirme aşamasında error_reporting(E_ALL); komutunu kullanarak gizli hataları görün.
• HTML'i Tarayıcıda Test Edin: PDF oluşturmadan önce şablonunuzu doğrudan bir HTML dosyası olarak tarayıcıda açın. Eğer tarayıcıda düzgün görünmüyorsa, PDF çıktısında da düzgün görünmeyecektir.
• Bellek Limitlerini Kontrol Edin: Çok sayfalı veya yüksek çözünürlüklü görseller içeren faturalarda ini_set('memory_limit', '512M'); komutu ile bellek limitini geçici olarak artırın.
• Dompdf Debug Modu: Dompdf'in kendi hata ayıklama modunu aktif etmek için define("DOMPDF_ENABLE_DEBUG", true); sabitini kullanabilirsiniz.

Özellikle karmaşık tablolarda, table-layout: fixed; CSS özelliğini kullanmak, PDF motorunun tablo genişliklerini hesaplarken yaşadığı performans sorunlarını minimize edecektir.

Alternatif Kütüphane: Snappy (wkhtmltopdf)

Dompdf, saf PHP ile yazıldığı için kurulumu kolaydır ancak çok karmaşık CSS3 özelliklerini veya modern JavaScript tabanlı grafik kütüphanelerini (Charts.js vb.) PDF'e dönüştürmekte zorlanabilir. Eğer faturanızda yoğun grafikler veya karmaşık düzenler varsa, wkhtmltopdf tabanlı Snappy kütüphanesini tercih edebilirsiniz.

Snappy, WebKit motorunu kullandığı için tarayıcı uyumluluğu çok daha yüksektir. Kurulumu için sunucunuza wkhtmltopdf binary dosyasını yüklemeniz gerekir:

use Knp\Snappy\Pdf;

$snappy = new Pdf('/usr/local/bin/wkhtmltopdf');
$snappy->generateFromHtml('
Fatura Başlığı
', 'fatura.pdf');

Bu yöntem, özellikle yüksek kaliteli baskı çıktısı almanız gereken durumlarda Dompdf'e göre daha keskin bir görsel sonuç sağlar.

Sonuç

PHP ile dinamik PDF fatura oluşturma süreci, doğru kütüphane seçimi ve temiz bir HTML şablonu ile oldukça verimli bir hale getirilebilir. Dompdf, başlangıç seviyesinden orta seviyeye kadar olan projeler için ideal bir çözümdür. Bir sonraki adım olarak, faturalarınıza QR kod eklemeyi veya dijital imza süreçlerini entegre etmeyi deneyerek sisteminizi daha profesyonel bir seviyeye taşıyabilirsiniz. Başarılı kodlamalar dilerim.

Yasal Sorumluluk Reddi: Bu rehber yazılım geliştirme eğitimi amaçlıdır. Finansal verilerin işlenmesi, vergi mevzuatı veya faturalandırma süreçleri ile ilgili yasal yükümlülükleriniz için bir mali müşavir veya hukuk uzmanına danışmanız tavsiye edilir.