UnicodeHowTo

Brian Sweeney edited this page Feb 2, 2016 · 7 revisions

A guide to enabling Unicode support in DOMPDF (with the CPDF backend)

To ensure maximum compatibility you should follow all of the following steps. Click through for additional details.

Detailed Instructions:

Ensure the MBString PHP extension is enabled

This extension is necessary for dompdf to parse Unicode/UTF-8 text correctly. dompdf relies heavily on the MBString family of functions for parsing text. Without these functions characters could be corrupted, words split randomly, and lines wrapped in the wrong place.

Installation instructions can be found in the PHP documentation.

Note: Version 0.6.0 included a basic compatibility layer for installations where MBString was unavailable. This compatibility layer is no longer provided as of version 0.7.0. If you require a compatibility layer try Patchwork UTF-8 for PHP.

Install dompdf 0.6.0 or greater

You will need dompdf 0.6.0 or greater because earlier releases do not support character encodings other than Windows ANSI. Find the latest release of dompdf on the releases page.

Configure dompdf for Unicode support

This requirements applies to dompdf 0.6.0 only. As of dompdf 0.7.0 Unicode support is always enabled.

For dompdf to handle Unicode characters correctly you must enable Unicode support in your configuration. Edit dompdf_config.inc.php or dompdf_config.custom.inc.php so that DOMPDF_UNICODE_ENABLED is true. Without enabling this setting your text will be re-encoded to Windows ANSI when inserted into the PDF and any characters that fall outside this encoding will be converted to question marks.

Load a font supporting your characters into DOMPDF

In order to display your text correctly the PDF needs access to a font that supports the characters used in the document. dompdf includes the DejaVu fonts, which support a wide range of characters. If the DejaVu fonts do not support your the characters in your document any TrueType font will work.

Note: dompdf currently supports only TrueType fonts. So when looking for a font make sure it comes in TrueType format.

There are currently two methods available for loading a font:

  • Use the load_font.php script included with DOMPDF
  • Use CSS @font-face rules to load a font at run-time
  • Use the font management page included in the admin site (v0.6.x only)

Use the load_font.php script

Note: The load_font.php script was distributed with dompdf 0.6.x and earlier. It was removed from the distribution as of version 0.7.0. Updated versions of the file are now maintained as part of the dompdf-utils project.

load_font.php relies on php-font-lib to extract the information dompdf needs to use a font. If you followed the dompdf installation instructions you should already have this library.

load_font.php is a command-line script, it can not be run through your web server. The script accepts the following parameters:

  1. the name of the font
  2. the path to the normal variant TTF file
  3. the path to the italic variant TTF file
  4. the path to the bold variant TTF file
  5. the path to the bold-italic variant TTF file

Run load_font.php without any parameters to see the help text.

> php load_font.php

Usage: load_font.php font_family [n_file [b_file] [i_file] [bi_file]]

...

All you need to successfully install a font is the normal variant.

As an example, say we have a font named Firefly located at /home/fonts. To install this font you would go into your dompdf installation directory and enter the following command:

> php load_font.php Firefly /home/fonts/firefly.ttf

which would produce the following output:

Unable to find bold face file.
Unable to find italic face file.
Unable to find bold_italic face file.
Copying /home/fonts/firefly.ttf to /home/dompdf/lib/fonts/firefly.ttf...
Generating .afm for /home/dompdf/fonts/firefly.ttf...
?
Finished - font files created

Use CSS @font-face rules to load a font at run-time

So long as the font you want to load is accessible to dompdf you can load it easily via CSS.

@font-face {
  font-family: 'Firefly';
  font-style: normal;
  font-weight: normal;
  src: url(http://example.com/fonts/firefly.ttf) format('truetype');
}

Use the font management page included in the admin site (v0.6.0 only)

This page can be found at dompdf/www/fonts.php. You must modify the admin username/password combo in your configuration before you can upload a new font.

The admin site is no longer distributed with dompdf as of version 0.7.0.

Create a compatible HTML document

For dompdf to correctly parse your document you must let it know what encoding is used. To do this place a meta tag in the head of your document that specifies the encoding. We recommend encoding documents to UTF-8 for greatest compatibility. However, you should be able to use other encodings so long as the computer where dompdf is installed supports the specified encoding.

<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

You should also ensure that your html editor is using the encoding you have specified. If, for example, you specify that your document is using UTF-8 but your editor is actually encoding your document in iso-8859-5, then there is a chance that the text of the document will be mangled. An exception to this rule is that entity-encoded characters should be accurately parsed regardless of the document encoding.

In an earlier example we loaded the Firefly font into our DOMPDF installation. Here is a sample document that uses that font:

<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
</head>
<body>
    <p style="font-family: firefly, DejaVu Sans, sans-serif;">献给母亲的爱</p>
</body>
</html>

When you style a block of text to display using a specific font that font must support all the characters in that block. Any character not supported will typically show up as an unfilled square. DOMPDF does not attempt to find a replacement font for unsupported characters.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.