doc-fr/reference/sqlite/functions/sqlite-create-function.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.22 $ -->
<!-- EN-Revision: 1.18 Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->

<refentry xml:id="function.sqlite-create-function" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>sqlite_create_function</refname>
  <refname>SQLiteDatabase->createFunction</refname>
  <refpurpose>
   Enregistre une fonction utilisateur "classique" UDF pour SQLite
  </refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>void</type><methodname>sqlite_create_function</methodname>
   <methodparam><type>resource</type><parameter>dbhandle</parameter></methodparam>
   <methodparam><type>string</type><parameter>function_name</parameter></methodparam>
   <methodparam><type>callback</type><parameter>callback</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>num_args</parameter></methodparam>
  </methodsynopsis>
  <para>Style orienté objet :</para>
  <classsynopsis>
   <ooclass><classname>SQLiteDatabase</classname></ooclass>
   <methodsynopsis>
    <type>void</type><methodname>createFunction</methodname>
    <methodparam><type>string</type><parameter>function_name</parameter></methodparam>
    <methodparam><type>callback</type><parameter>callback</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>num_args</parameter></methodparam>
   </methodsynopsis>
  </classsynopsis>
  <para>
   <function>sqlite_create_function</function> vous permet d'enregistrer une fonction
   PHP dans SQLite comme <acronym>UDF</acronym> (Fonction Définie par l'Utilisateur,
   <literal>User Defined Function</literal>), pour qu'elle soit accessible depuis 
   les requêtes SQL.
  </para>
  <para>
   Les UDF peuvent être utilisées dans n'importe quelle requête SQL qui peut
   appeler des fonctions, telles que SELECT et UPDATE, ou même des déclencheurs.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>dbhandle</parameter></term>
     <listitem>
      <para>
       La ressource de base de données SQLite; retournée par
       <function>sqlite_open</function> lorsqu'utilisée de manière
       procédurale. Ce paramètre n'est pas requis si vous utilisez la méthode
       orientée objet.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>function_name</parameter></term>
     <listitem>
      <para>
       Le nom de la fonction utilisée dans les requêtes SQL.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>callback</parameter></term>
     <listitem>
      <para>
       Fonction de procédure de rappel pour gérer les fonctions SQL définies.
      </para>
      <note>
       <simpara>
        Les fonctions de procédure de rappel devraient retourner un type
        compris par SQLite (c'est-à-dire, voir
        <link linkend="language.types.intro">type scalaire</link>).
       </simpara>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>num_args</parameter></term>
     <listitem>
      <para>
       Conseil à l'analyseur SQLite si la fonction de procédure de rappel
       accepte un nombre prédéterminé d'arguments.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  &sqlite.param-compat;
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.void;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>sqlite_create_function</function></title>
    <programlisting role="php">
<![CDATA[
<?php
function md5_and_reverse($string)
{
    return strrev(md5($string));
}

if ($dbhandle = sqlite_open('mysqlitedb', 0666, $sqliteerror)) {

    sqlite_create_function($dbhandle, 'md5rev', 'md5_and_reverse', 1);

    $sql  = 'SELECT md5rev(filename) FROM files';
    $rows = sqlite_array_query($dbhandle, $sql);
} else {
    echo 'Erreur pendant l\'ouverture de la base db : ' . $sqliteerror;
    exit;
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Dans cet exemple, nous avons une fonction qui calcule la somme de contrôle
   MD5 d'une chaîne, et l'inverse. Lorsque la requête SQL s'exécute,
   elle retourne le nom du fichier, transformé par cette opération.
   Les données retournées dans <parameter>$rows</parameter> contiennent le
   résultat.
  </para>
  <para>
   La beauté de cette technique est que vous n'avez pas à traiter vous-même
   les données avec une boucle, une fois que vous avez lu les données.
  </para>
  <para>
   PHP enregistre une fonction spéciale appelée PHP lorsque
   la base est ouverte. Cette fonction est utilisée pour appeler toute fonction
   PHP sans avoir à l'enregistrer au préalable.
  </para>
  <para>
   <example>
    <title>Exemple d'utilisation d'une fonction PHP dans SQLite</title>
    <programlisting role="php">
<![CDATA[
<?php
$rows = sqlite_array_query($db, "SELECT php('md5', filename) from files");
?>
]]>
    </programlisting>
    <para>
     Cet exemple va appeler la fonction <function>md5</function> sur chaque
     colonne <literal>filename</literal> dans la base, et retourner le contenu
     dans le tableau <parameter>$rows</parameter>.
    </para>
   </example>
  </para>
  <note>
   <para>
    Pour des raisons de performances, PHP ne va pas automatiquement
    coder ou décoder les données binaires passées à votre UDF. Vous devez le faire
    manuellement. Voyez les fonctions <function>sqlite_udf_encode_binary</function>
    et <function>sqlite_udf_decode_binary</function> pour plus de détails.
   </para>
  </note>
  <tip>
   <para>
    Il n'est pas recommandé d'utiliser des UDF pour traiter des données binaires,
    à moins que les performances ne soient pas un problème pour votre application.
   </para>
  </tip>
  <tip>
   <para>
    Vous pouvez utiliser <function>sqlite_create_function</function> et
    <function>sqlite_create_aggregate</function> pour remplacer des fonctions
    natives SQLite.
   </para>
  </tip>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>sqlite_create_aggregate</function></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
 sgml-omittag:t
 sgml-shorttag:t
 sgml-minimize-attributes:nil
 sgml-always-quote-attributes:t
 sgml-indent-step:1
 sgml-indent-data:t
 sgml-parent-document:nil
 sgml-default-dtd-file:"../../manual.ced"
 sgml-exposed-tags:nil
 sgml-local-catalogs:nil
 sgml-local-ecat-files:nil
 End:
 vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->