Choosing a configuration v7+

(mPDF ≥ 7.0)

In mPDF there are a number of ways to configure your set-up. There is often a trade-off between file size, processing speed, appearance (support for different fonts), and reliability (i.e. ensuring that text is always displayed, at least in some form).

Some of the things you can change are:

the mode used to call mPDF e.g. $mpdf = new \Mpdf\Mpdf(['mode' => 'c'])
other configuration variables set in other configuration keys: see mPDF Variables - Overview (many of those configuration variable can also be set at runtime on a ‘per-script’ basis)
font details in configuration keys (See class \Mpdf\Config\FontVariables)

Main choices

Some of the major considerations are:

whether to restrict the document to core non-embedded fonts
whether, or how, to subset embedded fonts
handling of languages which require special fonts, including automatic font selection and character substitution

1. Core non-embedded fonts

PDF files have certain standard fonts: Helvetica, Times and Courier in the win-1252 character set, and Zapfdingbats and Symbol character sets. These fonts should be available to any PDF reading program, and do not need to be embedded in the PDF document.

Advantages: Small file size, fast processing, small memory usage.

Disadvantages: Limited choice of fonts for appearance. Will not display characters which are not in the win-1252 Symbols, or Dingbats codepages (suitable for most Western European languages).

To use core fonts only, use 'c' for the mode configuration key:

<?php

$mpdf = new \Mpdf\Mpdf(['mode' => 'c']);

Note: due to encoding conversion, mPDF changes mb_internal_encoding() and mb_regex_encoding() internally when core fonts are being used. To restore original values, call $mpdf->cleanup() when you are done with generating the PDF.

2. Embedded Unicode fonts

The alternative (the default setup) uses TrueType Unicode fonts, and the only limitation of characters to display is determined by the font files themselves.

Subsetting fonts

Fonts with good coverage of all characters you may require can be very large. If you embed the whole font file in the PDF document, the file can become very large - especially if you use a number of fonts. mPDF can embed subsets of the fonts i.e. just including the characters used in the PDF document.

Advantages of subsetting: Manageable file size (typically between 20-200kB)

Disadvantages of subsetting: Increase in processing time and memory usage (not always), as mPDF has to rebuild font files for each document.

By default, mPDF will embed subsets of fonts if less than 30% of the characters contained in the font are used in the document; otherwise it will embed the whole font file. You can override this by changing the configurable variable $this->percentSubset

For backwards compatibility, you can use 's' in the mode configuration key to override the configuration settings and force subsetting of all fonts e.g.

<?php
$mpdf = new mPDF(['mode' => 's']);

Using core non-embedded fonts in a Unicode document

If your document uses Unicode fonts as above, you can force mPDF to use the core (non-embedded) PDF fonts in parts of the document by selecting the fontnames: 'chelvetica', 'ccourier' and 'ctimes' e.g.

<p style="font-family:chelvetica">This paragraph will use core fonts</p>

You could force mPDF to always use core fonts when Arial/Helvetica/Courier are specified, by editing the font translation configuration key fonttrans e.g.:

<?php
$this->fonttrans = array(
	'arial' => 'chelvetica',
	'helvetica' => 'chelvetica',
	'timesnewroman' => 'ctimes',
	'times' => 'ctimes',
	'couriernew' => 'ccourier',
	'courier' => 'ccourier',
);

3. Languages/Scripts which require special fonts

Most browsers / PC applications automatically select / substitute appropriate fonts when required. mPDF does not do this by default (additional processing resources required). there are two situations when you need to consider the method of font selection:

the text contains characters which are not covered by the initial font selected
the text contains complex script requiring special treatment i.e. OpenType layout (OTL)

The DejaVu fonts distributed with mPDF contain characters (glyphs) to display most Western and Eastern European languages, Cyrillic text, Baltic languages, Turkish, and Greek.

Languages which usually need special consideration are: CJK (chinese - japanese - korean) languages, Indic languages, Vietnamese, Thai, and Arabic languages. With these, you need to tell mPDF to select a suitable font.

There are several different methods to do this:

Write your HTML code to specify the exact fonts needed:

<p style="font-family: Garuda">เป็นมนุษย์สุดประเสริฐเลิศคุณค่า</p>
<p style="font-family: BIG5">仝娃阿哀愛挨姶</p>
<p style="font-family: sun-exta">仝娃阿哀愛挨姶</p>
<p style="font-family: 'XB Riyaz'">البرادعی البرادعی</p>

Write your HTML code using the lang attribute to define the language.

<p lang="th">เป็นมนุษย์สุดประเสริฐเลิศคุณค่า</p>
<p lang="zh-CN">仝娃阿哀愛挨姶</p>
<p lang="ar">البرادعی البرادعی</p>
<p lang="hi">पहला पन्ना</p>

This needs to be used in conjunction with either:

autoLangToFont
CSS stylesheet using the :lang selector

Use autoScriptToLang to mark up HTML text by inserting the lang attribute, based on the Unicode script block in question, and values in a Mpdf\Language\LanguageToFontInterface implementation.
```
<?php
$mpdf->autoScriptToLang = true;
```
As for (2) this needs to be used in conjunction with either:
- autoLangToFont
- CSS stylesheet using the :lang selector
When enabling autoScriptToLang and your primary language is not English you should set the appropriate baseScript so your primary font (set using the CSS property font-family) is not automatically overridden:
```
<?php
/* Set the base langage to Chinese */
$mpdf->baseScript = \Mpdf\Ucdn::SCRIPT_HAN;
```
If you want to control the fonts used for fallback languages you’ll need to extend the Mpdf\Language\LanguageToFont class and pass that class to the languageToFont configuration option when initializing mPDF (see option 4 in the Fonts in mPDF 7.x page).
Use $useSubstitutions to use character substitution. mPDF will inspect every character in the HTML code, and if the character is not represented in the specified font, it will try to substitute it from one of the fonts defined in backupSubsFont configuration key.
```
<?php
$this->backupSubsFont = ['dejavusanscondensed'];
```

Which method should I use?

Individually authored pages

If you are authoring a document in a common language which contains sections of text using special languages, the ideal method to use is (1) or (2).

Multilingual documents ‘on-the-fly’

If you are creating a PDF document from a page such as this web-page or a forum board which is likely to contain some special language text, and it is not possible to mark-up the special language text, you should use method (3).

If the document is mainly in a common language and may contain only occasional words or characters, the alternative is to use method (4) character substitution.

It is possible to use method (4) together with (1), (2) or (3), to ensure that all special characters are displayed.