Unicode Usage Fill forms with multilingual text and encoding

Introduction

While all SetaPDF components accept UTF-8 values as their standard encoding the glyphs have to be converted to a font specific encoding to render them.

By default the SetaPDF-FormFiller component uses the pre-defined font in the PDF form to render a field appearance. Depending on the language it may be possible that a pre-defined font is not able to display a specific glyph. This manual will show possible workarounds for these situations. 

Using a Custom Font

The best an reliable way to add support for required languages is to use a TrueType font program which covers all needed glyphs. 

A font is represented by a font object that could be created in several ways. In any way we suggest to use a subset font either TrueType or Type0 to be as flexible as possible:

PHP
// allows you to use 255 different characters
$font = new SetaPDF_Core_Font_TrueType_Subset(
    $document,
    'DejaVuSansCondensed-Oblique.ttf'
);

// or

// allows you to use up 65000 different characters
$font = new SetaPDF_Core_Font_Type0_Subset(
    $document,
    'DejaVuSansCondensed-Oblique.ttf'
);

$field = $fields->get('Name');
$field->setAppearanceFont($font);
$field->setValue('Mr. Úmśęnłasdí');

An online-demo is available here.

If the form uses the same name for several field instances and you will call the setValue() method only of one of them, you have to set the appearance font in advance to all other field instances. 

Please notice that all font instance currently do not support scripts and languages which need pre-processing such as glyph substitution or glyph ordering (such as Arabic, Hebrew,...)  

If you need to use different font styles and you do not know which style is used in which form field, you can access the original font prior setting the new one: 

PHP
$font = $field->getAppearanceFont();
// all fonts which are created out of a PDF document are of the instance SetaPDF_Core_Font
if ($font instanceof SetaPDF_Core_Font) {
    $isBold = $font->isBold();
    $isItalic = $font->isItalic();
    $isMonospace = $font->isMonospace();
    $fontName = $font->getFontName();
}

Render Appearance by Reader

A simple solution to support  unicode values is to instruct the Reader application to re-render the form field appearances at opening time. This flag could be simply set with the setNeedAppearances() method: 

Description
public SetaPDF_FormFiller::setNeedAppearances (
[ boolean $needAppearances = true ]
): void

Set the NeedAppearances flag.

This flag indicates the viewer to re-render the form field appearances.

Parameters
$needAppearances : boolean

The NeedAppearances flag status

Whether this flag is set, can be checked with the isNeedAppearancesSet() method.

Sadly not all reader applications support this flag! So using a font subset would be a more reliable solution.