(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)
PDO::sqliteCreateAggregate — Référence une fonction agrégative définie par l'utilisateur pour une utilisation dans les requêtes SQL
$function_name
,$step_func
,$finalize_func
,$num_args
= ?Cette fonction est EXPERIMENTALE. Le comportement de cette fonction, son nom, et toute la documentation autour de cette fonction peut changer sans préavis dans une prochaine version de PHP. Cette fonction doit être utilisée à vos risques et périls.
Cette méthode est similaire à PDO::sqliteCreateFunction à l'exception qu'elle référence les fonctions qui peuvent être utilisées pour calculer un résultat agrégé à travers toutes les lignes d'une requête.
La différence entre cette méthode et PDO::sqliteCreateFunction est que deux fonctions sont requises pour gérer les agrégation.
function_name
Le nom de la fonction utilisée dans les requêtes SQL.
step_func
Fonction de rappel appelée pour chaque ligne dans le jeu de résultats. Votre fonction PHP devrait accumuler le résultat et stocker son contexte d'agrégation.
Cette fonction doit être définie comme :
context
null
pour la première ligne ; sur les lignes suivantes ceci aura la valeur
qui a été précedement retourné par la fonction step ; vous devriez utiliser
ceci pour maintenir l'état d'aggregation.
rownumber
Le numéro de ligne courante.
value
Le premier argument à passer à l'agrégateur.
values
Arguments supplémentaires à passer à l'agrégateur.
context
lors du prochain appel d'une fonction
d'étape ou finale.
finalize_func
Fonction de rappel pour agréger les "étapes" de données de chaque ligne. Une fois que toutes les lignes ont été traitées, la fonction sera appelée, prendra les données du contexte d'agrégation et retournera le résultat. La fonction de rappel doit retourner un type compris par SQLite (c'est-à-dire un type scalaire).
Cette fonction doit être définie comme :
context
Contient la valeur de retour du tout dernier appel à la fonction step.
rowcount
Contient le nombre de lignes sur lesquelles l'agrégat a été effectué.
num_args
Conseil à l'analyseur SQLite si la fonction de rappel accepte un nombre prédéterminé d'arguments.
Cette fonction retourne true
en cas de succès ou false
si une erreur survient.
Exemple #1 Exemple d'agrégation avec une fonction max_length
<?php
$data = array(
'one',
'two',
'three',
'four',
'five',
'six',
'seven',
'eight',
'nine',
'ten',
);
$db = new PDO('sqlite::memory:');
$db->exec("CREATE TABLE strings(a)");
$insert = $db->prepare('INSERT INTO strings VALUES (?)');
foreach ($data as $str) {
$insert->execute(array($str));
}
$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->sqliteCreateAggregate('max_len', 'max_len_step', 'max_len_finalize');
var_dump($db->query('SELECT max_len(a) from strings')->fetchAll());
?>
Dans cet exemple, on crée une fonction agrégative qui va calculer la
longueur de la plus grande chaîne de caractères dans une des colonnes de la
table. Pour chaque ligne, la fonction max_len_step
est
appelée et le paramètre $context
est passé. Le
paramètre de contexte est comme n'importe quelle autre variable PHP et
doit être fixé pour contenir un tableau ou même, un objet. Dans cet exemple,
nous l'utilisons pour contenir la taille maximale que nous avons vu jusqu'à
présent ; si le paramètre $string
a une grandeur plus
importante que celle courante, on met à jour le contexte pour contenir cette
nouvelle taille maximale.
Une fois que toutes les lignes ont été traitées, SQLite appelle la fonction
max_len_finalize
pour déterminer le résultat agrégatif.
Ici, nous pourrions effectuer des calculs basés sur les données trouvées
dans $context
. Dans notre exemple simple, nous avons
calculé le résultat comme si la requête progressait, alors que nous avons
simplement besoin de retourner la valeur de contexte.
Il n'est PAS recommandé d'enregistrer une copie des valeurs dans le contexte pour finalement les traiter. Dans ce cas, SQLite utiliserait beaucoup trop de mémoire pour traiter la requête - imaginez la quantité de mémoire nécessaire si un million de lignes étaient enregistrées en mémoire, sachant que chaque ligne contient une chaîne de caractères (32 octets par chaîne).
Vous pouvez utiliser PDO::sqliteCreateFunction et PDO::sqliteCreateAggregate pour surcharger les fonctions natives de SQLite.