SQLite (PDO)
Manuel PHP

PDO::sqliteCreateAggregate

(PHP 5 >= 5.1.0, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateAggregate — Référence une fonction définie par l'utilisateur agrégative pour une utilisation dans les requêtes SQL

Description

public bool PDO::sqliteCreateAggregate ( string $function_name , callable $step_func , callable $finalize_func [, int $num_args ] )
Avertissement

Cette fonction est EXPERIMENTALE. Cela signifie que le comportement de cette fonction, son nom et, concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS ! Soyez-en conscient, et utilisez cette fonction à 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.

Liste de paramètres

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 :

step ( mixed $context , int $rownumber , mixed $value1 [, mixed $value2 [, mixed $.. ]] )

context vaudra NULL pour la première ligne; pour les lignes suivantes, il vaudra la même valeur que celle précédemment retournée par la fonction step; vous devriez l'utiliser pour maintenir l'état d'agrégation.

rownumber contiendra le nombre de lignes.

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 retournera une type compris par SQLite (c'est-à-dire un type scalaire).

Cette fonction doit être définie comme :

fini ( mixed $context , int $rownumber )

context contiendra la valeur de retour du tout dernier appel à la fonction step.

rownumber contiendra le nombre de lignes sur lesquelles l'agrégation a eu lieu.

La valeur de retour de cette fonction sera utilisée comme valeur de retour pour l'agrégation.

num_args

Conseil à l'analyseur SQLite si la fonction de rappel accepte un nombre prédéterminé d'arguments.

Valeurs de retour

Cette fonction retourne TRUE en cas de succès ou FALSE si une erreur survient.

Exemples

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

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

Astuce

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

Astuce

Vous pouvez utiliser PDO::sqliteCreateFunction et PDO::sqliteCreateAggregate pour surcharger les fonctions natives de SQLite.

Note:

Cette méthode n'est pas disponible avec les pilotes de SQLite2. Utilisez l'ancien style de l'API sqlite à la place.

Voir aussi

SQLite (PDO)
Manuel PHP
LoadingChargement en cours