mod_xml2enc - Apache HTTP Server Version 2.4









Modules | Directives | FAQ | Glossary | Sitemap
Apache HTTP Server Version 2.4



Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_xml2enc

Available Languages:  en  |
 fr 

Description:Enhanced charset/internationalisation support for libxml2-based
filter modules
Status:Base
Module Identifier:xml2enc_module
Source File:mod_xml2enc.c
Compatibility:Version 2.4 and later.  Available as a third-party module
for 2.2.x versions
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.

Topics

 Usage
 Programming API
 Detecting an Encoding
 Output Encoding
 Unsupported Encodings
Directives

 xml2EncAlias
 xml2EncDefault
 xml2StartParse

Bugfix checklisthttpd changelogKnown issuesReport a bugSee also

Comments


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:
    
        If the HTTP Content-Type header includes a
        charset parameter, that is used.
        If the data start with an XML Byte Order Mark (BOM) or an
        XML encoding declaration, that is used.
        If an encoding is declared in an HTML <META>
        element, that is used.
        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 Directive

Description:Recognise Aliases for encoding values
Syntax:xml2EncAlias charset alias [alias ...]
Context:server config
Status:Base
Module:mod_xml2enc

    This server-wide directive aliases one or more encoding to another
    encoding.  This enables encodings not recognised by libxml2 to be handled
    internally by libxml2's encoding support using the translation table for
    a recognised encoding.  This serves two purposes: to support character sets
    (or names) not recognised either by libxml2 or iconv, and to skip
    conversion for an encoding where it is known to be unnecessary.



xml2EncDefault Directive

Description:Sets a default encoding to assume when absolutely no information
can be automatically detected
Syntax:xml2EncDefault name
Context:server config, virtual host, directory, .htaccess
Status:Base
Module:mod_xml2enc

    If you are processing data with known encoding but no encoding
    information, you can set this default to help mod_xml2enc process
    the data correctly.  For example, to work with the default value
    of Latin1 (iso-8859-1) specified in HTTP/1.0, use:
    xml2EncDefault iso-8859-1




xml2StartParse Directive

Description:Advise the parser to skip leading junk.
Syntax:xml2StartParse element [element ...]
Context:server config, virtual host, directory, .htaccess
Status:Base
Module:mod_xml2enc

    Specify that the markup parser should start at the first instance
    of any of the elements specified.  This can be used as a workaround
    where a broken backend inserts leading junk that messes up the parser (example here).
    It should never be used for XML, nor well-formed HTML.




Available Languages:  en  |
 fr 

Copyright 2026 The Apache Software Foundation.Licensed under the Apache License, Version 2.0.
Modules | Directives | FAQ | Glossary | Sitemap