İçindekiler

  1. Giriş

  2. Dolibarr'da PDF Faturalama Nasıl Çalışır?

  3. Önemli PDF Oluşturma Motorları: TCPDF ve DOMPDF

  4. PDF Görüntüleme Hatalarının Genel Belirtileri

  5. PDF Faturalama Sorunlarının Arkasındaki Kök Nedenler

  6. Adım Adım Tanı İş Akışı

  7. Düzeltme #1: PDF Şablon Hatalarını Onarma

  8. Düzeltme #2: Yazı Tipi Uyumluluğunu Yönetme

  9. Düzeltme #3: PDF Oluşturma için PHP Yapılandırmasını Ayarlama

  10. Düzeltme #4: Dosya İzni ve Erişim Sorunlarını Çözme

  11. Düzeltme #5: Doğru Çıktı Yöntemini Kullanma (Tarayıcı, İndirme, Depolama)

  12. Özel Şablonlar: Kırılmayı Önlemek İçin En İyi Uygulamalar

  13. Çok dilli ve RTL (Arapça, İbranice) PDF Çıktısı için İpuçları

  14. Son Düşüncelerimiz

1. Giriş

Dolibarr ERP & CRM, faturalama ve ödemelerden stok yönetimine, CRM'e, muhasebeye ve proje takibine kadar uzanan operasyonları kolaylaştıran yaygın olarak benimsenen açık kaynaklı bir iş platformudur. En önemli özelliklerinden biri—özellikle ticari operasyonlar için—üretim yeteneğidir PDF faturaları ve diğer belgeleri otomatik olarak.

Ancak birçok kullanıcı can sıkıcı bir sorunla karşılaşıyor: faturaları düzgün görüntülenmiyor, hiç oluşturulmuyor veya bozuk veya okunamayan PDF'lerle sonuçlanıyor. İster kendi sunucunuzu barındırın, ister bulut tabanlı bir Dolibarr örneği kullanın, bu sorunlar faturalama iş akışlarını bozabilir ve şirketinizin profesyonel imajına zarar verebilir.

Bu kılavuz şunları açıklıyor: PDF faturalarının Dolibarr'da neden doğru şekilde işlenemediği, temel PDF oluşturma işleminin nasıl çalıştığı ve bu sorunları nasıl hızlı ve kalıcı bir şekilde teşhis edip düzeltebileceğiniz.

2. Dolibarr'da PDF Faturalama Nasıl Çalışır?

Dolibarr’da (fatura, teklif, sipariş vb. için) “PDF Oluştur”a tıkladığınızda sistem:

  1. Kullanır PHP tabanlı şablon (PDF modeli olarak bilinir)

  2. Dinamik değişkenleri doldurur (müşteri adı, ürün detayları, toplam tutar, vb.)

  3. Bu içeriği şu kişiye gönderir: PDF motoru (TCPDF veya DOMPDF)

  4. Sonucu şu şekilde çıktı olarak verir:

    • Hemen indirin

    • Tarayıcı ekranı

    • Dosya depolama /documents/

PDF üretimi tamamen sunucu tarafında gerçekleştirilir, bu da ortamın (PHP sürümü, bellek ayarları, yazı tipi desteği) başarıda veya başarısızlıkta kritik bir rol oynadığı anlamına gelir.

3. Temel PDF Oluşturma Motorları: TCPDF ve DOMPDF

Dolibarr iki temel PDF oluşturma motorunu destekler:

TCPDF (eski sürümlerdeki varsayılan motor)

  • Eski Dolibarr sürümlerinde yaygın olarak kullanılır

  • Hızlı ve hafif

  • UTF-8 ve temel görüntü oluşturmayı destekler

  • CSS veya gelişmiş düzenler için yetersiz destek

DOMPDF (sonraki sürümlerde tanıtıldı)

  • Daha modern ve esnek

  • HTML5/CSS3 düzenini destekler

  • Daha fazla bellek ve daha ağır sistem kaynakları gerektirir

  • Özel tasarımlar ve karmaşık belgeler için daha iyi

Faturalarınız boş, bozuk veya hizasızsa, sorun şunlarla ilgili olabilir: motor sınırlamaları, yanlış yapılandırma veya kaynak kısıtlamaları.

4. PDF Görüntüleme Hatalarının Genel Belirtileri

Kullanıcılar fatura oluştururken genellikle şu sorunları bildiriyorlar:

  • İçeriği olmayan boş PDF

  • Eksik sunum (eksik tablolar, fiyatlar, müşteri bilgileri)

  • Yanlış hizalanmış metin veya düzen kaymaları

  • PDF indiriliyor ancak açılmıyor

  • Şu tür hata mesajları:

    • TCPDF ERROR: Some data has already been output

    • DOMPDF Fatal error: Uncaught exception

  • PDF doğru görünüyor ancak yanlış dil veya bozuk karakterler gösteriyor

Bu belirtiler şunu gösteriyor: farklı temel nedenlerSunucu kurulum sorunlarından hatalı şablon koduna veya eksik yazı tiplerine kadar uzanan sorunlar.

5. PDF Faturalama Sorunlarının Arkasındaki Kök Nedenler

Dolibarr'da fatura PDF hatalarının en yaygın nedenleri şunlardır:

Sebeb olmak Açıklama
Bozuk veya güncelliğini yitirmiş PDF şablonu Özel PDF modellerinde sözdizimi sorunları veya mantık hataları
Uyumsuz PHP sürümü DOMPDF ve TCPDF'nin katı PHP gereksinimleri vardır
Eksik yazı tipleri veya Unicode desteği Latin olmayan karakterler çıktıyı bozuyor
Düşük PHP belleği veya yürütme sınırları Büyük faturalar kaynak tükenmesi nedeniyle gerçekleştirilemiyor
Yanlış izinler Dolibarr yazamıyor /documents/ veya şablonlara erişin
Çıktı başlıkları zaten gönderildi Erken yankı veya boşluk nedeniyle düzgün dosya oluşturulmasını engeller
Yanlış dosya yolu yapılandırması Varolmayan veya kullanım dışı bırakılmış klasörlere işaret eder
Uygunsuz sunucu kodlaması veya yerel ayarlar Çok dilli PDF oluşturmayı bozar

Bu sorunların her biri çözüm için farklı bir yaklaşımı gerektirmektedir.

6. Adım Adım Tanılama İş Akışı

Düzeltmeleri uygulamadan önce, şu yapılandırılmış tanılama rutinini izleyin:

1. Adım: Geliştirici Modunu Etkinleştirin

In conf.php, geliştirici modunu etkinleştir:

php

define('DOL_DEVELOPER_MODE', 1);

Bu, PDF oluşturma hata ayıklama çıktısını görüntüler.

Adım 2: Sorunu Yeniden Oluşturun

  • Farklı fatura modellerini deneyin (örn. crabe, azur, rouget)

  • Küçük ve büyük faturalar için PDF'ler oluşturun

  • Hem indirme hem de önizleme işlemlerini deneyin

Adım 3: Günlükleri Kontrol Edin

  • PHP günlükleri (/var/log/php/error.log)

  • Apache/Nginx günlükleri (/var/log/apache2/error.log)

  • Dolibarr'ın dahili günlük dosyası (yapılandırılmışsa)

Adım 4: Şablon Kaynak Kodunu Kontrol Edin

  • MyCAD'de yazılım Güncelleme ye git /dolibarr/core/modules/facture/doc/

  • Sözdizimi sorunları, kapatılmamış etiketler veya kullanım dışı bırakılmış işlevler açısından PHP kodunu inceleyin

7. Düzeltme #1: PDF Şablon Hatalarını Onarma

PDF modelleri (örneğin, pdf_crabe.modules.php) PHP'de yazılmıştır. Yanlış yerleştirilmiş tek bir karakter bile çıktıyı bozabilir.

Kontrol Listesi:

  • Sağlamak <?php etiketlerin ardından boşluklar gelmez

  • HTML veya metin çıktısı yok önce başlıklar ayarlandı

  • Kazara değil echo or print mantık bölümlerindeki çağrılar

  • gibi değişkenler $this->emetteur düzgün bir şekilde başlatılmalıdır

İpucu: Önce Varsayılan Şablonlarla Test Edin

Dolibarr'ın varsayılanına geç crabe model. Eğer bu işe yararsa, sorun özel şablonunuzdur.

8. Düzeltme #2: Yazı Tipi Uyumluluğunu Yönetme

PDF motorlarının karakterleri doğru şekilde görüntüleyebilmesi için uygun yazı tipine ihtiyacı vardır.

Font Sorunlarının Belirtileri:

  • Arapça, Çince veya Kiril metinleri görüntülenmiyor

  • İsimlerin veya adreslerin olması gereken yerlerde boş alanlar

  • PDF harfler yerine “????” görüntülüyor

Çözümler:

  • Değiştirmek UTF-8 uyumlu yazı tipleri DejaVu Sans veya FreeSerif gibi

  • DOMPDF için, yazı tiplerini elle yükleyin load_font.php yarar

  • PDF çıktısına gömülmeyen sistem yazı tiplerinden kaçının

Dolibarr'da yazı tipi ayarlarını şablon başına özelleştirebilirsiniz.

9. Düzeltme #3: PDF Oluşturma için PHP Yapılandırmasını Ayarlama

Özellikle DOMPDF yeterli sunucu kaynaklarına ihtiyaç duyar.

Güncelle php.ini:

ini

memory_limit = 512M max_execution_time = 120 upload_max_filesize = 20M post_max_size = 25M

Değişikliklerden sonra Apache/Nginx veya PHP-FPM'i yeniden başlatın.

Uzantıları Doğrula

Aşağıdaki PHP uzantılarının etkin olduğundan emin olun:

  • mbstring

  • gd

  • dom

  • fileinfo

  • intl (dil/yerel ayar desteği için)

kullanın:

darbe

php -m | grep gd

10. Düzeltme #4: Dosya İzni ve Erişim Sorunlarını Çözme

Eğer Dolibarr yapamazsa şuraya yaz: /documents/ dosya, PDF oluşturma sessizce başarısız oluyor.

İzinleri Düzeltmek İçin Komutlar:

darbe

chown -R www-data:www-data /var/www/dolibarr/documents chmod -R 755 /var/www/dolibarr/documents

değiştirmek www-data web sunucusu kullanıcınızla.

Faturalar için alt dizinleri sağlayın (/documents/facture/) mevcut.

11. Düzeltme #5: Doğru Çıktı Yöntemini Kullanma (Tarayıcı, İndirme, Depolama)

Dolibarr, PDF faturaları oluştururken farklı çıktı davranışlarına izin verir:

  • Tarayıcıda görüntüle (Çizgide)

  • İndirme istemi

  • Doğrudan kaydet /documents/ rehber

Faturalar bir yöntemde doğru şekilde görüntülenmiyorsa ancak başka bir yöntemde çalışıyorsa, sorun aşağıdakilerden kaynaklanıyor olabilir: HTTP başlıkları veya tarayıcı uyumluluğu.

Öneriler:

  • Fatura sayfasından tüm çıktı yöntemlerini test edin

  • Başlıklardan önce herhangi bir HTML çıktısı (hata ayıklama bilgisi gibi) göndermekten kaçının

  • Çakışma olup olmadığını kontrol edin Content-Type or Content-Disposition başlıkları

  • PDF oluşturmayı engelleyebilecek tarayıcı uzantılarını devre dışı bırakın

Bazı durumlarda, satır içi görüntülemeden indirmeye geçmek "boş ekran" sorunlarını çözer.

12. Özel Şablonlar: Kırılmayı Önlemek İçin En İyi Uygulamalar

Dolibarr'da faturalar için özel bir PDF modeli oluşturmak yaygındır, ancak aşağıdakilerle olası uyumluluk riskleri doğurur:

  • PHP sürüm yükseltmeleri

  • PDF motor değişiklikleri

  • Dolibarr çekirdek güncellemeleri

Gelecekte sorun yaşamamak için:

12.1 Resmi Şablon İskeletini Kullanın

Mevcut bir şablonu kullanın (örneğin crabe) başlangıç ​​noktası olarak kullanın. Dolibarr'ın iç yapısına sadık kalın:

  • Tanımlama $object doğru bir şekilde (genellikle bir Facture sınıf örneği)

  • Tablo oluşturma için dahili yardımcı yöntemleri kullanın

  • Sabit kodlanmış düzen konumlarından kaçının; göreceli konumlandırmayı kullanın

12.2 Tüm Çıktıları Temizle

Özel karakterler içerebilen veya kodlamayı bozabilen kaçış dizeleri:

php

$this->pdf->MultiCell(..., dol_htmlentities($line->description), ...)

12.3 Geliştirici Araçlarıyla Doğrulama

Özel mantık kullanıyorsanız (örneğin toplamlar, indirimler), sonuçları Dolibarr'ın yerleşik PDF'si ve ekran görüntüsüyle doğrulayın.

12.4 Şablonların Sürüm Kontrolünü Sağlayın

Özel şablonları Git'te saklayın. Bu size şunları sağlar:

  • Bozuk sürümleri geri al

  • Uyumluluk değişikliklerini zaman içinde takip edin

  • Dolibarr yükseltmeleri arasında değişiklikleri kolayca birleştirin

13. Çok dilli ve RTL (Arapça, İbranice) PDF Çıktısı için İpuçları

Çok dilli veya sağdan sola PDF'ler oluşturmak ekstra özen gerektirir.

13.1 Doğru Yerel Ayarları Ayarlayın

PDF oluşturmadan önce Dolibarr'ın kullanıcı/istemcinin diline ayarlandığından emin olun:

php

$langs->setDefaultLang('ar_EG');

Bazı durumlarda, karakter setini zorlamanız gerekebilir:

php

header('Content-Type: application/pdf; charset=UTF-8');

13.2 RTL Uyumlu Yazı Tiplerini Kullanın

Yazı tipleri gibi Amiri, Noto Nesih Arapçaya da DejaVu Sans RTL betiklerini destekler.

13.3 DOMPDF'de RTL'yi Etkinleştir

DOMPDF, yalnızca açıkça yapılandırıldığında RTL'yi destekler:

php

$this->pdf->setRTL(true);

Ancak destek değişebilir. TCPDF, RTL betikleri için genellikle daha güvenilirdir, ancak tasarımda daha az esnektir.

13.4 Hizalama Ayarları Olmadan LTR/RTL'yi Karıştırmaktan Kaçının

Tablolarda, hizalama özelliklerini her zaman açıkça ayarlayın. Örnek:

php

$this->pdf->MultiCell(..., 'Client Name:', 0, 'R'); $this->pdf->MultiCell(..., $client_name, 0, 'L');

14. Son Düşünceler

Dolibarr'da profesyonel PDF faturaları oluşturmak sorunsuz bir deneyim olmalıdır; ancak şablonlar bozulduğunda, sunucu ayarları çakıştığında veya içerik oluşturulamadığında kolayca hayal kırıklığına uğrayabilirsiniz.

Sağlam PDF çıktısı sağlamak için son kontrol listesi:

✅Kullanım resmi şablonlar özel çalışmalar için bir temel olarak
✅ PHP ve Dolibarr sürümlerinizi uyumlu tutun modül uyumluluğu ile
✅ Sağlayın yazı tipi kapsamı kullandığınız her dil için
✅ Doğru ayarlayın izinleri üzerinde /documents/ rehber
✅ Doğrula şablon sözdizimi, erken çıktıyı önleyin
✅ Düzenli olarak özel şablonları test edin Dolibarr yükseltmelerinden sonra
✅ Çok dilli veya RTL ise: gerçek verilerde yazı tipi + düzen davranışını doğrulayın
✅Kullanım günlükler ve geliştirici modu sessiz hataları izlemek

Küçük bir yapılandırma hatası veya güncel olmayan bir şablon tüm faturalama iş akışınızı bozabilir. Ancak bu kılavuzda ayrıntılı olarak açıklanan tanılama çerçevesi ve düzeltmelerle Dolibarr'da PDF ile ilgili sorunları gidermek ve önlemek için gereken her şeye sahip olacaksınız.

Bu en iyi uygulamaları uygulayarak fatura PDF'lerinizin net, güvenilir, profesyonel ve tam işlevsel—Dolibarr veya PHP'nin hangi sürümünü kullandığınızın bir önemi yok.