(PHP 5 >= 5.3.0, PHP 7, PHP 8)
SQLite3::createAggregate — Registra una función PHP para ser utilizada como función de agregación SQLite
$name
,$stepCallback
,$finalCallback
,$argCount
= -1Registra una función PHP o una función definida por el usuario para ser utilizada como función de agregación SQL, que será utilizada en las consultas SQL.
name
Nombre de la función de agregación SQL a crear o redefinir.
stepCallback
Función de retrollamada llamada para cada fila en el conjunto de resultados. Su función PHP debería acumular el resultado y almacenar su contexto de agregación.
Esta función debe ser definida como:
context
null
para la primera fila; en las filas siguientes esto tendrá el valor
que previamente fue retornado por la función step; debería utilizarse
esto para mantener el estado de agregación.
rownumber
El número de fila actual.
value
El primer argumento a pasar al agregador.
values
Argumentos adicionales a pasar al agregador.
context
durante la próxima llamada a una función
de paso o final.
finalCallback
Función de retrollamada para agregar los "pasos" de datos de cada fila. Una vez que todas las filas han sido procesadas, la función será llamada, tomará los datos del contexto de agregación y retornará el resultado. La función de retrollamada debe retornar un tipo comprendido por SQLite (i.e. un tipo escalar).
Esta función debe ser definida como:
context
Contiene el valor de retorno de la última llamada a la función step.
rownumber
Siempre 0
.
argCount
El número de argumentos tomados por la función de agregación SQL. Si este número es negativo, entonces la función de agregación SQL podrá tomar un número no definido de argumentos.
Retorna true
si la creación del agregado ha tenido éxito, o false
en caso de error.
Ejemplo #1 Ejemplo de una función de agregación con max_length
<?php
$data = array(
'one',
'two',
'three',
'four',
'five',
'six',
'seven',
'eight',
'nine',
'ten',
);
$db = new SQLite3(':memory:');
$db->exec("CREATE TABLE strings(a)");
$insert = $db->prepare('INSERT INTO strings VALUES (?)');
foreach ($data as $str) {
$insert->bindValue(1, $str);
$insert->execute();
}
$insert = null;
function max_len_step($context, $rownumber, $string)
{
if (strlen($string) > $context) {
$context = strlen($string);
}
return $context;
}
function max_len_finalize($context, $rownumber)
{
return $context === null ? 0 : $context;
}
$db->createAggregate('max_len', 'max_len_step', 'max_len_finalize');
var_dump($db->querySingle('SELECT max_len(a) from strings'));
?>
El resultado del ejemplo sería:
int(5)
En este ejemplo, se crea una función agregativa que calculará la
longitud de la cadena de caracteres más larga en una de las columnas de la
tabla. Para cada fila, la función max_len_step
es
llamada y el parámetro $context
es pasado. El
parámetro de contexto es como cualquier otra variable PHP y debe ser fijado para
contener un array o incluso, un objeto. En este ejemplo,
se utiliza para contener la longitud máxima que se ha visto hasta el momento; si el
parámetro $string
tiene una longitud mayor que la actual, se
actualiza el contexto para contener esta nueva longitud máxima.
Una vez que todas las filas han sido procesadas, SQLite llama a la función
max_len_finalize
para determinar el resultado agregativo.
Aquí, se podrían realizar cálculos basados en los datos encontrados
en $context
. En nuestro ejemplo simple, hemos
calculado el resultado como si la consulta estuviera progresando, aunque simplemente
necesitamos retornar el valor de contexto.
No se RECOMIENDA registrar una copia de los valores en el contexto para finalmente procesarlos. En este caso, SQLite utilizaría mucha memoria para procesar la consulta - imagine la cantidad de memoria necesaria si un millón de filas fueran registradas en memoria, sabiendo que cada fila contiene una cadena de caracteres (32 bytes por cadena).
Puede utilizarse SQLite3::createAggregate() para sobrescribir las funciones nativas de SQLite.