ldapsaisie/doc/conf/LSobject/ioFormat.docbook

<sect2 id="config-LSobject-ioFormat">
  <title>ioFormat</title>
  <para>Cette section décrit la manière de paramétrer les formats d'import/export
  pour un type d'&LSobject; donné.</para>

<para>La configuration des <emphasis>ioFormats</emphasis> se situe dans la
configuration des &LSobjects;, dans la variable <varname>ioFormat</varname>
(<emphasis>$GLOBALS['LSobjects']['[nom du type d'LSobject]']['ioFormat']</emphasis>).
Cette variable est un tableau associatif dont la clé est l'identifiant du format et
dont la valeur associée est la configuration du format.

<important><para>Le moteur d'importation simule la validation d'un formulaire de
création du type d'&LSobject; (ou de modification en cas d'activation du mode mise à jour
uniquement, voir ci-dessous). En conséquence :
<itemizedlist>
  <listitem><simpara>seul les attributs présent dans le formulaire de création peuvent
  être importés.</simpara></listitem>
  <listitem><simpara>tous les attributs obligatoires présents dans le formulaire de
  création doivent être fournis par le fichier source ou générer à partir des autres
  attributs.</simpara></listitem>
  <listitem><simpara>Les valeurs des attributs issus de l'importation seront vue comme
  des valeurs retournées par le formulaire et non comme des valeurs des attribus LDAP
  eux-même. Ainsi et par exemple, un attribut traité comme un booléen dans un formulaire
  pourra prendre comme valeur par défaut <literal>yes</literal> ou <literal>no</literal>.
  </simpara></listitem>
</itemizedlist>
</para></important>
<programlisting>
<citetitle>Structure</citetitle>
<![CDATA[$GLOBALS['LSobjects']['[nom du type d'LSobject]']['ioFormat'] = array (
  '[ioFormat ID]' => array (
    'label' => '[Label du type de fichier]',
    'driver' => '[Pilote d'ioFormat utilisé]',
    'driver_options' => array([Options du pilote d'ioFormat utilisé]),
    'update_only' => '[Booléen]',
    'fields => array (
      '[champ 1]' => '[attribut 1]',
      '[champ 2]' => '[attribut 2]',
      [...]
    ),
    'generated_fields' => array (
      '[attribute 3]' => '[LSformat]',
      '[attribute 4]' => array('[LSformat1]', '[LSformat2]', ...)
      '[attribute 5]' => function($attrs, $row) {
        return array([...]);
      },
      [...]
    ),
    'before_import' => array('function1', 'function2'),
    'after_import' => 'function3',
  ),
  [...]
);]]>
</programlisting>

<variablelist>
<title>Paramètres de configuration</title>

<varlistentry>
  <term>label</term>
  <listitem>
    <simpara>Le label du format</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>driver</term>
  <listitem>
    <simpara>Le pilote a utilisé pour ce format. Le pilote permet de gérér la lecture
    et l'écriture dans un type de fichier d'import/export. Pour plus d'information sur
    les pilotes disponibles, <link linkend='config-LSobject-ioFormat-drivers'>Voir la
    section concernée.</link></simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>driver_options</term>
  <listitem>
    <simpara>Tableau associatif des options du pilote utilisé pour ce format. Pour
    plus d'informations, consulter la documentation du pilote utilisé.</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>update_only</term>
  <listitem>
    <simpara>Booléen permetant d'activer le mode mise à jour uniquement pour ce format. Dans ce
    mode, les données de l'objet LDAP correspondant seront chargées depuis l'annuaire avant toutes
    validations des données fournies dans le fichier d'import, et ce, dans un formulaire de
    modifications et non pas un formulaire de création autrement. Pour que cela soit possible, il
    est indispensable que le DN de l'objet puisse être déduit depuis les données fournies dans le
    fichier d'import. Pour cela, vous pouvez le fournir via un champ du fichier d'import associé
    à la clé <literal>dn</literal> ou à défaut il sera généré à partir du RDN dont la valeur devra
    être fournie dans le fichier d'import. Vous pouvez également le générer via le paramètre
    <literal>generated_fields</literal> (voir ci-dessous).</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>fields</term>
  <listitem>
    <simpara>Tableau associatif permettant d'associer un champ du fichier source (la clé)
    avec attribut de l'objet LDAP (la valeur). Il est également possible d'associé un champ
    avec la valeur <literal>dn</literal> pour fournir le DN de l'objet en mode mise à jour
    uniquement (voir ci-dessus).</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>generated_fields</term>
  <listitem>
    <simpara>Tableau associatif permettant de définir soit des &LSformats;, soit un
    <emphasis>callable</emphasis> (au sens PHP) pour générer les valeurs d'attributs automatiquement.
    Ce tableau contient en clé, le nom de l'attribut à générer (ou <literal>dn</literal> pour la
    génération du DN de l'objet en mode mise à jour uniquement), et en valeur associée, un ou plusieurs
    &LSformat; ou un <emphasis>callable</emphasis> à utiliser pour générer ses valeurs. En cas de
    &LSformat;, ils seront composés à l'aide des valeurs des autres attributs de l'objet. En cas d'un
    <emphasis>callable</emphasis>, il sera appeler avec en paramètre le tableau des valeurs des autres
    attributs (<literal>$attrs</literal>), le tableau des données issues du fichier source
    (<literal>$row</literal>) et devra retourner le tableau des valeurs générées de l'attribut ou
    <literal>false</literal> en cas d'erreur.
    </simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>before_import</term>
  <listitem>
    <simpara>Chaîne de caractères (ou tableau de chaîne de caractères) correspondant
    au nom d'une ou plusieurs fonctions qui seront exécutées avant chaque import.
    <link linkend="config-LSobject-ioFormat-triggers">Voir la section concernée</link></simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>after_import</term>
  <listitem>
    <simpara>Chaîne de caractères (ou tableau de chaîne de caractères) correspondant
    au nom d'une ou plusieurs fonctions qui seront exécutées après chaque import.
    <link linkend="config-LSobject-ioFormat-triggers">Voir la section concernée</link></simpara>
  </listitem>
</varlistentry>

</variablelist>
</para>

<sect3 id="config-LSobject-ioFormat-drivers">
  <title>Pilote d'ioFormat</title>
  <para>Cette section décrit la manière de configurer les pilotes d'ioFormat utilisés
  lors des imports/exports d'&LSobjects;.</para>

<sect4 id="config-LSobject-ioFormat-drivers-CSV">
    <title>Pilote de fichiers CSV</title>
    <para>Ce pilote permet de gérer l'import/export de &LSobject; à partir d'un fichier
    <literal>CSV</literal>. Depuis la version 4 d'LdapSaisie, ce pilote utilise les
    fonctions standards <literal>fgetcsv()</literal> et <literal>fputcsv</literal>
    fournis par PHP. Avant cela, la classe PEAR <application>
    <ulink url='http://pear.php.net/package/File_CSV_DataSource'>File_CSV_DataSource
    </ulink></application> était utilisée. Par défaut, les paramètres de lecture et
    d'écriture des fichiers sont : la virgule sert de délimiteur, le caractère
    <literal>"</literal> peut être utilisé pour encadrer les valeurs des champs et la
    longueur maximale d'une ligne est infini. Ces paramètres peuvent être modifiés en
    configurant les options du pilote.
<programlisting>
<citetitle>Structure</citetitle>
<![CDATA[$GLOBALS['LSobjects']['[nom du type d'LSobject]']['ioFormat']['[ID ioFormat]']['driver_options'] = array (
  'delimiter' => '[délimiteur]',
  'enclosure' => '[caractère d'encadrement de texte]',
  'length' => [longueur maximale d'une ligne],
  'escape' => '[caractère d'échappement]',
  'multiple_value_delimiter' => '[délimiteur]',
);]]>
</programlisting>

<variablelist>
<title>Paramètres de configuration</title>

<varlistentry>
  <term>delimiter</term>
  <listitem>
    <simpara>Le caractère utilisé pour délimiter les champs (Par défaut, une virgule).</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>length</term>
  <listitem>
    <simpara>La longueur maximale d'une ligne du fichier. Si zéro est spécifié, la longueur d'une
    ligne ne sera pas limité, mais la lecture du fichier sera ralentie. (Par défaut : <literal>0
    </literal>)
    </simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>enclosure</term>
  <listitem>
    <simpara>Le caractère utilisé pour encadrer les valeurs des champs
    (Par défaut : <literal>"</literal>).</simpara>
  </listitem>
</varlistentry>

<varlistentry>
  <term>escape</term>
  <listitem>
    <simpara>Le caractère d'échappement utilisé si un des champs d'une ligne de fichier contient le
    caractère utilisé pour encadrer les valeurs. (Par défaut : <literal>\</literal>).</simpara>
    <note><simpara>Selon la RFC4180, l'echappement du caractère utilisé pour encadrer les valeurs des
    champs doit se faire en le doublant. Le caractère défini ici est une alternative à ce comportement
    par défaut. Pour désactiver ce caractère d'échappement alternatif, il est possible depuis de la
    version 7.4.0 de PHP de mettre ici une chaine vide.</simpara></note>
  </listitem>
</varlistentry>

<varlistentry>
  <term>multiple_value_delimiter</term>
  <listitem>
    <simpara>Le caractère utilisé pour délimiter au sein d'un champs, les valeurs valeurs multiples d'un
    attribut (Par défaut : <literal>|</literal>).</simpara>
  </listitem>
</varlistentry>

</variablelist>

</para>

</sect4>

</sect3>

<sect3 id="config-LSobject-ioFormat-triggers">
  <title>Déclencheurs</title>
  <para>Cette section décrit la manière de paramétrer des déclencheurs afin que
  &LdapSaisie; exécute durant ses processus, et à des moments bien précis des
  traitements d'un &ioFormat;, des fonctions que vous pourrez développer vous
  même. De plus, le résultat de l'exécution de vos fonctions pourra influer
  sur le déroulement des processus.</para>

  <para>Actuellement, les évenements suivant sont gérés :

<informaltable>
 <tgroup cols="3"> <!-- on décrit le nombre de colonnes -->
   <thead> <!-- on passe au "header" du tableau -->
     <row>
       <entry>Nom</entry>
       <entry>Description</entry>
       <entry>Bloquant</entry>
     </row>
   </thead>
   <tbody> <!-- et on remplit les lignes -->
     <row>
       <entry><literal>before_import</literal></entry>
       <entry><simpara>Avant l'import.</simpara></entry>
       <entry><simpara>Oui</simpara></entry>
     </row>
     <row>
       <entry><literal>after_import</literal></entry>
       <entry><simpara>Après l'import'.</simpara></entry>
       <entry><simpara>Non</simpara></entry>
     </row>
   </tbody>
 </tgroup>
</informaltable>
<note><simpara>Si un événement est dit <emphasis>bloquant</emphasis>, lors de
l'exécution des actions liées, si une des fonctions retourne <literal>false
</literal>, le processus s'arrêtera.</simpara></note>
  </para>
  <sect4 id="config-LSobject-ioFormat-triggers-config">
    <title>Configuration</title>
    <para>La configuration des déclencheurs se fait dans la définition des types
    d'&ioFormat;. Par exemple, pour définir les fonctions à exécuter après
    l'import des LSobjects de type <emphasis>LSpeople</emphasis> avec son LSioFormat <emphasis>
    mycsv</emphasis>, c'est à dire lors de leur évènement <literal>after_import</literal>, il faut
    définir la variable suivante :
    <programlisting linenumbering="unnumbered"><![CDATA[$GLOBALS['LSobjects']['LSpeople']['ioFormat']['mycsv']['after_import']]]></programlisting>
    Cette variable peut contenir soit une chaine de caractères correspondant au
    nom de la fonction à exécuter, soit un tableau de chaînes de caractères
    correspondant aux noms des fonctions à exécuter. Il est également possible de mettre ici directement
    des <ulink url='https://www.php.net/manual/fr/functions.anonymous.php'>fonctions anonymes</ulink>.
    </para>
  </sect4>
  <sect4 id="config-LSobject-ioFormat-triggers-writing">
    <title>Ecriture d'une fonction</title>
    <para>Une fonction exécutée par un déclencheur d'un ioFormat se déclare de la
    manière suivante :
    <programlisting linenumbering="unnumbered"><![CDATA[
/*
 * Ma fonction à exécuter lors de l'evenement [event]
 *
 * Paramètres :
 *     - $ioFormat : Le LSioFormat sur lequel l'évènement survient
 *     - $data : Les données de contexte de l'évènement
 *
 * Valeurs retournées :
 *     - True : Tout s'est bien passé
 *     - False : Une erreur est survenue ou la fonction souhaite bloquer le
 *               processus lors d'un évènement bloquant.
 */
function maFonction (&$ioFormat, &$data) {

  // Actions

}
    ]]></programlisting>
Cette fonction doit accepter deux paramètres, le LSioFormat sur lequel l'évènement survient et un
tableau des données contextuelles de l'évènement. Elle doit par ailleurs retourner
<literal>True</literal> si tout s'est bien passé ou <literal>False</literal> en cas de problème.
Dans le cas d'un événement bloquant, si la fonction retourne <literal>False</literal>, le processus
est arrêté.</para>

<para>Les données contextuelles de l'évènement, passées en paramètre, pourront dépendre du contexte
et de l'évènement déclencheur, mais pour les moments, il s'agit toujours d'un tableau telque décrit
ci-dessous :
<programlisting linenumbering="unnumbered"><![CDATA[array(
  'input_file' => "[/path/of/import.file]",
  'updateIfExists' => [boolean],
  'justTry' => [boolean],
  'objectsData' => array(
    [Données des objets chargés depuis le fichier d'import]
  ),
  'return' => array(
    'success' => [boolean],
    'LSobject' => "[nom du type d'LSobject]",
    'ioFormat' => "[nom du type d'ioFormat]",
    'updateIfExists' => [boolean],
    'justTry' => [boolean],
    'imported' => array([objets importés]),
    'updated' => array([objets mis à jour]),
    'errors' => array(
      array(
        'data' => [données de l'objet importé ayant déclenché l'erreur],
        'errors' => array (
          'globals' => array("Erreur 1", [...]),
          'attrs' => array(
            'attr1' => array("Erreur 1", [...]),
            [...]
          ),
        ),
      ),
      [...]
    ),
  ),
)]]></programlisting>
<note><simpara>Les clés <literal>objectsData</literal> et <literal>return</literal> sont des références.
En cas de modification, cela influencera respectivement sur les données utilisées pour l'import et
sur le résultat de l'import tel qu'affiché dans l'interface.</simpara></note>
</para>
  </sect4>

</sect3>

</sect2>