DOCSEARCHbyAlgolia
Submit Docs

mPDF Documentation

repository·master·Indexed 19 days ago

https://github.com/mpdf/mpdf.github.io

User documentation for mPDF, a PHP library used to generate PDF files from HTML and CSS. It features support for UTF-8, RTL (Right-to-Left) languages, CJK characters, and PDF standards like PDF/A-1b, PDF/X-1a, and PDF/A-3. The docs cover configuration via the constructor for versions 7.0+, service container overrides for HTTP clients and content loaders in version 8.1+, CSS priority, and specific layout limitations regarding block-level elements in tables and fixed positioning.

Tokens
171.2K
Snippets
499
Records
806
Agent score
64%

What's inside mPDF

  1. Overview of mPDF

    master

    mPDF is a PHP library designed to generate PDF files from UTF-8 encoded HTML. It is built upon FPDF and HTML2FPDF, featuring enhancements for handling different languages and CSS styles.

    While it is highly capable for PHP-based environments, it is slower than its predecessors and produces larger files when using Unicode fonts. It is particularly useful for tasks requiring specific PDF features like color handling, barcodes, headers/footers, page numbering, and Tables of Contents (TOCs).

  2. Core features of mPDF

    master

    mPDF is a PHP library that converts HTML and CSS into PDF documents. Key capabilities include:

    • Language Support: Accepts UTF-8 encoded HTML and supports RTL (Right-to-Left) languages like Arabic and Hebrew, as well as CJK (Chinese, Japanese, Korean) characters.
    • Layout & Styling: Supports nested block-level elements (P, DIV) with CSS properties like margins, borders, padding, line-height, and background colors. It also supports floating and fixed-position elements, columns, and page orientation.
    • Advanced Typography: Features text justification, hyphenation, word/character spacing, text-indent (first line and hanging), and intelligent word-wrapping to avoid orphan punctuation.
    • Document Structure: Supports automatic Table of Contents, Indexes, Bookmarks, Page Numbering, and Page Headers/Footers (with left/center/right alignment and date/time insertion).
    • Tables: Supports nested, rotated, and autosized tables (which reduce font size to fit the page), as well as cell padding and borders.
    • Media & Graphics: Supports images in JPG, GIF, PNG, SVG, BMP, or WMF formats, and various barcode types (EAN13, UPC, Code 128, etc.).
    • PDF Standards & Security: Supports PDF/A-1b, PDF/X-1a, and PDF/A-3 (including ZUGFeRD invoices), as well as password protection and annotations.
    • Watermarks: Supports text or image watermarks with customizable transparency and angles.

  3. Supported Image Formats in mPDF

    master

    mPDF supports the following image formats:

    • GIF (including transparent GIFs)
    • PNG (including interlaced, transparent, and alpha channel support)
    • JPG
    • WMF (visible in IE or PDF)
    • SVG (visible in some browsers like Firefox and PDF)
    • BMP
    • WEBP (supported since v8.0.16; visible in browsers with WEBP support)
    • Dynamically generated images from PHP scripts

  6. Handle RTL and CJK languages in mPDF

    master

    mPDF provides specialized handling for complex character sets:

    • RTL (Right-to-Left): Automatically detects RTL characters. It transposes tables, lists, text justification, and table cell alignment, and performs full text reversal for RTL characters while maintaining the original order for non-RTL characters.
    • CJK (Chinese-Japanese-Korean): Supports CJK characters with automatic font substitution to ensure characters are rendered correctly.
    • Character Substitution: Can be configured to automatically replace characters that do not exist in the currently active font.

  7. Control watermark image placement and visibility

    master

    By default, watermark images are printed on top of the page contents.

    Placing images behind content

    You can set the watermarkImgBehind configuration setting to true to attempt to place the image behind page contents. Note: The image will be hidden by any background color specified, including table cells and the page background.

    Showing/Hiding watermarks

    Use the following variables to control visibility:

    • showWatermarkText: Specifies whether to show/print the watermark text.
    • showWatermarkImage: Specifies whether to show/print the watermark image.

    CSS Alternative

    As of mPDF 3.0, you can use the CSS background-image style on the <body> tag to create a watermark effect. However, this method does not support opacity/transparency. Unlike a true watermark (which is semi-transparent and printed over everything), a CSS background image will have text and tables written over the top of it.

  8. Configure conditional page breaks with the $type attribute

    master

    The $type attribute allows you to control how many pages are added based on whether the document is SINGLE-SIDED or DOUBLE-SIDED. This is particularly useful for ensuring new sections start on specific page types (ODD or EVEN).

    Behavior Table

    | $type | SINGLE-SIDED | DOUBLE-SIDED (Current: ODD) | DOUBLE-SIDED (Current: EVEN) | | :--- | :--- | :--- | :| | BLANK | 1 | 1 | 1 | | 'O' or 'ODD' | 0 | 0 | 1 | | 'E' or 'EVEN' | 0 | 1 | 0 | | 'NEXT-ODD' | 1 | 2 | 1 | | 'NEXT-EVEN' | 1 | 1 | 2 |

    Usage Scenarios

    • 'O' or 'ODD': In a double-sided document, if you are currently on an EVEN page, this will add 1 page to make the next page ODD. If you are already on an ODD page, it adds 0 pages.
    • 'NEXT-ODD': Ensures the next section starts on an ODD page. If you are on an ODD page, it adds 2 pages (an EVEN blank page and then the ODD page).
    <pagebreak type="NEXT-ODD" />

  9. How automatic font selection works in mPDF

    master

    mPDF (v6.0+) uses a two-stage process to handle multiple languages and scripts in a single document. Because it is difficult to determine a specific language from raw HTML, mPDF uses the Unicode script block as an intermediary step via the lang attribute.

    1. Stage 1: autoScriptToLang (\Mpdf\ScriptToLang class): Detects text runs based on their Unicode script block and wraps them in <span> tags with an appropriate lang attribute (e.g., und-Cyrl for undetermined Cyrillic).
    2. Stage 2: autoLangToFont (\Mpdf\LangToFont class): Uses the lang attribute generated in Stage 1 to select the correct font and apply OpenType Layout (OTL) features.

    Note: While powerful, these features increase processing time. If you have full control over your HTML, it is better to manually mark up text with lang attributes and use CSS :lang selectors. This allows OTL to use language-dependent substitutions more effectively than the 'undetermined' tags generated by automatic script detection.

    <!-- Example of the two-stage transformation -->
<!-- Input -->
English ру́сский язы́к پښتو

<!-- After autoScriptToLang -->
English <span lang="und-Cyrl">ру́сский язы́к</span> <span lang="ps">پښتو</span>

<!-- After autoLangToFont (Font selection applied) -->

  10. Use FPDF original functions in mPDF

    master

    While mPDF is primarily designed to support HTML input, it maintains compatibility with original FPDF functions. This allows you to write directly to the document using low-level commands.

    Important Limitations: When using these original FPDF functions instead of native mPDF functions:

    • Text may require manual encoding.
    • They do not automatically reverse RTL (Right-to-Left) text.
    • They do not convert HTML entities to characters.

    For better UTF-8 support and automatic handling of encoding and RTL, use the mPDF-specific WriteCell() or WriteText() functions instead.

  11. Use the HTML lang attribute for multi-lingual documents

    master

    The recommended method for handling multi-lingual documents in mPDF is using the HTML lang attribute. This attribute serves several purposes:

    1. OTL Feature Selection: When using OpenType Layout (OTL) tables in a font, mPDF uses the language from the lang attribute to select which OTL features to apply.
    2. CSS Styling: It allows you to target specific languages using the CSS :lang() selector.
    3. Automatic Mapping: It can be used in conjunction with autoLangToFont and autoScriptToLang settings.

    Use IETF tags for the lang attribute. These are case-insensitive in mPDF and follow the pattern: [2 or 3 letter language code][-4 letter script code][-2 letter region code] (e.g., en, zh-Hant, en-US).

  12. Support Vietnamese characters in mPDF

    master

    To render Vietnamese text correctly in mPDF, ensure your document uses Unicode characters. The Vietnamese alphabet is distributed across several Unicode ranges that mPDF supports, including:

    • Basic Latin: U+0000..U+007F
    • Latin-1 Supplement: U+0080..U+00FF (e.g., À, Á, Â, Ã, È, É, Ê, Ì, Í, Ò, Ó, Ô, Õ, Ù, Ú, Ý)
    • Latin Extended-A: U+0100..U+024F (e.g., Ă, ă, Đ, đ, Ĩ, ĩ, Ũ, ũ)
    • Latin Extended-B: Specific characters like Ơ, ơ, Ư, ư (U+01A0, U+01A1, U+01AF, U+01B0)
    • Latin Extended Additional: U+1E00..U+1EFF (e.g., Ạ, ạ, Ả, ả, Ấ, ấ, etc.)
    • Combining Diacritical Marks: U+0300..U+036F

    Additionally, the Vietnamese currency symbol đồng (₫, U+20AB) is supported.