Nette Database

Nette Database est une couche de base de données puissante et élégante pour PHP, mettant l'accent sur la simplicité et les fonctionnalités intelligentes. Elle offre deux façons de travailler avec la base de données – Explorer pour un développement rapide d'applications, ou l'accès SQL pour travailler directement avec les requêtes.

Installation

Téléchargez et installez la bibliothèque à l'aide de l'outil Composer :

composer require nette/database

Bases de données supportées

Nette Database supporte les bases de données suivantes :

Deux approches de la base de données

Nette Database vous donne le choix : écrire directement des requêtes SQL (accès SQL) ou laisser Explorer les générer automatiquement. Voyons comment les deux approches résolvent les mêmes tâches :

Accès SQL – Requêtes SQL

// Insertion d'un enregistrement
$database->query('INSERT INTO books', [
	'author_id' => $authorId,
	'title' => $bookData->title,
	'published_at' => new DateTime,
]);

// Récupération des auteurs actifs avec le nombre de livres
$result = $database->query('
	SELECT authors.*, COUNT(books.id) AS books_count
	FROM authors
	LEFT JOIN books ON authors.id = books.author_id
	WHERE authors.active = 1
	GROUP BY authors.id
');

// Affichage (problème N+1 : génère N requêtes supplémentaires pour les livres)
foreach ($result as $author) {
	$books = $database->query('
		SELECT * FROM books
		WHERE author_id = ?
		ORDER BY published_at DESC
	', $author->id);

	echo "L'auteur $author->name a écrit $author->books_count livres :\n";

	foreach ($books as $book) {
		echo "- $book->title\n";
	}
}

Approche Explorer – Génération automatique de SQL

// Insertion d'un enregistrement
$database->table('books')->insert([
	'author_id' => $authorId,
	'title' => $bookData->title,
	'published_at' => new DateTime,
]);

// Récupération des auteurs actifs
$authors = $database->table('authors')
	->where('active', 1);

// Affichage (optimisé : génère seulement 2 requêtes au total)
foreach ($authors as $author) {
	$books = $author->related('books')
		->order('published_at DESC');

	echo "L'auteur $author->name a écrit {$books->count()} livres :\n";

	foreach ($books as $book) {
		echo "- $book->title\n";
	}
}

L'approche Explorer génère et optimise automatiquement les requêtes SQL. Dans l'exemple ci-dessus, l'accès SQL souffre du problème “N+1” (une requête pour les auteurs, puis une requête par auteur pour ses livres), tandis qu'Explorer optimise cela en seulement deux requêtes au total : une pour les auteurs et une pour tous leurs livres associés.

Vous pouvez combiner librement les deux approches dans votre application selon vos besoins.

Connexion et configuration

Pour vous connecter à la base de données, il suffit de créer une instance de la classe Nette\Database\Connection :

$database = new Nette\Database\Connection($dsn, $user, $password);

Le paramètre $dsn (Data Source Name) est le même que celui utilisé par PDO. En cas d'échec de connexion, une exception Nette\Database\ConnectionException est levée.

Cependant, la méthode recommandée est d'utiliser la configuration de l'application (fichier NEON). Ajoutez simplement une section database, et Nette DI créera automatiquement les services nécessaires (Connection et Explorer), ainsi que le panneau de base de données dans la barre de débogage Tracy.

database:
	dsn: 'mysql:host=127.0.0.1;dbname=test'
	user: root
	password: password

Ensuite, vous obtenez l'objet de connexion ou l'Explorer en tant que service via l'injection de dépendances :

class Model
{
	public function __construct(
		// ou Nette\Database\Explorer
		private Nette\Database\Connection $database,
	) {
	}
}

Consultez la section sur la configuration de la base de données pour plus de détails.

Création manuelle de l'Explorer

Si vous n'utilisez pas Nette DI, vous pouvez créer manuellement une instance de Nette\Database\Explorer :

// connexion à la base de données
$connection = new Nette\Database\Connection('mysql:host=127.0.0.1;dbname=mydatabase', 'user', 'password');
// stockage pour le cache, implémente Nette\Caching\Storage, par ex. :
$storage = new Nette\Caching\Storages\FileStorage('/path/to/temp/dir');
// s'occupe de la réflexion de la structure de la base de données
$structure = new Nette\Database\Structure($connection, $storage);
// définit les règles de mappage des noms de tables, colonnes et clés étrangères
$conventions = new Nette\Database\Conventions\DiscoveredConventions($structure);
$explorer = new Nette\Database\Explorer($connection, $structure, $conventions, $storage);

Gestion de la connexion

Lors de la création de l'objet Connection, la connexion est établie automatiquement. Si vous souhaitez différer la connexion, utilisez le mode lazy – activez-le dans la configuration en définissant lazy, ou comme ceci :

$database = new Nette\Database\Connection($dsn, $user, $password, ['lazy' => true]);

Pour gérer la connexion, utilisez les méthodes connect(), disconnect() et reconnect().

• connect() crée la connexion si elle n'existe pas encore, et peut lever une exception Nette\Database\ConnectionException.
• disconnect() déconnecte la connexion actuelle à la base de données.
• reconnect() effectue une déconnexion puis une reconnexion à la base de données. Cette méthode peut également lever une exception Nette\Database\ConnectionException.

De plus, vous pouvez surveiller les événements liés à la connexion en utilisant l'événement onConnect, qui est un tableau de callbacks appelés après l'établissement de la connexion à la base de données.

// s'exécute après la connexion à la base de données
$database->onConnect[] = function($database) {
	echo "Connecté à la base de données";
};

Barre de débogage Tracy

Si vous utilisez Tracy, le panneau Database s'active automatiquement dans la barre de débogage, affichant toutes les requêtes exécutées, leurs paramètres, leur temps d'exécution et l'endroit dans le code où elles ont été appelées.