Apache Module mod_xml2enc

Summary

This module provides enhanced internationalisation support for markup-aware filter modules such as mod_proxy_html. It can automatically detect the encoding of input data and ensure they are correctly processed by the libxml2 parser, including converting to Unicode (UTF-8) where necessary. It can also convert data to an encoding of choice after markup processing, and will ensure the correct charset value is set in the HTTP Content-Type header.

Usage

There are two usage scenarios: with modules programmed to work with mod_xml2enc, and with those that are not aware of it:

Filter modules enabled for mod_xml2enc

Modules such as mod_proxy_html version 3.1 and up use the xml2enc_charset optional function to retrieve the charset argument to pass to the libxml2 parser, and may use the xml2enc_filter optional function to postprocess to another encoding. Using mod_xml2enc with an enabled module, no configuration is necessary: the other module will configure mod_xml2enc for you (though you may still want to customise it using the configuration directives below).

Non-enabled modules

To use it with a libxml2-based module that isn't explicitly enabled for mod_xml2enc, you will have to configure the filter chain yourself. So to use it with a filter foo provided by a module mod_foo to improve the latter's i18n support with HTML and XML, you could use

FilterProvider iconv xml2enc Content-Type $text/html FilterProvider iconv xml2enc Content-Type $xml FilterProvider markup foo Content-Type $text/html FilterProvider markup foo Content-Type $xml FilterChain iconv markup

mod_foo will now support any character set supported by either (or both) of libxml2 or apr_xlate/iconv.

Programming API

Programmers writing libxml2-based filter modules are encouraged to enable them for mod_xml2enc, to provide strong i18n support for your users without reinventing the wheel. The programming API is exposed in mod_xml2enc.h, and a usage example is mod_proxy_html.

Detecting an Encoding

Unlike mod_charset_lite, mod_xml2enc is designed to work with data whose encoding cannot be known in advance and thus configured. It therefore uses 'sniffing' techniques to detect the encoding of HTTP data as follows:

1. If the HTTP Content-Type header includes a charset parameter, that is used.
2. If the data start with an XML Byte Order Mark (BOM) or an XML encoding declaration, that is used.
3. If an encoding is declared in an HTML <META> element, that is used.
4. If none of the above match, the default value set by xml2EncDefault is used.

The rules are applied in order. As soon as a match is found, it is used and detection is stopped.

Output Encoding

libxml2 always uses UTF-8 (Unicode) internally, and libxml2-based filter modules will output that by default. mod_xml2enc can change the output encoding through the API, but there is currently no way to configure that directly.

Changing the output encoding should (in theory, at least) never be necessary, and is not recommended due to the extra processing load on the server of an unnecessary conversion.

Unsupported Encodings

If you are working with encodings that are not supported by any of the conversion methods available on your platform, you can still alias them to a supported encoding using xml2EncAlias.

xml2EncAlias charset alias [alias ...]

xml2EncDefault name

xml2EncDefault iso-8859-1

xml2StartParse element [element ...]