Voir la source de Object-Relational Mapping

La librairie LibOrm (Object-Relational Mapping) est une bibliothèque de correspondance entre la base de données et des objets PHP. Elle facilite la définition des tables de données et les requêtes SQL.

Le module LibOrm est disponible sur CVS : [http://213.215.40.194/cgi-bin/cvsweb.cgi/libraries/LibOrm/libraries/LibOrm]

{{Fonctionnalité|path=LibOrm|addon=LibOrm|version=0.6.3}}


--> Cette page ne recense pas toutes les possibilités de la librairie. Elle donne un aperçu des fonctions permettant de débuter dans l'utilisation de la librairie.

=== Exemple ===
Nous travaillons sur un module d'Ovidentia qui requiert la librairie LibOrm. Pour plus d'explications sur la méthode d'intégration d'une librairie dans un module : [[Fichiers spécifiques des modules]].

Dans notre module, nous gérons 2 tables de données : Contact et AdressePostale. Ces 2 tables sont liées car 1 contact a 1 adresse postale.

==== Les tables de données ====

Définition de la structure de la table AdressePostale. Il est indispensable de terminer le nom de la classe par Set.

<source lang="php">
class monmodule_AddressePostaleSet extends ORM_MySqlRecordSet {
   function __construct() {
      parent::__construct();
      
     $this->setPrimaryKey('id');
     $this->addFields(
        ORM_TextField('rue')->setDescription('Street'),
        ORM_StringField('codepostal', 10)->setDescription('Zip code'),
        ORM_StringField('ville', 60)->setDescription('City')
     );
   }
}
</source>

Définition de la classe AdressePostale en tant qu'enregistrement (record). Lorsque la librairie LibOrm retournera une ligne de la table AdressePostale, la librairie retournera un objet de la classe AdressePostale.
Remarque : si vous n'avez pas besoin de personnaliser la classe d'enregistrement, il n'est pas nécessaire de la créer. Elle sera automatiquement créée par la librairie à partir du nom de la classe AdressePostaleSet.

<source lang="php">
class monmodule_AddressePostale extends ORM_MySqlRecord {
   
}
</source>


Définition de la structure de la table Contact :

<source lang="php">
class monmodule_ContactSet extends ORM_MySqlRecordSet {
   function __construct() {
      parent::__construct();
     
      $this->setPrimaryKey('id');
      $this->addFields(
         ORM_StringField('nom', 80)->setDescription('Nom'),
         ORM_StringField('prenom', 80)->setDescription('Prénom'),
         ORM_StringField('poste', 50)->setDescription('Métier'),
         ORM_StringField('bureau', 15)->setDescription('Bureau'),
         ORM_StringField('telephone', 30)->setDescription('Téléphone'),
         ORM_StringField('fax', 30)->setDescription('Fax'),
         ORM_StringField('mobile', 30)->setDescription('Téléphone Mobile'),
         ORM_StringField('email', 255)->setDescription('E-mail')
      );

      $this->hasOne('addressepostale', 'monmodule_AddressePostaleSet');
   }
}
</source>

Définition de la classe Contact en tant qu'enregistrement (record).

<source lang="php">
class monmodule_Contact extends ORM_MySqlRecord {

}
</source>

=== Utilisation de la librairie et initialisation ===

Après installation de la librairie sur le portail, vous pouvez l'utiliser dans votre code PHP en appelant la fonctionnalité.
Il est nécessaire d'initialiser le back-end (la base de données) qui sera utilisé. En effet la librairie prévoit des requêtes dans différents formats de base de données : MySQL, XML, RSS...

Cet exemple montre l'utilisation du back-end MySQL. Le constructeur de la classe ORM_MySqlBackend prend en paramètre la variable globale d'Ovidentia (objet babDatabase) :

<source lang="php">
bab_functionality::get('LibOrm')->initMySql();
$mysqlbackend = new ORM_MySqlBackend($GLOBALS['babDB']);
ORM_MySqlRecordSet::setBackend($mysqlbackend);
</source>

==== Requêtes : gestion des données ====

Nous avons défini nos tables de données dans les chapitres précédents. Pour les exemples de requêtes les définitions de classes doivent être disponibles dans le code PHP.

===== Insérer des données (équivalent requêtes INSERT dans MySQL) =====

Pour ajouter une donnée (ici une adresse postale), on définit un nouvel enregistrement en utilisant la méthode newRecord() sur la classe de définition (ici monmodule_AdressePostaleSet).

<source lang="php">
$adresseset = new monmodule_AddressePostaleSet();
$adresse = $adresseset->newRecord();
</source>

Les champs définis dans la classe monmodule_AddressePostaleSet seront disponibles sous la forme de variables dans les objets de cette classe. La méthode save() sur l'objet effectuera l'enregistrement de la nouvelle donnée.

<source lang="php">
$adresseset = new monmodule_AddressePostaleSet();
$adresse = $adresseset->newRecord();

$adresse->rue = '45, rue Georges André';
$adresse->codepostal = '54000';
$adresse->ville = 'Nancy';

$adresse->save();
</source>

Remarque :

Dès l'utilisation de la méthode save() sur l'objet, vous travaillez sur la donnée enregistrée. Un nouvel appel à la méthode save() ne créera pas un nouvel enregistrement mais modifiera la donnée en cours :

<source lang="php">
$adresseset = new monmodule_AddressePostaleSet();
$adresse = $adresseset->newRecord();

$adresse->rue = '45, rue Georges André';
$adresse->codepostal = '54000';
$adresse->ville = 'Nancy';

$adresse->save();

$adresse->codepostal = '78000';
$adresse->ville = 'Versailles';

$adresse->save();
</source>

====== Gestion des données liées ======

Nos définitions de tables prévoyaient une liaison entre un contact et une adresse postale. Voici un exemple permettant d'insérer un contact et son adresse automatiquement. Il est nécessaire pour cela de définir une liaison JOIN :

<source lang="php">
$contactset = new monmodule_ContactSet();
$contactset->join('addressepostale');

$contact = $contactset->newRecord();

$contact->nom = 'Martin';
$contact->prenom = 'Henry';
$contact->addressepostale->rue = '45, rue Georges André';
$contact->addressepostale->codepostal = '54000';
$contact->addressepostale->ville = 'Nancy';

$contact->save();
</source>

===== Sélectionner des données (équivalent requêtes SELECT en MySQL) =====

La sélection de données s'effectue par la méthode select() sur l'objet de définition. Il est conseillé d'utiliser la commande foreach pour parcourir les résultats.


Cet exemple montre la sélection de tous les contacts et affiche leurs noms.

<source lang="php">
$contactset = new monmodule_ContactSet();

$contacts = $contactset->select();
foreach ($contacts as $contact) {
    echo $contact->nom;
}
</source>

Cet exemple montre la sélection de tous les contacts dont le prénom est Paul et affiche leurs noms. On passe en paramètre à la méthode select() un critère (objet ORM_Criteria).

<source lang="php">
$contactset = new monmodule_ContactSet();

$contacts = $contactset->select($contactset->prenom->is('Paul'));
foreach ($contacts as $contact) {
    echo $contact->nom;
}
</source>

Cet exemple montre la sélection de tous les contacts dont le prénom est Paul et dont le nom est André et affiche leurs noms. L'opérateur AND permet la création d'un critère à partir de 2 critères.

<source lang="php">
$contactset = new monmodule_ContactSet();
$contactset->join('addressepostale');

$contacts = $contactset->select($contactset->prenom->is('Paul')->_AND_($contactset->nom->startWith('André')));
foreach ($contacts as $contact) {
    echo $contact->nom;
}
</source>

===== Mettre à jour des données (équivalent requêtes UPDATE en MySQL) =====

La modification d'une donnée passe par la méthode save() sur l'objet en cours. La donnée en cours peut provenir d'une requête de sélection ou de création.

Cet exemple montre 2 appels à la méthode save(). Le premier appel créé un nouvel enregistrement. Le deuxième effectue une modification de l'enregistrement.

<source lang="php">
$adresseset = new monmodule_AddressePostaleSet();
$adresse = $adresseset->newRecord(); 
$adresse->rue = '45, rue Georges André';
$adresse->codepostal = '54000';
$adresse->ville = 'Nancy';
 
$adresse->save();
 
$adresse->codepostal = '78000';
$adresse->ville = 'Versailles';
 
$adresse->save();
</source>

Cet exemple montre l'appel à la méthode save() après une requête de sélection. Le code affecte une majuscule au prénom Paul à tous les contacts qui n'en n'avaient pas.

<source lang="php">
$contactset = new monmodule_ContactSet();
$contactset->join('addressepostale');

$contacts = $contactset->select($contactset->prenom->is('paul'));
foreach ($contacts as $contact) {
    $contact->prenom = 'Paul';
    $contact->save();
}
</source>

===== Supprimer des données (équivalent requêtes DELETE en MySQL) =====

Pour supprimer des données, on utilise la méthode delete sur l'objet de définition. Cette méthode prend en paramètre un critère (objet ORM_Criteria).

Dans cet exemple, on supprime tous les contacts dont le prénom est paul :

<source lang="php">
$contactset = new monmodule_ContactSet();

$contacts = $contactset->delete($contactset->prenom->is('paul'));
</source>