Table of Contents

  1. Introduction

  2. Overview of Dolibarr's PDF Generation System

  3. Default Document Models in Dolibarr

  4. Locating and Understanding PDF Template Files

  5. How PDF Generation Works in Dolibarr

  6. Selecting a Default PDF Model

  7. Adding Your Company Logo and Branding

  8. Customizing Headers and Footers

  9. Editing the Layout of PDF Elements

  10. Customizing Font Styles, Sizes, and Colors

  11. Modifying Table Structures for Products and Services

  12. Showing or Hiding Specific Fields

  13. Adding Custom Fields to PDF Templates

  14. Localization and Language Considerations

  15. PDF Templates and Module Integration

  16. Creating a New PDF Model from Scratch

  17. Best Practices for Upgrading Without Losing Custom PDFs

  18. Testing and Debugging PDF Output

  19. Performance Considerations in Large Documents

  20. Conclusion

1. Introduction

Dolibarr’s PDF document generator is one of its most essential features. Whether you’re printing invoices, proposals, orders, or delivery notes, these documents often serve as official communication with clients, suppliers, and partners. This guide details how to customize Dolibarr’s PDF documents to reflect your branding, business logic, and layout preferences.

2. Overview of Dolibarr's PDF Generation System

Dolibarr uses PHP-based PDF templates to create documents. These templates are PHP files located in specific directories depending on the document type (e.g., invoices, orders). Dolibarr uses TCPDF, a widely used open-source PHP library, to render these PDFs.

Each module (like invoices or proposals) has its own PDF generation logic and template files.

3. Default Document Models in Dolibarr

Each type of document offers several standard models:

  • Invoices: crabe, azur, fraise

  • Proposals: elyse, azur

  • Orders: einstein, caracole

  • Shipments: rouget, expedition_lettre

These models can be selected from the configuration of each module and serve as starting points for customization.

4. Locating and Understanding PDF Template Files

Template files are stored in:

/htdocs/core/modules/<module>/doc/

For example, invoice templates are found in:

/htdocs/core/modules/facture/doc/

Each model corresponds to a .php file, e.g., pdf_crabe.modules.php. These files define layout, header/footer logic, and how data is rendered.

5. How PDF Generation Works in Dolibarr

When generating a PDF:

  1. Dolibarr loads the selected template class

  2. Retrieves business data (invoice, proposal, etc.)

  3. Uses TCPDF to write content line-by-line

  4. Saves the output to the /documents/ folder

The entire process is triggered when clicking the Generate PDF button inside a document.

6. Selecting a Default PDF Model

  1. Go to Setup > Modules > [Module Name]

  2. Scroll to the PDF Templates section

  3. Select the preferred model as the default

  4. Optionally disable others to prevent users from switching

This sets the layout used for all generated documents of that type.

7. Adding Your Company Logo and Branding

Logos are managed from: Setup > Company/Organization

To add a custom logo:

  1. Upload a logo image (JPEG or PNG preferred)

  2. Ensure it's placed in /logos/

  3. Templates like pdf_crabe will automatically embed it

For more control, edit the write_file() method in the template file to reposition or resize the logo.

8. Customizing Headers and Footers

Headers typically include:

  • Company name

  • Address

  • Document title

  • Reference number

Footers may contain:

  • Page numbers

  • Legal information

  • Terms and conditions

These can be customized in the template’s pdf->SetHeader() and pdf->SetFooter() logic or directly within write_file().

9. Editing the Layout of PDF Elements

You can adjust:

  • Margins and paddings

  • Font styles for titles, tables, and notes

  • Spacing between sections

  • Image placements

Use TCPDF methods like SetXY(), MultiCell(), and Line() to position and format content.

10. Customizing Font Styles, Sizes, and Colors

Dolibarr uses TCPDF’s style engine. Examples:

$pdf->SetFont('dejavusans', 'B', 10);
$pdf->SetTextColor(0, 0, 0);
$pdf->SetFillColor(230, 230, 230);

You can switch fonts (DejaVu, Courier, Helvetica) and apply bold/italic/underline as needed.

11. Modifying Table Structures for Products and Services

The main product table includes:

  • Description

  • Quantity

  • Unit price

  • Total

You can:

  • Change column order

  • Add/remove columns (e.g., SKU, supplier info)

  • Format currency display

Locate the loop that processes $object->lines[] in the template file and adjust accordingly.

12. Showing or Hiding Specific Fields

To hide/display fields:

  • Use configuration constants (set via Setup > Other Setup)

  • Add conditional logic in PHP, e.g.:

if (!empty($line->ref)) {
    $pdf->MultiCell(...);
}

You can also check user permissions or document types to conditionally render content.

13. Adding Custom Fields to PDF Templates

If you’ve added extra fields:

  1. Ensure they’re enabled and filled in the UI

  2. Access them via $object->array_options['options_fieldname']

  3. Format and insert using MultiCell() or other TCPDF functions

Custom fields work for third parties, products, and most document lines.

14. Localization and Language Considerations

PDFs respect Dolibarr’s language settings. If generating multilingual documents:

  • Set language in $outputlangs before writing content

  • Use load_langs('bills') or similar

Ensure UTF-8 encoding and fonts that support special characters.

15. PDF Templates and Module Integration

Some modules like Contracts or Projects have their own templates. If integrating data from other modules:

  • Extend the template logic to query extra fields

  • Use hooks or override core templates if necessary

Always keep cross-module dependencies documented.

16. Creating a New PDF Model from Scratch

  1. Copy an existing model (e.g., pdf_crabe.modules.php)

  2. Rename the file and class (e.g., pdf_mycustom.modules.php and pdf_mycustom)

  3. Register it by refreshing the module settings page

  4. Test and iterate

Keep your custom templates outside /core/ if possible to avoid overwrites during upgrades.

17. Best Practices for Upgrading Without Losing Custom PDFs

  • Never modify built-in templates directly

  • Store custom files in a /custom/ or backup directory

  • Use version control (Git) to track changes

  • Test after each Dolibarr upgrade

Also, document your customizations for team awareness.

18. Testing and Debugging PDF Output

To debug:

  • Use print_r() or var_dump() (log to file, not screen)

  • Check $object structure

  • Review TCPDF output for layout errors

Use sandbox invoices for safe testing.

19. Performance Considerations in Large Documents

For invoices with many lines:

  • Minimize image and font usage

  • Paginate properly

  • Avoid unnecessary loops

  • Use SetAutoPageBreak(true) to prevent cut-off content

Performance tuning helps avoid timeouts or memory errors.

20. Conclusion

Customizing Dolibarr's PDF documents allows businesses to produce professional, on-brand, and functional output. From minor layout tweaks to building entirely new templates, understanding how the PDF system works will give you full control over document generation.