Construction de requêtes SQL avec Query Builder

Introduction

Bow fournit une API liée à la construction de requêtes. La méthode table permet de construire une requête SQL en se basant sur le nom de la table et retourne une instance de Bow\Database\QueryBuilder::class.

use Bow\Database\Database

$builder = Database::table('users');
// => Instance \Bow\Database\QueryBuilder::class

Vous pouvez aussi utiliser le helper app_db_table:

$builder = app_db_table('users');

Sur l'instance de la QueryBuilder de Bow, il y a plusieurs méthodes qui vont vous permettre de construire une requête SQL. Par exemple, la méthode toSql qui permet d'afficher la requête construite.

$builder->toSql();
// select * from `users`

Récupérer les informations

Pour récupérer les informations avec le builder, vous devez utiliser la méthode get qui retourne une collection, first qui retourne null ou un objet stdclass et last qui se comporte comme first sauf qu'il retourne plutôt le dernier élément du résultat de l'exécution de la requête.

Exemple avec get

$builder = Database::table('users');

$users = $builder->get();

foreach ($users as $user) {
  echo $user->name;
}

Projection de colonnes

Vous pouvez passer un tableau à get qui est une liste des colonnes de la projection comme ceci : $builder->get(['name']).

Exemple avec first

$user = app_db_table('users')->first();

// Vide
is_null($user)
// Ok
echo $user->name;

Exemple avec last

$user = $builder->last();

Ajoutez des restrictions

Restriction simple

Avec le builder, vous pouvez ajouter des restrictions simples sur la construction de la requête SQL avec la méthode where.

$users = app_db_table('users')->where('id', 1)->get();

$users = app_db_table('users')->where('id', '!=', 1)->get();

La clause OR

Vous pouvez enchainer la restriction en ajoutant un or dans votre requête. La méthode orWhere vous permet de faire cela:

$users = app_db_table('users')->where('id', 1)->orWhere('name', 'Papac')->get();

Vous pouvez voir le result de la construction de la requête avec la méthode toSql.

$sql = app_db_table('users')->where('id', 1)->orWhere('id', 1)->toSql();
// => select * from `users` where id = 1 or id = 3;

Clauses additionnelles

whereNull / whereNotNull

La méthode whereNull vérifie que la valeur de la colonne donnée est NULL:

$users = app_db_table('users')->whereNull('name')->get();

La méthode whereNotNull vérifie que la valeur de la colonne n'est pas NULL:

$users = app_db_table('users')->whereNotNull('age')->get();

whereIn / whereNotIn

La méthode whereIn vérifie que la valeur d'une colonne donnée est contenue dans le tableau donné:

$users = app_db_table('users')->whereIn('age', [27, 30])->get();

La méthode whereNotIn vérifie que la valeur de la colonne donnée n'est pas contenue dans le tableau donné:

$users = app_db_table('users')->whereNotIn('age', [27, 30])->get();

whereBetween / whereNotBetween

La méthode whereBetween vérifie que la valeur d'une colonne est comprise entre deux valeurs:

$users = app_db_table('users')->whereBetween('votes', [1, 100])->get();

La méthode whereNotBetween vérifie que la valeur d'une colonne se situe en dehors de deux valeurs:

$users = app_db_table('users')->whereNotBetween('votes', [1, 100])->get();

Ordonner, Grouper, et limiter

orderBy

La méthode orderBy vous permet de trier le résultat de la requête en fonction d'une colonne donnée. Le premier argument de la méthode orderBy devrait être la colonne que vous souhaitez trier, tandis que le second argument contrôle le sens du tri et peut être asc ou desc:

$users = app_db_table('users')->orderBy('name', 'desc')->get();

groupBy et having

Les méthodes groupBy et having peuvent être utilisées pour regrouper les résultats de la requête. La signature de la méthode having est similaire à celle de la méthode where:

$users = app_db_table('orders')
  ->groupBy('price')
  ->having('price', '>', 100)
  ->get();

jump et take

Pour limiter le nombre de résultats renvoyés par la requête ou pour ignorer un nombre donné de résultats dans la requête, vous pouvez utiliser les méthodes jump (pour ignorer) et take (pour renvoyer un nombre):

use Bow\Database\Database;

$users = Database::table('users')->jump(10)->take(5)->get();

Aggregates

Méthodes d'agrégation

Le générateur de requêtes fournit également une variété de méthodes d'agrégation telles que count, max, min, avg et sum.

Vous pouvez appeler n'importe laquelle de ces méthodes après avoir construit votre requête.

$users = app_db_table('users')->count();

$price = app_db_table('orders')->max('price');

$avg = app_db_table('orders')->avg('price');

Vérifier si des enregistrements existent

Au lieu d'utiliser la méthode count pour déterminer s'il existe des enregistrements correspondant aux contraintes de votre requête, vous pouvez utiliser la méthode exists :

$exists = app_db_table('users')->where('id', 1)->exists();

Spécification d'une clause de sélection

Bien entendu, il se peut que vous ne souhaitiez pas toujours sélectionner toutes les colonnes d'une table de base de données. À l'aide de la méthode select, vous pouvez spécifier une clause select personnalisée pour la requête:

$price = app_db_table('orders')->select('price')->get();
// Ou sélectionnez plusieurs colonnes
$price = app_db_table('orders')->select(['id', 'price'])->get();

Insertion d'informations

Insertion de données

Le générateur de requêtes fournit une méthode insert pour insérer des enregistrements dans la table de base de données.

La méthode insert accepte un tableau de noms de colonnes et de valeurs :

app_db_table('users')->insert(
  ['email' => 'exemple@gmail.com', 'age' => 27]
);

Vous pouvez même insérer plusieurs enregistrements dans la table avec un seul appel à insérer en transmettant un tableau de tableaux. Chaque tableau représente une ligne à insérer dans la table:

Mise à jour

Bien entendu, en plus d'insérer des enregistrements dans la base de données, le générateur de requêtes peut également mettre à jour des enregistrements existants à l'aide de la méthode update. La méthode update, comme la méthode insert, accepte un tableau de paires de colonnes et de valeurs contenant les colonnes à mettre à jour. Vous pouvez contraindre la requête de mise à jour à l'aide de clauses where:

app_db_table('users')->where('id', 1)->update(
  ['email' => 'exemple@gmail.com', 'age' => 27]
);

Supprimer un enregistrement

Suppression de données

Le générateur de requêtes peut également être utilisé pour supprimer des enregistrements de la table via la méthode delete.

Vous pouvez contraindre des instructions delete en ajoutant des clauses where avant d'appeler la méthode delete :

app_db_table('users')->delete();

app_db_table('users')->where('age', '>', 27)->delete();

Si vous souhaitez vider la table entière, ce qui supprimera toutes les lignes et réinitialisera l'ID d'auto-incrémentation à zéro, vous pouvez utiliser la méthode truncate:

app_db_table('pets')->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.