doc-fr/reference/pdo_sqlite/PDO/sqliteCreateFunction.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 9e0f03ac354d797d1d16c0fcc1663e5e170f2727 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="pdo.sqlitecreatefunction" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>PDO::sqliteCreateFunction</refname>
  <refpurpose>
   Référence une fonction définie par l'utilisateur pour une utilisation dans les requêtes SQL
  </refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>bool</type><methodname>PDO::sqliteCreateFunction</methodname>
   <methodparam><type>string</type><parameter>function_name</parameter></methodparam>
   <methodparam><type>callable</type><parameter>callback</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>num_args</parameter><initializer>-1</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>
  &warn.experimental.func;

  <para>
   Cette méthode vous permet de référencer
   une fonction PHP avec SQLite comme étant un <acronym>UDF</acronym> 
   (<literal>User Defined Function</literal>), de telle façon qu'elle 
   puisse être appelée à l'intérieur de vos requêtes SQL.
  </para>
  <para>
   Un UDF peut être utilisé dans n'importe quelle requête SQL qui peut appeler
   des fonctions, par exemple les requêtes SELECT et UPDATE mais aussi dans les
   marqueurs.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>function_name</parameter></term>
     <listitem>
      <para>
       Le nom de la fonction utilisé dans les requêtes SQL.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>callback</parameter></term>
     <listitem>
      <para>
       Fonction de rappel pour manipuler la fonction SQL définie.
      </para>
      <note>
       <simpara>
        Les fonctions de rappel devraient retourner un type connu par SQLite
        (c'est-à-dire <link linkend="language.types.intro">type scalaire</link>).
       </simpara>
      </note>
      <para>
       Cette fonction doit être définit comme :
       <methodsynopsis>
        <type>mixed</type><methodname><replaceable>callback</replaceable></methodname>
        <methodparam><type>mixed</type><parameter>value</parameter></methodparam>
        <methodparam rep="repeat"><type>mixed</type><parameter>values</parameter></methodparam>
       </methodsynopsis>
       <variablelist>
        <varlistentry>
         <term><parameter>value</parameter></term>
         <listitem>
          <para>
           Le premier argument à passer à la fonction SQL.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>values</parameter></term>
         <listitem>
          <para>
           Arguments supplémentaires à passer à la fonction SQL.
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>num_args</parameter></term>
     <listitem>
      <para>
       Nombre d'arguments que la fonction SQL prend. Si ce paramètre est 
       <literal>-1</literal>, la fonction SQL peut prendre n'importe quel nombre 
       d'arguments.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       Une conjonction d'opérations de bits d'indicateurs. Actuellement, seul 
       <constant>PDO::SQLITE_DETERMINISTIC</constant> est pris en charge, ce qui 
       spécifie que la fonction retourne toujours le même résultat étant donné 
       les mêmes entrées dans une seule instruction SQL.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

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

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>7.1.4</entry>
      <entry>
       Le paramètre <parameter>flags</parameter> a été ajouté.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

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

$db = new PDO('sqlite:sqlitedb');
$db->sqliteCreateFunction('md5rev', 'md5_and_reverse', 1);
$rows = $db->query('SELECT md5rev(filename) FROM files')->fetchAll();
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Dans cet exemple, nous avons une fonction qui calcule la somme MD5 de la
   chaîne de caractères et la renverse ensuite. Lorsque la requête SQL
   s'exécute, elle retourne la valeur du nom du fichier transformée par notre
   fonction. Les données retournées dans <literal>$rows</literal>
   contiennent le résultat traité.
  </para>
  <para>
   La beauté de cette technique est que vous n'avez pas à traiter le résultat
   en utilisant une boucle &foreach; après que vous ayez récupéré les données.
  </para>
  <!-- Pas pour PDO, il ne le fait pas pour le moment
  <para>
   PHP référénce une fonction spéciale nommée <literal>php</literal> quand la base de données
   est accédée pour la première fois. La fonction php peut être utilisée pour appeler n'importe quelle
   fonction PHP sans avoir à la référencer au préalable.
  </para>
  <para>
   <example>
    <title>Exemple utilisant la fonction PHP</title>
    <programlisting role="php">
<![CDATA[
<?php
$rows = $db->query("SELECT php('md5', filename) from files")->fetchAll();
?>
]]>
    </programlisting>
    <para>
     Cet exemple appelera <function>md5</function> sur chaque colonne 
     <literal>filename</literal> de la base de données et retournera le résultat en tant 
     que <parameter>$rows</parameter>
    </para>
   </example>
  </para>

  -->
  <tip>
   <para>
    Vous pouvez utiliser <xref linkend="pdo.sqlitecreatefunction" /> et
    <xref linkend="pdo.sqlitecreateaggregate" /> pour surcharger les
    fonctions natives de SQL.
   </para>
  </tip>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><xref linkend="pdo.sqlitecreateaggregate" /></member>
    <member><function>sqlite_create_function</function></member>
    <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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/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
-->