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

<?xml version="1.0" encoding="UTF-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 656d1610af1a960d87c8b7056e54d0d4c75fb123 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></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>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>num_args</parameter></term>
     <listitem>
      <para>
       Conseil à l'analyseur SQLite si la fonction de rappel accepte un nombre
       prédéterminé d'arguments.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </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 <parameter>$rows</parameter>
   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>
  <note>
   <para>
    Cette méthode n'est pas disponible avec les pilotes de SQLite2.
    Utilisez l'ancien style de l'API sqlite à la place.
   </para>
  </note>
 </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
-->