Serveur Apache HTTP Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Modules

# Module Apache mod_xml2enc

Description: | Support avancé de l'internationalisation et des jeux de caractères pour les modules de filtrage basés sur libxml2
Statut: | Base
Identificateur de Module: | xml2enc_module
Fichier Source: | mod_xml2enc.c
Compatibilité: | Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.2.x

### Sommaire

Ce module fournit un support avancé de l'internationalisation pour les modules de filtrage supportant les balises (markup-aware) comme `mod_proxy_html`. Il est capable de détecter automatiquement l'encodage des données en entrée et de s'assurer qu'elle sont traitées correctement par l'interpréteur libxml2, y compris la conversion en Unicode (UTF-8) si nécessaire. Il peut aussi convertir les données dans l'encodage de votre choix après le traitement des balises, et s'assurera que le jeu de caractères approprié sera défini dans l'en-tête HTTP Content-Type.

### Sujets

- Utilisation
- API de programmation
- Détection et encodage
- Codage en sortie
- Codages non supportés

### Directives

### Traitement des bugs

- Journal des modifications de httpd
- Problèmes connus
- Signaler un bug

## Utilisation

Il existe deux scénarios d'utilisation : le cas des modules programmés pour travailler avec mod_xml2enc ; et les autres :

Modules de filtrages programmés pour mod_xml2enc

  Les modules comme `mod_proxy_html` versions 3.1 et supérieures utilisent la fonction optionnelle `xml2enc_charset` pour déterminer la valeur de l'argument "jeu de caractères" à transmettre à l'interpréteur libxml2, et disposent de la fonction optionnelle `xml2enc_filter` pour effectuer un encodage ultérieur éventuel. L'utilisation de mod_xml2enc avec un module préprogrammé à cet effet ne nécessite aucune configuration : ce dernier configurera mod_xml2enc pour vous (sachant que vous pouvez tout de même le personnaliser via les directives de configuration ci-dessous).

Modules de filtrages non programmés pour mod_xml2enc

  Pour utiliser mod_xml2enc avec un module basé sur libxml2 qui n'a pas été explicitement programmé pour mod_xml2enc, vous devrez configurer la chaîne de filtrage vous-même. Ainsi, pour utiliser mod_xml2enc avec un filtre foo fourni par un module mod_foo et pour améliorer le support i18n de ce dernier avec HTML et XML, vous pouvez utiliser les directives suivantes :

          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 supportera alors tout jeu de caractère supporté soit par libxml2, soit par apr_xlate/iconv, soit par les deux.

## API de programmation

Les programmeurs de modules de filtrage basés sur libxml2 sont encouragés à les préprogrammer pour mod_xml2enc, afin de fournir un support i18n solide aux utilisateurs sans avoir à réinventer la roue. L'API de programmation est décrite dans mod_xml2enc.h, et `mod_proxy_html` est un exemple de son utilisation.

## Détection et encodage

A la différence de `mod_charset_lite`, mod_xml2enc est conçu pour travailler avec des données dont l'encodage ne peut pas être connu, et donc configuré, à l'avance. Il utilise donc les techniques de 'reniflage' suivantes pour détecter le type d'encodage des données HTTP :

1. Si l'en-tête HTTP Content-Type contient un paramètre charset, c'est ce dernier qui sera utilisé.
2. Si les données commancent par une balise XML concernant l'ordre des octets (BOM) ou par une déclaration d'encodage XML, c'est celle-ci qui sera utilisée.
3. Si un type d'encodage est déclaré dans un élément HTML `<META>`, c'est ce dernier qui sera utilisé.
4. Si aucun des éléments précédents n'est trouvé, c'est la valeur par défaut définie par la directive `xml2EncDefault` qui sera utilisée.

Les conditions sont testées dans cet ordre . Dès qu'une règle s'applique, elle est utilisée et la détection est terminée.

## Codage en sortie

libxml2 utilise toujours UTF-8 (Unicode) en interne, et les modules de filtrage basés sur libxml2 utiliseront cet encodage en sortie par défaut. mod_xml2enc peut modifier l'encodage en sortie via l'API, mais il n'y a actuellement aucun moyen de le configurer directement.

La modification de l'encodage en sortie ne devrait (du moins en théorie) jamais être nécessaire, et est même déconseillée à cause de la charge de traitement supplémentaire imposée au serveur par une conversion non nécessaire.

## Codages non supportés

Si vous travaillez avec des encodages non supportés par aucune des méthodes de conversion disponibles sur votre plateforme, vous pouvez tout de même leur associer un alias vers un code supporté via la directive `xml2EncAlias`.

## Directive xml2EncAlias

Description: | Définit des alias pour les valeurs d'encodage
Syntaxe: | `xml2EncAlias jeu-de-caractères alias [alias ...]`
Contexte: | configuration du serveur
Statut: | Base
Module: | mod_xml2enc

Cette directive de niveau serveur permet de définir un ou plusieurs alias pour un encodage. Elle permet au support d'encodage de libxml2 de traiter en interne des encodages non reconnus par libxml2 en utilisant la table de conversion pour un encodage reconnu. Elle permet d'atteindre deux objectifs : supporter des jeux (ou noms) de caractères non reconnus par libxml2 ou iconv, et éviter une conversion pour un encodage lorsque cela n'est pas nécessaire.

## Directive xml2EncDefault

Description: | Définit un encodage par défaut à utiliser lorsqu'aucune information ne peut être automatiquement détectée
Syntaxe: | `xml2EncDefault nom`
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Base
Module: | mod_xml2enc
Compatibilité: | Disponible depuis la version 2.4.0 du serveur HTTP Apache ; disponible depuis un module tiers dans les versions antérieures.

Si vous traitez des données dont l'encodage est connu, mais ne contenant aucune information à propos de ce dernier, vous pouvez définir une valeur par défaut afin d'aider mod_xml2enc à traiter correctement les données. Par exemple, pour définir la valeur par défaut Latin1 (iso-8859-1 specifiée dans HTTP/1.0), utilisez :

    xml2EncDefault iso-8859-1

## Directive xml2StartParse

Description: | Indique à l'interpréteur à partir de quelle balise il doit commencer son traitement.
Syntaxe: | `xml2StartParse élément [élément ...]`
Contexte: | configuration du serveur, serveur virtuel, répertoire, .htaccess
Statut: | Base
Module: | mod_xml2enc

Cette directive permet de spécifier à partir de quelle balise, parmi les éléments spécifiés, l'interpréteur de balise doit commencer son traitement. Ccei permet de contourner le problème des serveurs d'arrière-plan qui insèrent des éléments non conformes en début de données, ce qui a pour effet de perturber l'interpréteur (voir un exemple ici).

Elle ne doit être utilisée ni pour les documents XML, ni pour les documents HTML correctement formatés.