Gepi

_Ceci est une traduction libre de la page officielle de la documentation de Propel "/ICI":http://propel.phpdb.org/trac/wiki/Users/Documentation/1.3/BasicCRUD_

 = Opérations de base : C.R.U.D. (create, read, update, delete) = 

 Ce guide tente de montrer comment effectuer les opérations de base sur la base de données en utilisant Propel.

 Les exemples qui suivent supposent que vous avez déjà installé et paramétré Propel. 

 == CREATE == 

 Pour ajouter de nouvelles données dans la base, il faut instancier un des objets générés par Propel et ensuite appeler la méthode setChamp() appropriée. Propel générera le SQL qui va bien pour faire l'insertion. 

 === Simple INSERT ===

 Dans sa forme la plus simple, on crée un nouveau tuple de cette façon : 

<pre>

# php 

 / * Initialiser Propel, etc * / 

 $user = new Utilisateur(); 

 $user->setPrenom("Thomas"); 

 $user->setNom("Belliard"); 

 $user->save();

</pre>

Propel va traduire ces lignes de code par :

<pre>

#! sql 

 INSERT INTO utilisateurs (prenom, nom) VALUES ('Thomas', 'Belliard');

</pre>

 === Gérer les insertions connexes === 

 De plus, Propel sait si un objet a été sauvegardé ou pas. Donc on peut créer plusieurs tuples de plusieurs tables différents et tout sauvegarder une seule fois :

<pre>

 #! php 

 / * Initialiser Propel, etc * / 

 // 1) Créer un Auteur

 include_once 'librairie/Author.php'; 

 $author = new Author(); 

 $author->setFirstName("Leo"); 

 $author->setLastName("Tolstoï"); 

 // Note: ce tuple n'est pas encore dans la base

 // 2) Créer un Editeur

 include_once 'librairie/Publisher.php'; 

 $pub = new Editeur(); 

 $pub->setName("Viking Press"); 

 // Note: ce tuple n'est pas encore dans la base 

 // 3) Créer un livre

 include_once 'librairie/Book.php'; 

 $livre = new livre(); 

 $livre->setTitle("Guerre et Paix"); 

 $livre->setIsbn("0140444173"); 

 $livre->setPublisher($pub); 

 $livre->setAuthor($author); 

 $livre->save();

 // enregistre l'ensemble des 3 objets dans la base avec les dépendances (clés étrangères) qui vont bien ! 

</pre>

 Parce que Propel sait si un objet a été enregistré ou non, il est capable avec save() d'analyser tous les objets avant de les ajouter en gérant les relations à l'objet livre. (Plus d'info à ce sujet sur le site de Propel : "Relationships":http://propel.phpdb.org/trac/wiki/Users/Documentation/1.3/Relationships traduit "ici":http://projects.sylogix.org/gepi/wiki/propel_relations) .

 == RETRIEVE ==

 Récupérer des objets de la base de données, également dénommés _objets_hydratant, comme quand on effectue une requête SELECT pour peupler toutes les propriétés de l'objet peut se faire à l'aide des méthodes statiques PEER pour vérifier si ces enregistrements existent dans la table. Ces classes PEER ne contiennent que des méthodes statiques qui permettent d'effectuer des opérations sur la table.

Il existe plusieurs méthodes pour vous aider à choisir un seul ou plusieurs objets de la base de données. 

 === Récupération par la clé primaire === 

 La façon la plus simple pour récupérer un objet (ligne) de la base de données, est d'utiliser la méthode _retrieveByPK()_. Comme d'habitude, il faut fournir la valeur de la clé primaire en argument à cette méthode.

 ==== La clé primaire est sur une seul colonne ==== 

 Habituellement, votre table aura une seule clé primaire, ce qui signifie que la méthode _retrieveByPK()_ accepte un seul paramètre. 

<pre>

 #! php 

 $firstBook = [[BookPeer]]::retrieveByPK(1); 

 // $firstBook est maintenant un objet livre, ou NULL si aucune correspondance n'a été trouvée. 

</pre>

 ==== La clé primaire est sur plusieurs colonnes ==== 

 Dans certains cas, votre clé primaire est composée de plusieurs colonnes. Dans ce cas, _retrieveByPK()_ acceptera plusieurs paramètres, un pour chaque colonne de clé primaire. 

 Par exemple, si nous avions un tableau, avec une clé primaire à plusieurs colonnes, définie comme ceci: 

<pre>

 #! xml 

    <table name="multicolpk_example" phpName="MultiColPKExample"> 

       <column name="id1" type="INTEGER" primaryKey="true"/> 

       <column name="id2" type="INTEGER" primaryKey="true"/> 

       <! - Les autres colonnes ... -> 

    </ table> 

</pre>

 ... alors votre méthode _retrieveByPK()_ serait invoquée comme ceci: 

<pre>

 #! php 

 $myObject = [[MultiColPKExamplePeer]]::retrieveByPK(1,2); 

</pre>

 ==== Obtenir plusieurs objets par PK ==== 

 Vous pouvez également sélectionner plusieurs objets en fonction de leurs clés primaires, en appelant la méthode générée _retrieveByPKs()_ qui prend en paramètre un tableau de clés primaires: 

<pre>

 #! php 

 $selectedBooks = [[BookPeer]]::retrieveByPKs(array(1,2,3,4,5,6,7));

 // $SelectedBooks est un tableau d'objets

</pre>

 _Il est à noter que ceci ne fonctionne que pour les tables avec une seule colonne de clés primaires._ 

 === Interrogation de la base de données === 

 Pour sélectionner plusieurs lignes par d'autres critères que la clé primaire, nous avons deux choix:

 1) d'utiliser la classe Criteria, ou

 2) d'écrire du SQL personnalisé.

 La classe _Criteria_ offre une approche relativement simple à la construction d'une requête. C'est le meilleur choix pour construire des requêtes simples dans la base, mais pour une requête très complexe, il peut s'avérer plus efficace (et moins douloureux) de simplement utiliser une requête SQL personnalisée pour peupler (hydrate) votre objet Propel. 

 ==== Critères simples ==== 

 Voici quelques exemples de critères simples être utilisé pour renvoyer plusieurs objets. 

 *Exemple 1:* Trouver tous les auteurs dont le prénom est Thomas, mais dont le nom n'est pas Belliard. 

<pre>

 #! php 

 $c = new Criteria(); 

 $c->add(UtilisateurPeer::prenom, "Thomas"); 

 $c->add(UtilisateurPeer::nom, "Belliard", Criteria::NOT_EQUAL); 

 $users = [[UtilisateurPeer]]::doSelect($c); 

 // $users contient un tableau de tous les utilisateurs qui répondent à la requête 

 // {Trad} --> On voit ici toute l'utilité d'utiliser un IDE pour coder avec l'autocomplétion.

</pre>

 ... on obtient les mêmes résultats qu'avec la requête SQL suivante: 

<pre>

 #! sql 

 SELECT * FROM utilisateurs WHERE utilisateurs.prenom = 'Thomas' AND utilisateurs.nom <> 'Belliard';

</pre>

 *Exemple 2:* Trouver tous les auteurs dont le nom est Tolstoy, Dostoevsky, ou Bakhtin

<pre>

 #! php 

$c = new Criteria();

$c->add(AuthorPeer::LAST_NAME, array("Tolstoy", "Dostoevsky", "Bakhtin"), Criteria::IN);

$authors = [[AuthorPeer]]::doSelect($c);

 // $authors contient un tableau des objets auteurs

</pre>

 ... on obtient les mêmes résultats qu'avec la requête SQL suivante: 

<pre>

 #! sql 

 SELECT * FROM author WHERE author.LAST_NAME IN ('Tolstoy', 'Dostoevsky', 'Bakhtin');

</pre>

h3. Utiliser des critères complexes

 Quand vous avez besoin d'exprimer des relations logiques (ET, OU, etc) dans la clause where de la requête, vous devez combiner manuellement chaque objet Criteria() ensemble. Ces clauses sont ensuite ajouter à la requête par la méthode _Criteria->add()_.

 *Exemple 1:* Trouver tous les auteurs dont le prénom est "Leo" et le nom est "Tolstoy", "Dostoevsky", "Bakhtin". 

<pre>

 #! php

$c = new Criteria();

$cton1 = $c->getNewCriterion(AuthorPeer::FIRST_NAME, "Leo");

$cton2 = $c->getNewCriterion(AuthorPeer::LAST_NAME,  array("Tolstoy", "Dostoevsky", "Bakhtin"), Criteria::IN);

// On combine toutes ces clauses...

$cton1->addOr($cton2);

// ...qu'on ajoute au critère (sic), à la requête quoi ;)

$c->add($cton1);

</pre>

 ... résultats dans la requête SQL comme: 

<pre>

 #! sql 

 SELECT ... FROM author WHERE (author.FIRST_NAME = 'Leo' OR author.LAST_NAME IN ('Tolstoy', 'Dostoevsky', 'Bakhtin'));

</pre>

 Il y a aussi des_Criteria_raccourcis si vous souhaitez effectuer une requête avec les relations logiques entre les clauses de référence sur _la même colonne_. 

 *Exemple 2:* Trouver tous les auteurs dont le prénom est «Leo» ou «Karl» 

 Utiliser la classe Criteria(), cela ressemble à: 

<pre>

 #! php 

$c = new Criteria();

$cton1 = $c->getNewCriterion(AuthorPeer::FIRST_NAME, "Leo");

$cton2 = $c->getNewCriterion(AuthorPeer::FIRST_NAME, "Karl");

// on les combine

$cton1->addOr($cton2);

// ...et on les ajoute aux critères de la requêtes

$c->add($cton1);

</pre>

 _Criteria_ propose un raccourci pour cela : 

<pre>

 #! php 

$c = new Criteria();

$c->add(AuthorPeer::FIRST_NAME, "Leo");

$c->addOr(AuthorPeer::FIRST_NAME, "Karl");

</pre>

*ATTENTION*

 Il est important de noter que cette méthode a un certain nombre de limites - surtout qu'ils ne fonctionnent que pour les relations avec une seule colonne. D'après l'auteur de cette classe, il est conseillé de ne pas utiliser ces méthodes lorsque vous avez besoin d'exprimer des clauses particulières car elles masquent les réelles relations qui existent entre les objets Criteria et peuvent donc s'avérer difficiles à débugguer. (Ces méthodes vont probablement changer ou disparaître dans Propel 2). 

 === Utiliser du SQL personnalisé ===

 Propel est conçu pour travailler avec vous plutôt que contre vous. Dans de nombreux cas, la rédaction d'une requête complexe en utilisant les _Criteria_ finit par faire désordre et difficile à comprendre ou à maintenir un niveau des requêtes SQL. A certains moments, si la requête est complexe, il vaut mieux la coder en dur ({TRAD} d'autant que dans Gepi, on utilise que [[MySql]]).

<--TRAD reste à traduire vraiment (et à comprendre aussi)

 Ainsi, avec seulement un peu plus de travail, vous pouvez également obtenir des objets de votre base de données en utilisant SQL. Utiliser SQL pour interroger la base de données nous introduit à la populateObjects généré_()_méthode dans notre classes Peer - qui est appelé dans les coulisses par la doSelect_()_méthode. Cette méthode attend d'être adopté une créole_!_Objet [[ResultSet]], indexé numériquement (c'est-à-dire qui a été créé à l'aide! ResultSet:: FETCHMODE_NUM option_à executeQuery ()_).

TRAD-->

 *Exemple 1:* Utilisez des sous-sélections pour peupler la base de données 

<pre>

 #! php 

$con = Propel::getConnection(DATABASE_NAME);

$sql = "SELECT books.* FROM books WHERE NOT EXISTS (SELECT id FROM review WHERE book_id = book.id)";  

$stmt = $con->prepare($sql);

$stmt->execute();

$books = [[BookPeer]]::populateObjects($stmt);

</pre>

 Des choses importantes à retenir lorsque vous utilisez du SQL personnalisé pour remplir Propel: 

   *! ResultSet colonne doit être indexé numériquement 

   *! ResultSet doit contenir toutes les colonnes de l'objet 

   *! ResultSet doit avoir les colonnes _dans le même ordre_, telles qu'elles sont définies dans le (((schema.xml))) fichier 

 == METTRE À JOUR (update) == 

 Mise à jour de la base de données comporte essentiellement des lignes de récupérer des objets, de modifier le contenu, puis les enregistrer. Dans la pratique, pour Propel, il s'agit d'une combinaison de ce que nous avons déjà vu dans le récupérer et créer des sections. 

<pre>

 #! php 

// 1) On récupère un objet par sa clé primaire

$cours = edtCourPeer::retrieveByPK(1);

// 2) On met à jour les valeurs et on sauvegarde

$cours->setDuree(4);

$cours->save();

</pre>

 Il n'y a vraiment pas grand-chose de bien plus que cela. Bien sûr, vous pouvez également mettre à jour les relations d'une manière similaire à ce qui a déjà été démontré dans la section CREATE. 

<pre>

 #! php 

/* initialize Propel, etc. */

// 1) On récupère un auteur

$author = [[AuthorPeer]]::retrieveByPK(1);

// 2) On récupère un livre

$book = [[BookPeer]]::retrieveByPK(1);

// 3) Et on attribut ce livre à cet auteur

$book->setAuthor($author);

$book->save();

</pre>

h2. DELETE 

 Suppression d'objets peut être accompli en utilisant les classes Peer ou l'objet classes. 

 === En utilisant Peer ===

 Vous pouvez utiliser les méthodes générées _doDelete()_ de la classe Peer pour supprimer des enregistrements dans la table. Vous pouvez passer à cette méthode une clé primaire, une instance de l'objet, ou même un objet _Criteria_ (mais ce n'est pas très utile, puisque vous ne pouvez supprimer que par la clé primaire). 

 *Exemple 1:* Supprimer à l'aide de la clé primaire 

<pre>

 #! php

 [[EdtCoursPeer]]::doDelete(1);

 // et la ligne de la table edt_cours dont id_cours = 1 est effacée. 

</pre>

 *Exemple 2:* Supprimer à l'aide de l'objet instancié 

<pre>

 #! php 

$book = [[BookPeer]]::retrieveByPK(1);

[[BookPeer]]::doDelete($book);

</pre>

 === En utilisant directement les objets ===

 Par souci de cohérence avec d'autres C.R.U.D. opérations, vous pouvez également supprimer la ligne d'une base de données à l'aide de la classe d'objets. Certaines personnes préfèrent le faire de cette façon, l'instanciation d'un objet, puis appeler la méthode _delete()_. D'autres estiment que cela est "bizarre", car alors vous êtes à gauche avec un objet qui ne fait point à la ligne une base de données. Quel que soit - vous êtes libre de choisir:) 

<pre>

 #! php 

 $student = [[ElevePeer]]::retrieveByPK(1); 

 $student->delete(); 

 // (Et maintenant vous devez vous rappeler que vous ne pouvez plus utiliser cet élève car il n'existe plus).

L'autre intérêt est que on peut ajouter une méthode publique [[EleveDelete]]() dans laquelle on pourra vérifier tous les enregistrements liés à cet utilisateur.

</pre>

"A la page suivante, vous trouverez des explications sur les relations da la bdd":http://projects.sylogix.org/gepi/wiki/propel_relations.