Section: Ajouter des méthodes en XML
| « Récupération de liste d'enregistrements DAO | ^ jDao : mapping objet relationnel | Développer des méthodes en php » |
− Table des matières
Une factory générée par jDao contient par défaut un certain nombre de méthodes (find, findAll, get, insert, etc...) comme décrit sur la page sur l'utilisation des daos. Cependant, elles ne sont pas forcément suffisantes, et l'on a souvent besoin de faire des sélections, des mises à jour ou des suppressions particulières.
La section <factory> permet de définir des méthodes supplémentaires à générer, chacune des méthodes exécutant une requête SQL. L'avantage de déclarer de telles méthodes ici, par rapport à la création de requête SQL dans une classe normale, est que vous n'avez plus à vous préoccuper de problème de sqlinjection, de l'écriture fastidieuse des requêtes SQL, etc...
Balise <method> ¶
Les méthodes sont déclarées via la balise <method>. Celle-ci doit avoir au moins un attribut, name, indiquant le nom de la méthode. Il y a différents types de méthode. On indique le type via l'attribut type.
Une balise <method> peut contenir une ou plusieurs balises <parameter>, qui définissent des paramètres. Une balise <parameter> doit avoir un attribut name indiquant son nom.
<parameter name="foo" />
...
Il est possible d'indiquer une valeur par défaut :
<parameter name="foo" default="20"/>
Voici les différents types de méthodes. La balise <conditions> est décrite plus loin.
Méthode de type select, selectfirst ¶
Déclaration ¶
<method type="select"> <!-- ou type="selectfirst" -->
<parameter />
<conditions />
<order />
<limit />
</method>
Une méthode de type select renvoient une liste d'objets "record", qui ont donc comme propriétés celles indiquées dans la section record. Une méthode de type selectfirst renvoi le premier objet correspondant aux critères.
À noter qu'il n'est pas possible de limiter un select/selectfirst à un nombre réduit de propriétés. En effet, cela n'aurait pas vraiment de sens au niveau du concept de "mapping" et serait même dangereux pour les données puisqu'alors les propriétés non sélectionnées seraient vides dans le record, et si on fait ensuite un update derrière... Si on veut sélectionner un nombre restreint des propriétés définies, la seule possibilité pour le moment est de créer un autre DAO.
On peut ajouter un attribut distinct pour récupérer seulement les éléments distincts.
<method type="select" name="findThem" distinct="true">
..
On peut aussi ajouter un attribut groupby pour ajouter une clause GROUP BY. (à n'utiliser qu'avec mysql, le code généré par jDao n'est pas vraiment compatible avec d'autres bases de données).
<method type="select" name="findThem" groupby="foo">
..
La balise <conditions> (facultative) décrit une condition (la clause WHERE en SQL). Voir la section correspondante plus loin.
On peut aussi ajouter une balise <order> qui permet de spécifier l'ordre des enregistrements récupérés (clause ORDER en SQL). Il faut indiquer une ou plusieurs balises <orderitem>, qui contiennent un attribut property indiquant le nom de la propriété sur lequel l'ordre s'effectue et un attribut way. L'attribut way doit contenir "asc" ou "desc" ou un nom de paramètre de méthode (précédé alors par un $).
<order>
<orderitem property="foo" way="asc" />
</order>
À noter que property peut contenir, soit un nom d'une propriété, soit un nom de paramètre de la méthode (précédé d'un $) qui doit alors contenir un nom de propriété.
Enfin, une balise <limit> optionnelle permet de restreindre le nombre d'enregistrement retournés.
<limit offset="5" count="10" />
Les attributs count et offset contiennent soit un nombre, soit un nom de paramètre de méthode (précédé alors par un $).
<method type="select" name="getFewRecord" >
<parameter name="count"/>
<parameter name="offset"/>
<limit offset="$offset" count="$count"/>
</method>
Utilisation ¶
L'utilisation des méthodes déclarées en XML a été pensée pour être transparente vis-à-vis du développeur qui n'a pas envie de se soucier de la déclaration du DAO.
Reprenons notre méthode getFewRecord. On veut normalement récupérer un tableau en PHP afin de manipuler plus facilement les enregistrements. Rien de plus simple :
$dao = jDao::get('module~list'); // Récupèration du DAO si ce n'est pas fait
$records = $dao->getFewRecord(10, 5); // Appel de la méthode XML avec ses arguments et récupération des données
foreach ($records as $record) // Parcours des données
jLog::log($record->name); // Accès au champ "name" d'un enregistrement
Ainsi, pour chaque méthode XML ajoutée dans le DAO, une méthode est générée et utilisable directement via PHP. Comme pour toute requête SQL, il ne faut pas oublier de "fetcher" les données.
Méthode de type count ¶
<method type="count">
<parameter .../>
<conditions ../>
</method>
ce type de méthode est équivalent à un SELECT COUNT(*), avec les conditions indiquées.
Si on veut plutôt faire un SELECT COUNT(DISTINCT un_champs), il faut indiquer le nom de la propriété dans l'attribut distinct.
Méthode de type delete ¶
<method type="delete">
<parameter .../>
<conditions .../>
</method>
Génère une méthode qui execute une requête DELETE.
Méthode de type update ¶
<method type="update">
<parameter .../>
<conditions .../>
<values .../>
</method>
Ce type de méthode exécute une requête de type UPDATE. En plus des paramètres et des conditions, il faut indiquer les valeurs que l'on met sur telle ou telle propriété avec les balises <value>.
<values>
<value property="foo" value="123"/>
<value property="foo" expr="$myparam"/>
</values>
L'attribut property indique la propriété que l'on va mettre à jour. Comme dans les conditions, l'attribut value doit contenir une valeur. Mais si on veut indiquer une expression SQL ou un paramètre de la méthode, il faut utiliser l'attribut expr.
Clause conditions ¶
Voici la description de la balise <conditions> qui peut être utilisée dans la plupart des méthodes précédentes.
<conditions logic="AND">
<eq property="foo" value="" />
<neq property="foo" value="" />
<lt property="foo" value="" />
<gt property="foo" value="" />
<lteq property="foo" value="" />
<gteq property="foo" value="" />
<like property="foo" value="" />
<isnull property="foo"/>
<isnotnull property="foo"/>
<in property="foo" value="" />
<notin property="foo" value="" />
</conditions>
On peut mettre plusieurs balises <conditions> imbriquées pour faire des groupes or/and. Si l'attribut logic n'est pas spécifié, il vaut AND par défaut. Sinon il doit valoir "OR" ou "AND".
L'attribut value doit contenir une valeur. Le type de cette valeur est celui de la propriété. Si on préfère utiliser une expression SQL ou indiquer un paramètre de méthode, il faut utiliser l'attribut expr.
Cas de in/notin ¶
<in> et <notin> sont les équivalents de foo IN (a, b, c) et foo NOT IN (a, b, c). L'usage de value et expr est différente. Si vous avez une liste de valeurs statiques, vous les mettrez dans l'attribut value comme vous le feriez en SQL :
<in property="foo" value="5,3,2" />
ou
<in property="foo" value="'toto','titi','tata'" />
Vous utiliserez expr quand vous aurez un paramètre de méthode (donc une liste de valeurs dynamiques) :
<in property="foo" expr="$liste" />
Ce paramètre doit obligatoirement contenir un tableau PHP de valeurs. Et l'attribut expr ne peut contenir autre chose qu'un nom de paramètre.
