(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)
PDO::sqliteCreateAggregate — Registra uma função de agregação definida pelo usuário para uso em declarações SQL
$function_name,$step_func,$finalize_func,$num_args = ?Esta função é EXPERIMENTAL. O comportamento desta função, seu nome e documentação poderão mudar sem aviso prévio em futuras versões do PHP. Use por sua conta e risco.
Este método é semelhante a PDO::sqliteCreateFunction, exceto que registra funções que podem ser usadas para calcular um resultado agregado através de todas as linhas de uma consulta.
A principal diferença entre este método e PDO::sqliteCreateFunction é que duas funções são necessárias para gerenciar a agregação.
function_nameO nome da função usada nas declarações SQL.
step_funcFunção callback chamada para cada linha do conjunto de resultados. A função PHP deve acumular o resultado e armazená-lo no contexto de agregação.
Esta função precisa ser definida como:
context
null para a primeira linha; nas linhas subsequentes terá o valor
que foi retornado anteriormente da função step; isso deve ser usado
para manter o estado de agregação.
rownumberO número da linha atual.
valueO primeiro argumento passado para a agregação.
valuesOutros argumentos passados para a agregação.
context na próxima chamada das funções step ou
finalize.
finalize_funcFunção de chamada de retorno para agregar os dados "passados" de cada linha. Depois que todas as linhas forem processadas, esta função será chamada e deverá então pegar os dados do contexto de agregação e retornar o resultado. Esta função deve retornar um tipo reconhecido pelo SQLite (ou seja, um tipo escalar).
Esta função precisa ser definida como:
contextContém o valor retornado da última chamada à função step.
rowcountContém o número de linhas nas quais a agregação foi executada.
num_argsIndica ao analisador SQLite se a função callback aceita um número predeterminado de argumentos.
Exemplo #1 Exemplo de função de agregação max_length
<?php
$dados = array(
'um',
'dois',
'três',
'quatro',
'cinco',
'seis',
'sete',
'oito',
'nove',
'dez',
);
$db = new PDO('sqlite::memory:');
$db->exec("CREATE TABLE strings(a)");
$insert = $db->prepare('INSERT INTO strings VALUES (?)');
foreach ($dados as $string) {
$insert->execute(array($string));
}
$insert = null;
function max_len_step($context, $rownumber, $string)
{
if (strlen($string) > $context) {
$context = strlen($string);
}
return $context;
}
function max_len_finalize($context, $rowcount)
{
return $context === null ? 0 : $context;
}
$db->sqliteCreateAggregate('max_len', 'max_len_step', 'max_len_finalize');
var_dump($db->query('SELECT max_len(a) from strings')->fetchAll());
?>
Neste exemplo, está sendo criada uma função de agregação que irá calcular o
comprimento da string mais longa de uma das colunas da tabela.
Para cada linha, a função max_len_step é chamada e recebe
um parâmetro $context. O parâmetro de contexto
é como qualquer outra variável PHP e pode conter um array ou até
mesmo um valor de objeto. Neste exemplo, ele está sendo usado apenas para
manter o comprimento máximo visto até agora; se a
$string tiver um comprimento maior que o máximo
atual, o contexto será atualizado para conter esse novo comprimento máximo.
Após todas as linhas terem sido processadas, o SQLite chama a função
max_len_finalize para determinar o resultado agregado.
Aqui, algum tipo de cálculo poderia ser realizado com base nos dados
encontrados no parâmetro $context.
Porém, neste exemplo simples, o resultado foi calculado à medida que a
consulta avançava, portanto é necessário apenas retornar o valor do contexto.
NÃO é recomendado armazenar uma cópia dos valores no contexto e depois processá-los no final, pois isso faria com que o SQLite usasse muita memória para processar a consulta - basta pensar em quanta memória seria necessária se um milhão linhas fossem armazenadas na memória, cada uma contendo uma string de 32 bytes de comprimento.
PDO::sqliteCreateFunction e PDO::sqliteCreateAggregate podem ser usados para substituir funções SQL nativas do SQLite.