Section courante

A propos

Section administrative du site

Modèles

Les modèles sont la base de chaque application, car chaque application contient des données. PHPDevShell tente de rendre la gestion des données dans la structure MVC aussi simple que possible. Nous voyons toutes les données comme des objets, et ces objets peuvent être n'importe quelle forme de données. S'ils contiennent des informations, ils peuvent être interrogés et les données seront renvoyées. Les requêtes peuvent inclure des requêtes de base de données réelles, des fonctions ou des données définies manuellement.

Notez que lorsque vous faites référence à un dossier ou à un fichier, cela signifie qu'il s'agit d'un dossier ou d'un fichier à l'intérieur de votre propre dossier de plugiciel.

Appeler une requête de données

Peu importe que vous soyez dans une classe d'assistance, un contrôleur ou même un modèle lui-même, vous pouvez toujours exécuter une requête en utilisant :

  1. $this->db->invokeQuery('nameOfDataClass');

La requête que vous appelez se trouve dans un fichier portant le même nom que votre contrôleur. Par exemple, si vous avez un contrôleur appelé :

my-controller.php

le modèle avec toutes les requêtes sera appelé :

my-controller.query.php

dans le dossier models.

Un fichier modèle peut également être réutilisé dans d'autres controllers/models/classes en incluant simplement le nom de fichier à partir de n'importe quel autre endroit où il est nécessaire.

Chaque requête de données est une classe à part entière, ce qui signifie que pour chaque requête de données, vous créerez une classe comme celle-ci :

  1. class nameOfDataClass extends PHPDS_query {
  2.     /* La classe étend toujours PHPDS_query */
  3.     /**
  4.      * Remplacer l'appel
  5.      * @return string
  6.      */
  7.     public function invoke() {
  8.         $array = array('Valeur de données 1', 'Valeur de données 2');
  9.         return $array;
  10.     }
  11. }

Maintenant, chaque fois que nous appelons :

  1. $array=$this->db->invokeQuery('nameOfDataClass');

nous aurons les données que 'nameOfDataClass' renvoie.

L'utilisation de la fonction publique facultative invoke() à partir de la classe de requête indique toujours à la classe que vous souhaitez renvoyer des données personnalisées. Vous pouvez soit manipuler les données d'une requête de base de données, soit renvoyer des données n'ayant rien à voir avec la base de données.

La couche de base de données

Le système de requête ne s'arrête pas là. Il vous permet d'interroger la base de données avec des fonctions de base de données puissantes et faciles à utiliser avec très peu d'effort.

Faisons donc notre première requête de lecture. Obtenons simplement les résultats de la base de données. Un fichier de requête peut avoir plusieurs objets de classe, dans notre fichier d'exemple my-controller.query.php nous écrivons :

  1. class exampleQuery extends PHPDS_query {
  2.     protected $sql = "SELECT id, example_name, example_note FROM _db_ExamplePlugin_example";
  3. }

Maintenant, si nous appelons ces données depuis notre contrôleur avec quelque chose comme ceci :

  1. $array = $this->db->invokeQuery('exampleQuery');

Cela renverra un tableau prêt à être utilisé ou bouclé.

Remarque : Lisez le commutateur de requête de données $keyField ci-dessous pour voir comment les résultats sont renvoyés par la requête.

Transmission de données à la requête

Évidemment, la vie n'est pas si simple et nous devrons généralement modifier les conditions SQL dans notre requête. Comment gérerions-nous cela ?

Le modèle de requête gère tout ce que vous lui envoyez. Lui transmettre autant de variables que possible est en fait très simple.

Regardons l'exemple :

  1. class exampleQuery extends PHPDS_query {
  2.     protected $sql = "SELECT id, example_name, example_note FROM _db_ExamplePlugin_example WHERE example_name = '%s' AND example_note = '%s'";
  3. }

Comme on peut le voir, dans cet exemple, nous devons transmettre deux valeurs à la requête de base de données pour la clause WHERE. Pour ce faire, c'est simple :

  1. $array = $this->db->invokeQuery('exampleQuery', 'Sylvain', 'Hello');

Maintenant, 'Sylvain' et 'Hello' seront inclus dans la condition WHERE et seuls les résultats requis seront renvoyés. Les variables sont utilisées dans l'ordre passé. Ainsi, Sylvain est la première variable passée, elle sera donc utilisée avec la première occurrence d'un spécificateur de type de données, dans ce cas le %s dans example_name.

Remarque : Le %s signifie chaîne et est un spécificateur de type de données spécifiant le type de données transmises dans la requête (%s pour chaîne de caractères, %u pour entier non signé,...). Ce sont les mêmes que ceux que la fonction sprintf de PHP utiliserait.

Ce cas d'utilisation est simple mais présente deux problèmes : vous devez connaître l'ordre des paramètres, et si un paramètre est utilisé deux fois, vous devez le transmettre deux fois. Pour éviter cela, utilisez simplement des paramètres nommés :

  1. class exampleQuery extends PHPDS_query {
  2.     protected $sql = "SELECT id, example_name, example_note FROM _db_ExamplePlugin_example WHERE example_name = '%(name)s' AND example_note = '%(note)s'";
  3. }

Pour utiliser cette requête, vous devez utiliser un tableau associatif :

  1. $array = $this->db->invokeQueryWith('exampleQuery', 
  2.         array('name' => 'Sylvain', 'note' => 'Hello')
  3. );

Remarque : vous pouvez demander à la base de données d'appeler une requête de deux manières, soit en ajoutant les paramètres directement dans l'appel de fonction, soit AVEC un tableau. Notez la différence :

  1. $array = $this->db->invokeQuery('exampleQuery', 'Sylvain', 'Hello')
  2.     );
  3. $array = $this->db->invokeQueryWith('exampleQuery', 
  4.         array('name' => 'Sylvain', 'note' => 'Hello')
  5.     );

Commutateurs de requête de données

L'objet de requête vous permet de demander la manipulation de données via des commutateurs simples. Il existe quelques commutateurs disponibles. Les voici avec une brève explication :

  1. /**
  2.  * Le nom du champ à utiliser comme clef.
  3.  *
  4.  * Par défaut, cette valeur est définie sur la valeur spéciale '__auto__', ce qui signifie que la classe
  5.  * déterminera automatiquement quel champ/colonne doit être utilisé comme clef
  6.  * Si vous souhaitez que les clefs de tableau renvoyées soient définies sur une valeur de champ/colonne
  7.  * spécifique, il vous suffit de spécifier le nom de ce champ/colonne dans $keyField
  8.  * Si vous souhaitez que les clefs de tableau renvoyées soient définies sur un index numérique
  9.  * commençant à 0, vous devez définir $keyField=false
  10.  * @var string
  11.  */
  12. protected $keyField = '__auto__';
  13.  
  14. /**
  15.  * Faire d'un champ le point d'intérêt
  16.  *
  17.  * Ce champ modifie la façon dont certains tableaux sont renvoyés :
  18.  * - si $focus contient un nom de champ, une ligne sera la valeur de ce champ (scalaire) au lieu d'un tableau de toutes les valeurs de la ligne
  19.  * - si la ligne ne contient pas de champ, une valeur vide est utilisée pour la ligne
  20.  * @var string
  21.  */
  22. protected $focus = ''; /* peut être vide pour « non » ou toute autre valeur pour le nom du champ */
  23.  
  24. /**
  25.  * supprime toute ligne sans contenu
  26.  * @var boolean
  27.  */
  28. protected $noEmptyRow = false;
  29.  
  30. /**
  31.  * Lignes directrices pour le typage/la conversion forcée des données de résultat
  32.  *
  33.  * @var string | array of strings
  34.  */
  35. protected $typecast;
  36.  
  37. /**
  38.  * La première ligne du résultat est renvoyée au lieu d'un tableau d'une seule ligne
  39.  *
  40.  * @var boolean
  41.  */
  42. protected $singleRow = false;
  43.  
  44. /**
  45.  * Échapper automatiquement aux mauvais caractères pour tous les paramètres entrants
  46.  * @var boolean
  47.  */
  48. protected $autoProtect = false;
  49.  
  50. /**
  51.  * Au lieu du résultat de la requête, renvoie le last_insert_id()
  52.  * @var boolean
  53.  */
  54. protected $returnId = false;
  55.  
  56. /**
  57.  * Renvoie une valeur du champ demandé de la ligne demandée
  58.  * @var boolean
  59.  */
  60. protected $singleValue = false;

Pour demander la manipulation des données dans une requête, incluez simplement le commutateur dans la classe d'objet de base de données, par exemple :

  1. class editExampleQuery extends PHPDS_query {
  2.     protected $sql = "SELECT example_name FROM _db_ExamplePlugin_example WHERE id = %u";
  3.     protected $singleValue = true;
  4. }

Nous demandons au système de requête d'appeler la requête, mais de ne pas renvoyer de tableau, mais uniquement la valeur requise. Désormais, seul le nom de la colonne sera renvoyé directement.

Pour aller plus loin dans l'exemple, disons que nous voulons renvoyer l'ID de la ligne que nous venons d'insérer, nous pouvons également ajouter le commutateur suivant :

  1. class writeExampleQuery extends PHPDS_query {
  2.     protected $sql = "INSERT INTO _db_ExamplePlugin_example (id, example_name, example_note, alias) VALUES (%u, '%s', '%s', '%s')";
  3.     protected $returnId = true;
  4. }

Notez que %u et %s sont des spécificateurs de type de données (string=%s et unsigned integer=%u). Ce sont les mêmes que ceux que sprintf utiliserait.

Appelons la requête et obtenons l'ID renvoyé :

  1. $id = $this->db->invokeQuery('exampleQuery', '', 'Sylvain', 'Quelques remarques', 'hello');
  2. /* $id contient désormais l'ID de base de données renvoyé. */

Vérification ou modification des paramètres avant l'exécution de la requête

Tous les paramètres d'une requête ne doivent pas être spécifiés lors de son appel. Par exemple, une requête peut utiliser l'ID utilisateur actuel. Regardons cet exemple étendant la requête ci-dessus :

  1. class editMeExampleQuery extends editExampleQuery {
  2.      
  3.     public function checkParameters(&$parameters = null) {
  4.         $me = $this->user->currentUserID();
  5.         $parameters = array($me);
  6.  
  7.         return true;
  8.     }
  9. }

La méthode checkParameters() est appelée juste avant que la requête ne soit effectivement envoyée à la base de données. Elle permet à l'objet de requête de vérifier les valeurs des paramètres de l'appelant et/ou d'injecter ses propres valeurs. Elle peut également empêcher l'envoi de la requête (si par exemple certains paramètres sont manquants).

Comme vous pouvez également le voir dans cet exemple, les requêtes sont de véritables entités OOP, et bénéficient donc de tous les mécanismes comme l'extension d'une classe existante.

Vérification ou modification des résultats après l'exécution de la requête

Les données extraites de la base de données ont parfois besoin d'être un peu peaufinées avant d'être renvoyées à l'appelant. Un objet de requête a la possibilité de s'assurer que ses résultats sont conformes à ce que l'appelant attend. Voir cet exemple :

  1. class editPrettyExampleQuery extends editExampleQuery {
  2.      
  3.     public function checkResults(&$results = null)
  4.     {
  5.         return (is_string($results)) ? "Utilisateur '$result'" : false;
  6.     }
  7. }

La méthode checkResults() permet à la requête de vérifier et/ou de modifier les données de résultat avant de les renvoyer. Dans ce cas, elle ajoute le mot "User" avant le nom d'utilisateur si la requête en a renvoyé un, ou signale une erreur (en renvoyant False) dans le cas contraire.

Amélioration supplémentaire des objets de base de données avant qu'ils ne soient renvoyés

Comme tout le reste dans PHPDevShell, la requête peut être remplacée. Dans de nombreux cas, vous souhaiterez manipuler des données, améliorer davantage les requêtes et filtrer vos données avant qu'elles ne soient renvoyées à ce qui les a demandées.

Pour ce faire, c'est simple, vous allez remplacer l'appel (en utilisant la fonction publique invoke()), effectuer la requête et renvoyer les données. Pour remplacer l'appel, nous allons procéder ainsi :

  1. class exampleQuery extends PHPDS_query {
  2.     protected $sql = "SELECT id, example_name, example_note FROM _db_ExamplePlugin_example WHERE example_name = '%s' AND example_note = '%s'";
  3.  
  4.     /**
  5.      * Remplacer l'appel
  6.      * @return string
  7.      */
  8.      /* REMARQUE : l'ajout de cette «public function invoke» est la façon dont nous remplaçons et manipulons les données renvoyées par la requête SQL. */
  9.  
  10.     public function invoke($parameters)
  11.     {
  12.         /* Nous sommes maintenant dans une nouvelle instance de substitution d'appel. Commençons par capturer les données qui sont transmises aux paramètres. */
  13.         list($example_name, $example_note) = $parameters;
  14.          
  15.         /* Nous pouvons maintenant manipuler les données, supprimons les espaces blancs de $example_note à titre d'exemple. */
  16.         $example_note = trim($example_note);
  17.  
  18.         /* Nous pouvons maintenant effectuer la requête normalement et continuer à manipuler les données. Pour ce faire, nous effectuons l'appel d'origine. */
  19.         $array = parent::invoke(array($example_name, $example_note));
  20.  
  21.         /* Nous pouvons maintenant boucler les données et en faire ce que nous voulons. */
  22.         foreach ($array as $values) {
  23.             $id = $values['id'];
  24.             $name = $values['example_name'];
  25.             $count ++;
  26.             $new_array[] = array($id, $name, $count);
  27.         }
  28.      
  29.         /* Nous pouvons même faire plus de requêtes à partir d'ici. */
  30.         $this->db->invokeQuery('MoreQueries');
  31.         return $new_array;
  32.     }
  33. }

Comme vous pouvez le voir, vous avez vraiment le contrôle total. N'oubliez pas que vous pouvez invokeQueries dans d'autres requêtes, ou inclure n'importe quel fichier .query.php dans n'importe quel autre fichier, ce qui vous permet de réutiliser les requêtes encore et encore.

Passer un tableau de valeurs au lieu de valeurs individuelles

Que se passe-t-il si j'ai un tableau de valeurs que je souhaite transmettre avec invokeQuery, au lieu de transmettre des valeurs individuelles ? Disons par exemple :

  1. $where_clause = array('Sylvain', 'Hello');
  2. $array = $this->db->invokeQuery('exampleQuery', $where_clause);

Étant donné que les valeurs transmises sont placées dans un tableau, nous devons remplacer l'appel pour les extraire. Notez dans le code ci-dessous qu'il n'y a qu'un seul changement. Voir les remarques :

  1. class exampleQuery extends PHPDS_query {
  2.     protected $sql = "SELECT id, example_name, example_note FROM _db_ExamplePlugin_example WHERE example_name = '%s' AND example_note = '%s'";
  3.  
  4.     /**
  5.      * Remplacer l'appel
  6.      * @return string
  7.      */
  8.     /* REMARQUE : l'ajout de cette «public function invoke» est la façon dont nous remplaçons et manipulons les données renvoyées par la requête SQL. */
  9.     public function invoke($parameters)
  10.     {
  11.     /* Étant donné que nous avons transmis un tableau de valeurs, ce tableau sera indexé dans un tableau à l'index [0], nous devons donc les récupérer.
  12.      * REMARQUE : Le seul changement apporté au code ci-dessous est que nous avons modifié ceci :
  13.      * = parameters;
  14.      * à ceci :
  15.      * = $parameters['0'];
  16.      */
  17.         /* Nous sommes maintenant dans une nouvelle instance de substitution d'appel. */
  18.         /* Commençons par capturer les données étant transmises aux paramètres. */
  19.         list($example_name, $example_note) = $parameters['0'];
  20.          
  21.         /* Nous pouvons maintenant manipuler les données, supprimons les espaces blancs de $example_note à titre d'exemple. */
  22.         $example_note = trim($example_note);
  23.  
  24.         /* Nous pouvons maintenant effectuer la requête normalement et continuer à manipuler les données. Pour ce faire, nous effectuons l'appel d'origine. */
  25.         $array = parent::invoke(array($example_name, $example_note));
  26.  
  27.         /* Nous pouvons maintenant boucler les données et en faire ce que nous voulons. */
  28.         foreach ($array as $values) {
  29.             $id = $values['id'];
  30.             $name = $values['example_name'];
  31.             $count ++;
  32.             $new_array[] = array($id, $name, $count);
  33.         }
  34.      
  35.         /* Nous pouvons même faire plus de requêtes à partir d'ici. */
  36.         $this->db->invokeQuery('MoreQueries');
  37.         return $new_array;
  38.     }
  39. }

Enregistrer une classe

Parfois, les modèles deviennent complexes et le même modèle est utilisé encore et encore. Lorsque c'est le cas, il est fortement recommandé d'enregistrer une classe à la place, d'ajouter la classe dans includes, puis de l'appeler avec la méthode factory.

C'est plus simple qu'il n'y paraît. Nous allons d'abord créer la classe dans le dossier includes de vos plugins. La classe doit être nommée avec .class.php à la fin pour permettre le chargement à la demande.

Appelons donc cette classe :

includes/myClass.class.php

De toute évidence, une classe d'assistance doit avoir son propre fichier de modèles pour effectuer ses requêtes, cela se fait exactement comme avec les contrôleurs normaux, dans le dossier racine des modèles que nous ajoutons :

models/myClass.query.php

Vous pouvez maintenant invoquer des requêtes à partir de votre classe d'aide appelée myClass.class.php comme vous vous y attendriez.

La classe d'aide est généralement appelée à partir du contrôleur ou du fichier modèle, mais il n'y a pas d'emplacement approprié pour l'appeler, juste là où elle est nécessaire. Une classe d'aide doit commencer par le nom que vous avez donné au fichier, elle doit également étendre PHPDS_dependant, ce qui lui permet de partager des ressources :

  1. class myClass extends PHPDS_dependant
  2. {
  3.     public function someMethod ()
  4.     {
  5.         /* Nous pouvons également appeler des requêtes. */
  6.         $name = $this->db->invokeQuery('getName');
  7.         return "Bonjour $name";
  8.     }
  9. }

Appeler des classes d'aide est également facile.

Remarque : vous souhaiterez peut-être enregistrer votre classe dans votre fichier de configuration de plugiciels, ce qui vous permettra de partager votre classe avec tous vos plugiciels.

Appelons notre aide :

  1. $myClass = $this->factory('myClass');
  2. echo $myClass->someMethod();

Transactions et verrouillage de ligne

Dans certaines situations, vous devrez utiliser START TRANSACTION et COMMIT pour effectuer une requête de base de données et verrouiller une ligne afin que personne d'autre ne puisse y accéder jusqu'à ce que vous ayez terminé. Si vous utilisez MySQL, le moteur InnoDB prend en charge ce type de transaction et de verrouillage de ligne.

Remarque : de nombreux serveurs utilisant MySQL ont le moteur par défaut défini sur MyISAM. Le moteur MyISAM ne peut pas effectuer de transactions ou de verrouillage de ligne. Vous devez utiliser un moteur comme InnoDB prenant en charge les transactions et le verrouillage de ligne.

Prenons un exemple dans lequel nous devons récupérer un numéro unique et nous assurer que personne d'autre ne récupère ce même numéro. Voici les étapes à suivre :

  1. Utilisez START TRANSACTION.
  2. Utilisez SELECT avec FOR UPDATE pour verrouiller la ligne et récupérer le numéro.
  3. UPDATE la ligne avec un nouveau numéro pour la personne suivante.
  4. Utilisez COMMIT pour déverrouiller la ligne pour les autres.

Exemple de DATABASE TABLE

Voici le code SQL pour la table de base de données de test que nous allons utiliser dans cet exemple :

  1. CREATE TABLE `pds_test_unique_number` (
  2.   `id` int(11) NOT NULL AUTO_INCREMENT,
  3.   `prefix` text COLLATE utf8_unicode_ci NOT NULL,
  4.   `unique_number` int(11) NOT NULL,
  5.   PRIMARY KEY (`id`)
  6. ) ENGINE=InnoDB  DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;
  7.  
  8. INSERT INTO `pds_test_unique_number` (`id`, `prefix`, `unique_number`) VALUES (1, 'ABC', 1000001);

Exemple de fichier CONTRÔLEUR

Notre fichier contrôleur ressemblera à ceci :

  1. <?php
  2. class getUniqueNumber extends PHPDS_controller {
  3.     public function execute()  {
  4.         /* Donnez-lui un joli titre */
  5.         $this->template->heading(_('GET UNIQUE NUMBER'));
  6.  
  7.         /* Appelez notre requête qui renverra un identifiant unique */
  8.         $unique_number = $this->db->invokeQuery('myPlugin_getNewUniqueId');
  9.  
  10.         /* Appeler le fichier de gabarit */
  11.         $view = $this->factory('views');
  12.         $view->set('unique_number', $unique_number);
  13.         $view->show();
  14.     }
  15. }
  16. return 'getUniqueNumber';

Exemple de fichier MODELE

Notre fichier modèle ressemblera à ceci :

  1. <?php
  2. class myPlugin_getNewUniqueId extends PHPDS_query {
  3.     public function invoke($params) {
  4.          /* Nous devons START TRANSACTION pour pouvoir verrouiller la ligne. */
  5.          /* REMARQUE : pour verrouiller une ligne avec SELECT, vous devez utiliser FOR UPDATE. */
  6.  
  7.         $this->db->startTransaction();
  8.  
  9.         /* Obtenez le prochain identifiant unique */
  10.         $results = $this->db->invokeQuery('myPlugin_getNextAvailableUniqueId');
  11.  
  12.         /* Extraire l'ID de ligne et l'ID unique de la requête renvoyée */
  13.         $id = $results['id'];
  14.         $unique_id = $results['unique_id']; 
  15.          
  16.         /* Augmentez la partie numérique de l'identifiant d'un dans le tableau pour la personne suivante */
  17.         $this->db->invokeQuery('myPlugin_increaseUniqueIdByOne', $id);
  18.  
  19.         /* Il faut s'engager pour pouvoir déverrouiller la ligne */
  20.         $this->db->endTransaction();
  21.          
  22.         /*retourne $id; */
  23.         return $unique_id;
  24.     }
  25. }
  26.  
  27. class myPlugin_getNextAvailableUniqueId extends PHPDS_query {
  28.     protected $sql = "SELECT id,prefix,unique_number FROM pds_test_unique_number LIMIT 1 FOR UPDATE;";
  29.     protected $keyField=false;
  30.  
  31.     public function invoke($params) {
  32.         /* Appelez la requête de base de données. */
  33.         /* REMARQUE : la requête SELECT doit utiliser FOR UPDATE pour verrouiller la ligne. */
  34.         $results = parent::invoke();
  35.          
  36.         /* Obtenons l'ID de ligne de base de données qui a été utilisé afin que nous puissions le mettre à jour ultérieurement */
  37.         $id = $results[0]['id'];
  38.          
  39.         /* L'ID UNIQUE est une combinaison des deux champs suivants, alors mettons-les ensemble. */
  40.         $unique_id = $results[0]['prefix'].$results[0]['unique_number'];
  41.   
  42.         /* Renvoyer les résultats */
  43.         return array('id' => $id, 'unique_id' => $unique_id);;
  44.     }    
  45. }
  46.  
  47. class myPlugin_increaseUniqueIdByOne extends PHPDS_query
  48. {
  49.     /* Cela incrémentera le champ spécifié d'un pour la personne suivante. */
  50.     protected $sql = "UPDATE pds_test_unique_number SET unique_number = unique_number + 1 WHERE id=%u LIMIT 1;";
  51. }

N'oubliez pas que les modèles peuvent être réutilisés en incluant simplement le modèle d'un contrôleur dans un autre contrôleur à l'aide de PHP include standard :

  1. require_once 'plugins/ExamplePlugin/models/someModel1.query.php';
  2. require_once 'plugins/ExamplePlugin/models/someModel2.query.php';
  3. /* Maintenant, nous pensons utiliser leurs appellations. */
  4. $this->db->invokeQuery('queryFromModel1');
  5. $this->db->invokeQuery('queryFromModel2');

Exemple de fichier VUE

Notre fichier view ressemblera à ceci :

  1. L'identifiant unique est : {$unique_number}

Dernière mise à jour : Mardi, le 15 octobre 2024