Présentation
L'objet CopixDAOSearchParams est utilisé dans les DAO pour réaliser des requêtes à condition (findBy, countBy, deleteBy).
Exemple :
//On récupère les nouvelles de catégorie 2
_ioDao ('maTable')->findBy (_daoSp ()->addCondition ('id_categorie', '=', 2));
Cet objet propose 6 méthodes :
- addCondition pour l'ajout d'une condition de sélection
- addSQL pour l'ajout d'une condition de sélection directement en SQL
- orderBy pour le tri des résultats
- startGroup pour ajouter un groupe de conditions
- endGroup pour terminer un groupe de conditions
- setLimit (ou setOffset & setCount) pour limiter les résultats à un certain nombre d'enregistrements
addCondition
La méthode addCondition permet d'ajouter des restrictions à la recherche.
Elle accepte 4 paramètres qui sont :
- le nom du champ sur lequel s'applique la restriction
- la condition de comparaison que doit supporter le champ
- la valeur avec laquelle le champ sera comparé
- Le type de la condition (obligatoire AND ou non OR), par défaut positionnée à AND
Le nom du champ
Le nom du champ doit être celui que vous utilisez dans votre DAO. Si jamais vous avez défini un fichier XML, c'est le nom de la propriété name qu'il faudra utiliser, et non le nom réel du champ en base de données (fieldname).
Si vous utilisez un DAO automatique, le champ et sa représentation physique ayant le même nom, vous n'avez pas de question à vous poser.
La condition
Les conditions peuvent être tout type de comparaison supportée par les moteurs SQL, à savoir en général :
- = égalité
- ! = différence (sera converti en <> en interne par la méthode addCondition)
- <> différence
- > supérieur (le champ doit être supérieur à la valeur)
- > = supérieur ou égal (le champ doit être supérieur ou égal à la valeur)
- < inférieur (le champ doit être inférieur à la valeur)
- < = inférieur ou égal (le champ doit être inférieur ou égal à la valeur)
- LIKE pour la ressemblance
Cas particulier avec les valeurs null
Si vous spécifiez une valeur NULL avec un addCondition et un opérateur d'égalité ou de différence, Copix générera une requête SQL avec "IS" ou "IS NOT". Inutile donc de gérer vous même ces cas particulier de SQL.
exemple
//On compte le nombre de nouvelles sans catégories
_dao ('News')->findBy (_daoSp ()->addCondition ('category', '=', null));
//La requête SQL exécutée sera bien
//select .... from News where category IS NULL
//On compte le nombre de nouvelles avec une catégorie
_dao ('News')->findBy (_daoSp ()->addCondition ('category', '!=', null));
//ou _dao ('News')->findBy (_daoSp ()->addCondition ('category', '<>', null));
//La requête SQL exécutée sera bien
//select .... from News where category IS NOT NULL
AND / OR
Exemple d'utilisation des AND / OR avec addCondition
// On crée l'objet de critères
$criteres = _daoSp ()->addCondition ('author', '=', 'martin')
->addCondition ('author', '=', 'dupont', 'or');
// On récupère le résultat => liste des news dont l'auteur est martin ou dupont
$resultats = _dao ('News')->findBy ($criteres);
Utiliser des tableaux en tant que valeur
Vous pouvez donner un tableau en tant que valeur pour les conditions. Si tel est le cas, Copix réagira comme si vous aviez appelé successivement addCondition avec un OR.
Exemple :
// Cette syntaxe avec un tableau...
_daoSp ()->addCondition ('author', '=', array ('martin', 'dupont', 'durand', 'copix'));
//est équivalente à
_daoSp ()->startGroup ()
->addCondition ('author', '=', 'martin')
->addCondition ('author', '=', 'dupont', 'or')
->addCondition ('author', '=', 'durand', 'or')
->addCondition ('author', '=', 'copix', 'or')
->endGroup ();
addSQL
Parfois, certaines condition de sélection sont impossibles à décrire avec un simple addCondition, et il est également dommage d'avoir recours à une surcharge de DAO pour ce faire.
Ainsi, il vous est possible de demander à ajouter des conditions SQL sur vos champs, de la façon suivante :
$sp = _daoSP ()->addCondition ('titre_test', '=', 'Titre 3')
->addSQL ('not exists (select * from copixtestautodao where titre_test = :titre_test)', array (':titre_test'=>2038));
La méthode addSQL accepte 3 paramètres :
- le SQL à ajouter. Si la chaine SQL passée est vide, l'instruction est ignorée.
- la valeur des variables de la chaine SQL, au même titre que si vous faisiez une requête en direct avec CopixDB
- le type de condition (AND ou OR). Si vous ne souhaitez pas générer de and ou de or, vous pouvez spécifier une chaine vide.
groupBy
La méthode groupBy vous permet de spécifier quels champs seront utilisés pour grouper les résultats.
La méthode groupBy accepte autant de paramètres que de champs à grouper (dans l'ordre).
//grouper sur le champs field2
_daoSp()->groupBy ('field2');
//grouper sur le champs field2 et field3 après recherche sur field1
_daoSp()->addCondition('field1','=','foo')->groupBy ('field2', 'field3');
orderBy
La méthode orderBy vous permet de spécifier des ordres de tri pour les résultats.
La méthode orderBy accepte autant de paramètres que de champs utilisés dans le tri.
Spécification d'un tri ascendant
spécification d'un tri descendant
setLimit, setCount, setOffset
Ces méthodes permettent de définir des limites sur les enregistrements à récupérer.
//Demande à récupérer 4 enregistrements à partir de l'enregistrement numéro 3
_daoSp ()->setLimit (2, 4);
//ou
_daoSp ()->setOffset (2)
->setCount (4);
//Demande à récupérer 5 enregistrements
_daoSp ()->setCount (5);
//Demande à récupérer à partir de l'enregistrement 6 (inclus)
_daoSp ()->setOffset (5);
startGroup & endGroup
startGroup et endGroup permettent de définir des groupes de conditions. Vous pouvez imbriquer autant de groupes que vous le souhaitez.
startGroup accepte un paramètre qui est le type de groupe (conditions requises (AND) ou facultatives (OR)) au même titre que le 4ème paramètre de addCondition.
Par défaut, le paramètre est positionné à "AND"
Exemple
//sélection de tous les éléments sticky ou de tous les éléments non sticky datant de 2006 ou plus
_daoSp ()->addCondition('sticky', '=', '1')
->startGroup ('OR')
->addCondition('sticky', '=', '0')
->addCondition('date', '>', '2006-01-01')
->endGroup ();