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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-create-function">
 <refnamediv>
  <refname>sqlite_create_function</refname>
  <refpurpose>Enregistre une fonction utilisateur "classique" UDF pour SQLite</refpurpose>
 </refnamediv>
 <refsect1>
  <title>Description</title>
  <methodsynopsis>
   <type>bool</type><methodname>sqlite_create_function</methodname>
   <methodparam><type>resource</type><parameter>db</parameter></methodparam>
   <methodparam><type>string</type><parameter>function_name</parameter></methodparam>
   <methodparam><type>mixed</type><parameter>callback</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>num_args</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>sqlite_create_function</function> vous permet d'enregistrer une fonction
   &php; dans SQLite comme <acronym>UDF</acronym> (Fonction D&eacute;finie par l'Utilisateur,
   User Defined Function), pour qu'elle soit accessible depuis les requ&ecirc;tes SQL.
  </para>
  <para>
   <parameter>db</parameter> sp&eacute;cifie une ressource de base de donn&eacute;es SQLite,
   que vous souhaitez am&eacute;liorer. <parameter>function_name</parameter> sp&eacute;cifie
   le nom de la fonction que vous utiliserez dans les requ&ecirc;tes SQL. 
   <parameter>callback</parameter> peut &ecirc;tre n'importe quelle fonction de 
   callback &php;. Le param&egrave;tre optionnel <parameter>num_args</parameter> est
   utilis&eacute; par l'analyseur d'expressions SQLite. Il est recommand&eacute; que vous
   fournissiez une valeur si votre fonction n'accepte qu'un nombre fixe
   d'arguments.
  </para>
  <para>
   Les UDF peuvent &ecirc;tre utilis&eacute;es dans n'importe quelle requ&ecirc;te SQL qui peut
   appeler des fonctions, telles que SELECT et UPDATE, ou m&ecirc;me des triggers.
  </para>
  <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));
}

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

$rows = sqlite_array_query($db, 'SELECT md5rev(filename) from files');
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Dans cet exemple, nous avons une fonction qui calcule la somme de contr&ocirc;le
   MD5 d'une cha&icirc;ne, et l'inverse. Lorsque la requ&ecirc;te SQL s'ex&eacute;cute,
   elle retourne le nom du fichier, transform&eacute; par cette op&eacute;ration.
   Les donn&eacute;es retourn&eacute;es dans <parameter>$rows</parameter> contient le
   r&eacute;sultat.
  </para>
  <para>
   La beaut&eacute; de cette technique est que vous n'avez pas &agrave; traiter vous m&ecirc;me
   les donn&eacute;es avec une boucle, une fois que vous avez lu les donn&eacute;es.
  </para>

  <para>
   &php; enregistre une fonction sp&eacute;ciale appel&eacute;e <literal>php</literal> lorsque
   la base est ouverte. Cette fonction est utilis&eacute;e pour appeler toute fonction
   &php; sans avoir &agrave; l'enregistrer au pr&eacute;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&eacute;coder les donn&eacute;es binaires pass&eacute;es &agrave; 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&eacute;tails.
   </para>
  </note>
  <tip>
   <para>
    Il n'est pas recommand&eacute; d'utiliser des UDF pour traiter des donn&eacute;es binaires,
    &agrave; moins que les performances ne soient pas un probl&egrave;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>
  <para>
   Voir aussi
   <function>sqlite_create_aggregate</function>.
  </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
 -->