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;. 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é]),
    '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>fields</term>
  <listitem>
    <simpara>Tableau associatif permettant d'associer un champ du fichier source (la clé)
    avec attribut de l'objet LDAP (la valeur).</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, 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.
    </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>