🧩 ORM Barry

Barry ORM

Barry c'est l'ORM (Object Relation Mapping) intégré dans Bow Framework.

Introduction

info

Un ORM (Object Relation Mapping) est une façon de relier les tables entre elles en utilisant des classes. Chaque enregistrement d'une table représente un objet qui peut être en relation avec d'autres enregistrements.

L'ORM inclus avec Bow Framework fournit une implémentation ActiveRecord simple et élégante pour travailler avec votre base de données. Chaque table de base de données a un "modèle" correspondant qui est utilisé pour interagir avec cette table. Les modèles vous permettent de rechercher des données dans vos tables, ainsi que d'insérer de nouveaux enregistrements.

Dans tout bon framework qui se respecte, il y a un système ORM avec un nom sympathique. Celui de Bow se nomme Barry.

Prérequis

Avant de commencer, assurez-vous de configurer une connexion à la base de données dans config/database.php.

Avant de continuer, veuillez ajouter une migration :

php bow add:migration CreateTodoTable

Ensuite modifiez la migration:

public function up()
{
  $this->create("todos", function (SQLGenerator $table) {
    $table->addIncrement('id');
    $table->addString('title');
    $table->addInteger('status', ["default" => 1]);
    $table->addInteger('budget', ["default" => 0]);
    $table->addTimestamps();
  });
}

Enfin, faites la migration :

php bow migration:migrate

Information

Cette migration sera utilisée pour vous permettre de faire directement les tests sur le modèle App\Models\Todo::class.

Ajouter un modèle

Pour ajouter un modèle, il faut utiliser la ligne de commande php bow avec la commande add:model suivi du nom du modèle.

php bow add:model Todo

Après création du modèle, un fichier du même nom sera créé, dans notre cas Todo.php, à la racine du dossier app/Models.

Voici un aperçu du fichier :

namespace App\Models;

use Bow\Database\Barry\Model;

class Todo extends Model
{
  //
}

Important

Avant d'utiliser le modèle, vérifiez que vous avez configuré votre base de données.

Nom de table

Notez que nous n'avons pas indiqué à Barry quelle table utiliser pour notre modèle Todo. Par convention, en "snake_case", le nom pluriel de la classe sera utilisé comme nom de table à moins qu'un autre nom ne soit explicitement spécifié.

Vous pouvez spécifier manuellement un nom de table en définissant une propriété table sur votre modèle :

namespace App\Models;

use Bow\Database\Barry\Model;

class Todo extends Model
{
  /**
   * Définissez la table associée au modèle.
   *
   * @var string
   */
  protected $table = 'todos';
}

Clés primaires

Barry supposera également que chaque table a une colonne de clé primaire nommée id. Vous pouvez définir une propriété $primary_key protégée pour remplacer cette convention :

namespace App\Models;

use Bow\Database\Barry\Model;

class Todo extends Model
{
  /**
   * La clé primaire associée à la table.
   *
   * @var string
   */
  protected $primary_key = 'id_todo';
}

Récupérer les données

info

Une fois que vous avez créé un modèle et sa table de base de données associée, vous êtes prêt à commencer à récupérer les données. Considérez chaque modèle Barry comme un puissant générateur de requêtes vous permettant d'interroger la table de base de données associée au modèle.

Par exemple:

use App\Models\Todo;

$todos = Todo::all();

foreach ($todos as $todo) {
  echo $todo->title;
}

La méthode find et findBy permet aussi de récupérer les informations:

// Avec find
$todo = Todo::find(1);

// Avec findBy
$todo = Todo::findBy('id', 1);

Remarque

La méthode peut aussi retourner null dans le cas où il n'y a aucun enregistrement trouvé.

Ajout de contraintes supplémentaires

La méthode Barry all retournera tous les résultats dans le tableau du modèle. Étant donné que chaque modèle Barry sert de générateur de requêtes, vous pouvez également ajouter des contraintes aux requêtes, puis utiliser la méthode get pour récupérer les résultats :

$flights = App\Models\Todo::where('status', 'done')
            ->orderBy('title', 'desc')
            ->take(10)
            ->get();

Récupération d'agrégats

Vous pouvez également utiliser les méthodes count, sum, max et d'autres méthodes d'agrégation fournies par le générateur de requêtes. Ces méthodes renvoient la valeur scalaire appropriée au lieu d'une instance de modèle complète:

use App\Models\Todo;

$count = Todo::where('status', 'done')->count();

$max = Todo::where('status', 'done')->max('budget');

Insertion et mise à jour de modèles

INSERT

Pour créer un nouvel enregistrement dans la base de données, créez une nouvelle instance de modèle, définissez des attributs sur le modèle, puis appelez la méthode de sauvegarde:

namespace App\Http\Controllers;

use App\Controllers\Controller;
use App\Models\Todo;
use Bow\Http\Request;

class TodoController extends Controller
{
  /**
   * Créez une nouvelle instance de todo.
   *
   * @param Request $request
   * @return mixed
   */
  public function store(Request $request)
  {
    // Validez la demande...

    $todo = new Todo;

    $todo->title = $request->get('title');
    $todo->budget = $request->get('budget', 0);
    $todo->status = 'pending';

    $todo->save();
  }
}

Dans cet exemple, nous affectons le paramètre de nom de la requête HTTP entrante à les attributs title, budget de l'instance de modèle App\Models\Todo. Lorsque nous appelons la méthode save, un enregistrement sera inséré dans la base de données. Les horodatages created_at et updated_at seront automatiquement définis lorsque la méthode de sauvegarde sera appelée, il n'est donc pas nécessaire de les définir manuellement.

Insert via CREATE

Les objets Active Record peuvent être créés à partir d'un hachage, d'un bloc ou avoir leurs attributs définis manuellement après la création. La nouvelle méthode renverra un nouvel objet tandis que create renverra l'objet et l'enregistrera dans la base de données.

Par exemple, étant donné un utilisateur modèle avec des attributs de nom et d'occupation, l'appel de la méthode create créera et enregistrera un nouvel enregistrement dans la base de données:

use App\Models\Todo;

$user = Todo::create([
  'title' => 'Acheter un ticket metro',
  'budget' => 2000,
  'status' => 'pending',
]);

UPDATE

La méthode save peut également être utilisée pour mettre à jour des modèles qui existent déjà dans la base de données. Pour mettre à jour un modèle, vous devez le récupérer, définir les attributs que vous souhaitez mettre à jour, puis appeler la méthode save. Encore une fois, l'horodatage updated_at sera automatiquement mis à jour, il n'est donc pas nécessaire de définir manuellement sa valeur:

use App\Models\Todo;

$todo = Todo::find(1);

$todo->title = 'Shopping pour Franck';

$todo->save();

Vous pouvez aussi utiliser la méthode update. Cependant, vous devez définir les conditions pour limiter l'impact de la mise à jour.

use App\Models\Todo;

Todo::where('status', 'done')
  ->update(['title' => 'Achat de ticket d\'avion']);

La méthode update attend un tableau de paires de colonnes et de valeurs représentant les colonnes à mettre à jour.

Suppression de données

De même, une fois récupéré, un objet Active Record peut être détruit, ce qui le supprime de la base de données.

use App\Models\Todo;

$todo = Todo::find(1);
$todo->delete();

Si vous souhaitez supprimer plusieurs enregistrements en masse, vous pouvez utiliser la méthode destroyBy ou truncate:

// Delete all todo by id
Todo::deleteBy('id', 'David');

// delete all todo
Todo::truncate();

Il manque quelque chose ?

Si vous rencontrez des problèmes avec la documentation ou si vous avez des suggestions pour améliorer la documentation ou le projet en général, veuillez déposer une issue pour nous, ou envoyer un tweet mentionnant le compte Twitter @bowframework ou sur directement sur le github.