createfunction.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 51610360d58ed09bc9d1312f419057c0d1d1a998 Maintainer: Fan2Shrek Status: ready -->
<!-- Reviewed: yes -->
<refentry xml:id="pdo-sqlite.createfunction" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>Pdo\Sqlite::createFunction</refname>
  <refpurpose>
   Enregistre une fonction utilisateur pour une utilisation dans les instructions SQL
  </refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis role="Pdo\\Sqlite">
   <modifier>public</modifier> <type>bool</type><methodname>Pdo\Sqlite::createFunction</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>
  <simpara>
   Cette méthode permet les fonctions PHP d'être enregistrées avec SQLite en tant que
   fonction définie par l'utilisateur, de sorte qu'elles puissent être appelées dans les requêtes SQL.
   La fonction définie peut être utilisée dans n'importe quelle requête SQL qui permet des appels de fonction,
   par exemple <literal>SELECT</literal>, <literal>UPDATE</literal>, ou des déclencheurs.
  </simpara>
  <tip>
   <simpara>
    En utilisant cette méthode, il est possible de remplacer les fonctions SQL natives.
   </simpara>
  </tip>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>function_name</parameter></term>
    <listitem>
     <simpara>
      Le nom de la fonction utilisé dans les instructions SQL.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>callback</parameter></term>
    <listitem>
     <simpara>
      La fonction de rappel pour gérer la fonction SQL définie.
     </simpara>
     <note>
      <simpara>
       La fonction de rappel doit retourner un type compris par SQLite (c'est-à-dire
       <link linkend="language.types.intro">type scalaire</link>).
      </simpara>
     </note>
     <para>
      Cette fonction doit être définie 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 passé à la fonction SQL.
         </para>
        </listitem>
       </varlistentry>
       <varlistentry>
        <term><parameter>values</parameter></term>
        <listitem>
         <para>
          Les arguments supplémentaires passés à la fonction SQL.
         </para>
        </listitem>
       </varlistentry>
      </variablelist>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>num_args</parameter></term>
    <listitem>
     <simpara>
      Le nombre d'arguments que la fonction SQL prend.
      Si ce paramètre est <literal>-1</literal>,
      alors la fonction SQL peut prendre n'importe quel nombre d'arguments.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>flags</parameter></term>
    <listitem>
     <simpara>
      Un masque de bits de drapeaux.
      Actuellement, seul <constant>Pdo\Sqlite::DETERMINISTIC</constant> est supporté,
      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.
     </simpara>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

 <refsect1 role="examples">
  &reftitle.examples;
  <example xml:id="pdo-sqlite.createfunction.example.basic">
   <title><methodname>Pdo\Sqlite::createFunction</methodname> example</title>
   <simpara>
    Dans cette exemple, nous avons une fonction qui calcule la somme SHA256 d'une
    chaîne, puis la renverse. Lorsque l'instruction SQL est exécutée, elle
    retourne la valeur du nom de fichier transformé par notre fonction.
    Les données retournées dans <varname>$rows</varname> contiennent le résultat traité.
   </simpara>
   <simpara>
    La beauté de cette technique est qu'il n'est pas nécessaire de traiter le
    résultat en utilisant une boucle &foreach; après l'exécution de la requête.
   </simpara>
   <programlisting role="php">
<![CDATA[
<?php
function sha256_and_reverse($string)
{
    return strrev(hash('sha256', $string));
}

$db = new Pdo\Sqlite('sqlite::sqlitedb');
$db->sqliteCreateFunction('sha256rev', 'sha256_and_reverse', 1);
$rows = $db->query('SELECT sha256rev(filename) FROM files')->fetchAll();
?>
]]>
   </programlisting>
   <!-- TODO
   &example.outputs;
   <screen>
<![CDATA[
Code example
]]>
   </screen>
   -->
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><methodname>Pdo\Sqlite::createAggregate</methodname></member>
   <member><methodname>Pdo\Sqlite::createCollation</methodname></member>
   <member><function>sqlite_create_function</function></member>
   <member><function>sqlite_create_aggregate</function></member>
  </simplelist>
 </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
-->