Dans le jeu de fonctions
sql_* certains paramètres sont présents systématiquement et signifient la même information. Voici donc ces paramètres pour ne pas répéter maintes fois les mêmes choses :
-*
$serveur (ou
$connect) est le nom du fichier de connexion SQL (dans le répertoire
config/. Non renseigné ou vide, c’est le fichier de connexion défini à l’installation de SPIP qui est utilisé. C’est en général l’avant dernier paramètre des fonctions d’abstractions SQL.
-*
$options vaut
true par défaut et permet d’indiquer un caractère optionnel par son intermédiaire. Ce paramètre est en général le dernier des fonctions d’abstractions SQL. Il admet :
-**
true : toute fonction dans l’API SQL et non trouvée sur le jeu d’instruction SQL du serveur demandé provoquera une erreur fatale.
-**
'continue' : pas d’erreur fatale si la fonction n’est pas trouvée.
-** et
false : la fonction du jeu SQL n’exécute pas la requête quelle aura calculée, mais doit la retourner (on obtient donc une chaine de caractère qui est une requête SQL valide pour le gestionnaire de base de données demandé).
D’autres paramètres sont parfois présents d’une fonction à l’autre, en particulier pour toutes les fonctions qui s’apparentent à
sql_select() en reprenant tout ou partie de ses paramètres :
-*
$select, tableau des colonnes sql à récupérer,
-*
$from, tableau des tables SQL à utiliser,
-*
$where, tableau de contraintes sur les colonnes où chaque élément du tableau sera agrégé avec
AND,
-*
$groupby, tableau les groupements des résultats,
-*
$orderby, tableau définissant l’ordonnancement des résultats,
-*
$limit, chaine indiquant le nombre de résultat à obtenir,
-*
$having tableau de post-contraintes pour les fonctions d’agrégation.
Dans les fonctions de modification de contenu, on rencontre un paramètre commun :
-*
$desc, est un tableau de description des colonnes de la table SQL utilisée. S’il est omis, la description sera calculée automatiquement si les fonctions de portage en ont besoin.
{{{Principes d’écriture}}}
Un grand nombre de paramètres sont tolérants dans le type d’argument qui leur est envoyé, acceptant tableaux ou chaînes de caractères. C’est le cas par exemple des paramètres de
sql_select(). Son premier paramètre est
$select correspondant à la liste des colonnes SQL à récupérer. Voici 4 écritures fonctionnelles pour ce paramètre :
// 1 element
sql_select('id_article', 'spip_articles');
sql_select(array('id_article'), 'spip_articles');
// 2 elements
sql_select('id_article, titre', 'spip_articles');
sql_select(array('id_article', 'titre'), 'spip_articles');
Par convention, qui n’a rien d’obligatoire, on préférera utiliser l’écriture tabulaire dès qu’il y a plus d’un élément, écriture plus facilement analysable par les fonctions traduisant l’écriture abstraite en requête SQL.
{{{Préfixe des tables}}}
Les fonctions
sql_* remplacent le nom des tables SQL dans la requête qui commencent par « spip_ » (comme « spip_articles ») par le préfixe de table utilisé sur votre base de données. Ainsi, l’appel suivant fonctionnera quelque soit le préfixe de table utilisé :
sql_select('titre', 'spip_articles', 'id_article=' . sql_quote(1));