Magento Dataflow - parsers standard et valeurs de mapping [partie 4]

Comme promis dans le post Magento Dataflow - les Adapters par défaut [Partie 2], aujourd'hui je vais écrire à propos des parsers standards et des mappers disponibles dans le module Magento DataFlow.

  1. Définition des parsers

    Les parsers servent à transformer les données provenant des adapters. L'interface du parser Mage_Dataflow_Model_Convert_Parser_Interface définie 2 méthodes obligatoires pour chaque parser : parse() et unparse(). Définir un parser dans le XML d'actions du profil est aussi simple que ça :

    <action type="dataflow/convert_parser_serialize" method="parse" />

    Comme pour les adapters, nous définissons un tag d'action avec deux attributs: type qui indique quelle classe nous voulons utiliser et method qui indique la méthode à appeler. Nous pouvons également définir le parser en lui fournissant des variables à l'intérieur de l'action tag comme vous allez le voir dans la suite de ce post.

  2. Les parsers standards

    Magento Dataflow inclus quelques parsers standards que vous pouvez trouver dans le dossier app/code/core/Dataflow/Model/Convert/Parser.

    Le plus simple des parsers standards est le parser dataflow/convert_parser_serialize (Mage_Dataflow_Model_Convert_Parser_Serialize) qui n'a besoin d'aucune variable. Il a néanmoins besoin que l'une des actions précédentes du profil d'actions initialise les données. La méthode parse() délinéarise (avec la fonction unserialize) les données contenues dans le container du profile et les remplace avec le résultat. La méthode unparse() fait le contraire, elle linéarise (avec la fonction serialize) les données contenues dans le container du remplace et les remplace avec le résultat.

    Un des parsers standards le plus utilisé est le parser dataflow/convert_parser qui permet des transformations depuis (avec la méthode parse()) ou vers (avec la méthode unparse()) un fichier CSV. Exemple de définition :

    <action type="dataflow/convert_parser_csv" method="parse">
        <var name="delimiter"><![CDATA[,]]></var>
        <var name="enclose"><![CDATA["]]></var>
        <var name="fieldnames">true</var>
        <var name="store"><![CDATA[0]]></var>
        <var name="decimal_separator"><![CDATA[.]]></var>
        <var name="adapter">catalog/convert_adapter_product</var>
        <var name="method">parse</var>
    </action>

    Ce parser nécessite que vous appeliez au préalable un adapter io (par exemple, l'adapter dataflow/convert_adapter_io afin de lire un fichier csv) afin de pouvoir utiliser la méthod parse(). Si vous désirez enregistrer des données dans un fichier CSV, vous devez faire les deux : appeler une méthode qui va définir les données dans le container du profile avant l'exécution du parser et appeler un adapter io après l'exécution du parser afin d'enregistrer les données dans un fichier.

    Les variables suivantes vont vous permettre de personnaliser le parsing du fichier csv :

    • delimiter - définit le délimiteur utilisé dans le fichier csv ; le caractère virgule (,) est utilisé par défaut
    • enclose - définit le caractère utilisé pour encapsulées les données ; valeur vide par défaut.
    • escape - définit le caractère échappatoire pour le fichier csv ; caratère \\ par défaut
    • decimal_separator - définit le caractère pour séparer les décimales
    • fieldnames - si a la valeur true, il considère que la première ligne du fichier csv contient le nom de champs ; si a la valeur false, la variable map est utilisé
    • map - définit le nom des champs pour les fichier dont la première ligne ne contient pas le nom des champs ; pour voir comment définir une map regarder la section de cet article traitant des valeurs de mapping
    • adapter - indique quel adapter doit être appelé pour chaque ligne
    • method - indique quelle méthode de l'adapter doit être appelée pour chaque ligne ; par défaut saveRow

    Toutes les variables définies dans le parser sont transmises à l'adapter. Donc, si vous avez besoin de lui transmettre quelque chose, vous pouvez tout simplement définir les variables obligatoires dans le parser.

    Le dernier des parsers standards inclus dans le module Dataflow est le parser dataflow/convert_parser_xml_excel (Mage_Dataflow_Model_Convert_Parser_Xml_Excel), qui convertit les données depuis et vers un fichier Excel xml. Exemple de définition :

    <action type="dataflow/convert_parser_xml_excel" method="unparse">
        <var name="single_sheet"><![CDATA[products]]></var>
        <var name="fieldnames">true</var>
    </action>

    Les conditions d'utilisation de ce parser sont les mêmes que pour le parser dataflow/convert_parser_csv.

    Les variables suivantes vont vous permettre de personnaliser le parsing de votre fichier Excel :

    • fieldnames - si a la valeur true, il considère que la première ligne du fichier Excel contient le nom de champs ; si a la valeur false, la variable map est utilisé
    • map - définit le nom des champs pour les fichier dont la première ligne ne contient pas le nom des champs
    • single_sheet - indique si les données analysées proviennent d'une seule feuille ou de toutes ; doit contenir le nom de la feuiller à analyser
    • adapter - indique quel adapter doit être appelé pour chaque ligne
    • method - indique quelle méthode de l'adapter doit être appelée pour chaque ligne ; par défaut saveRow
  3. Les parsers standards pour les clients et les produits

    Pour échanger les entités les plus courantes - les clients et les produits - Magento fournit aussi des parsers standards : customer/convert_parser_customer (Mage_Customer_Model_Convert_Parser_Customer) et catalog/convert_parser_product (Mage_Catalog_Model_Convert_Parser_Product). Tous deux héritent de la classe Mage_Eav_Model_Convert_Adapter_Entity.

    Étant donné que les méthodes load() des adapters retournent uniquement un tableau contenant les identifiants des entités, il est nécessaire d'utiliser les méthodes unparse() des parsers afin d'obtenir plus de données. Les deux parsers prennent ce tableau d'identifiants et pour chaque entité retrouvent les données de ces entités tout en ignorant les champs du système, les objets et les champs qui ne sont pas des attributs. Ils créent finalement un tableau associatif avec les données récoltées. Le parser de produits ajoute également les données provenant de l'objet stock associé au produit. Le parser de clients ajoute quant à lui les données provenant des adresses de livraison et de facturation et les données provenant de l'inscription à la newsletter.

    Les deux parsers d'entités ont des méthodes parse() dépréciées depuis que leur fonctionnement est maintenant principalement réalisée par les actions de parser dans les méthodes des adapters standards appelées dans le contexte du parser. Exemple d'une définition d'un parser de produits, parsant uniquement les produits depuis le magasin sélectionné :

    <action type="catalog/convert_parser_product" method="unparse">
        <var name="store"><![CDATA[1]]></var>
    </action>

  4. Les valeurs de mapping

    Le module Dataflow apporte aussi un concept de mapper - une classe avec une méthode map() responsable de lier (mapper) les champs traités les uns avec les autres. La définition d'un mapper ressemble à ça par exemple :

    <action type="dataflow/convert_mapper_column" method="map">
        <var name="map">
            <map name="category_ids"><![CDATA[categorie]]></map>
            <map name="sku"><![CDATA[reference]]></map>
            <map name="name"><![CDATA[titre]]></map>
            <map name="description"><![CDATA[description]]></map>
            <map name="price"><![CDATA[prix]]></map>
            <map name="special_price"><![CDATA[special_price]]></map>
            <map name="manufacturer"><![CDATA[marque]]></map>
        </var>
        <var name="_only_specified">true</var>
    </action>

    Nous avons encore un tag d'action avec deux attributs : type pour définir la classe du mapper et method pour définir la méthode à appeler pour faire le mapping. Le mapper dataflow/convert_mapper_column est un mapper standard que vous pouvez trouver dans le module Magento Dataflow dans le dossier app/code/core/Dataflow/Model/Mapper/. Son but est de lier un tableau vers un autre en changeant le nom et en limitant les champs dans le résultat. L'attribut name du tag map indique le nom du champ qui doit être remplacé dans le nouveau tableau. Il est remplacé par le nom se trouvant dans le contenu du tag map. Si le nom du champ n'existe pas dans le tableau d'origine, la valeur du champ dans le tableau résultat est alors nulle. La variable _only_specified indique si uniquement les champs spécifiés dans la définition de map doivent être présents dans le tableau résultat.

Cet article devrait être l'article cloturant la présentation des spécifications standards du module Dataflow et les exemples basiques de son utilisation.

Traduction par Laurent Clouet