<?xml version="1.0" encoding="utf-8"?>

<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>

Регистрирует пользовательскую функцию для вызова в 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>

Метод регистрирует пользовательскую PHP-функцию в SQLite

для вызова в SQL-инструкциях.

Пользовательскую функцию вызывают в триггерах или SQL-запросах наподобие <literal>SELECT</literal>, <literal>UPDATE</literal>

или других предложениях с поддержкой вызова функций.

</simpara>

<tip>

<simpara>

При совпадении названий метод переопределит встроенную SQL-функцию.

</simpara>

</tip>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<variablelist>

<varlistentry>

<term><parameter>function_name</parameter></term>

<listitem>

<simpara>

Название функции, которое указывается в SQL-инструкции.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>callback</parameter></term>

<listitem>

<simpara>

Callback-функция для обработки пользовательской SQL-функции.

</simpara>

<note>

<simpara>

SQLite поддерживает только значения <link linkend="language.types.intro">скалярных типов</link>,

поэтому возврат из callback-функций значений других типов вызовет ошибку.

</simpara>

</note>

<para>

Корректная сигнатура функции обратного вызова:

<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>

Первый аргумент SQL-функции.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>values</parameter></term>

<listitem>

<para>

Дополнительные аргументы SQL-функции.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>num_args</parameter></term>

<listitem>

<simpara>

Количество аргументов, которое принимает SQL-функция.

При установке значения <literal>-1</literal> SQL-функция

примет произвольное количество аргументов.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>flags</parameter></term>

<listitem>

<simpara>

Битовая маска флагов.

Метод пока поддерживает только флаг <constant>Pdo\Sqlite::DETERMINISTIC</constant>,

который указывает, что функция возвращает один и тот же результат

при одинаковых входных данных в рамках одной 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>Пример регистрации пользовательской SQL-функции методом <methodname>Pdo\Sqlite::createFunction</methodname></title>

<simpara>

В примере функция вычисляет дайджест строки по алгоритму SHA256, а затем инвертирует хеш.

При выполнении SQL-инструкции БД возвращает результат,

в котором пользовательская функция преобразовала каждое название файла.

Данные, которые возвращаются в переменной <varname>$rows</varname>,

содержат результат обработки.

</simpara>

<simpara>

Преимущество подхода состоит в автоматической обработке запроса пользовательской функцией

вместо постобработки результата в цикле &foreach;.

</simpara>

<programlisting role="php">

</programlisting>

</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>