Voici le driver PHP pour MongoDB.
Vous trouverez dans ce chapitre quelques rapides exemples montrant la façon de se connecter, d'insérer des documents, de requêter des documents, de traverser des jeux de résultats, et de se déconnecter d'une base de données MongoDB. Vous trouverez encore plus de détails dans chaque étape de ce tutoriel.
<?php
// connexion
$m = new Mongo();
// sélection d'une base de données
$db = $m->comedy;
// sélectionne une collection (analogue à une table de base de données relationnelle)
$collection = $db->cartoons;
// ajoute un enregistrement
$obj = array( "title" => "Calvin and Hobbes", "author" => "Bill Watterson" );
$collection->insert($obj);
// ajoute un autre enregistrement, avec une façon différente d'insertion
$obj = array( "title" => "XKCD", "online" => true );
$collection->insert($obj);
// récupère tout de la collection
$cursor = $collection->find();
// traverse les résultats
foreach ($cursor as $obj) {
echo $obj["title"] . "\n";
}
?>
Ceci affichera :
Calvin and Hobbes XKCD
Pour se connecter à un serveur de base de données, utilisez une des façons suivantes :
<?php
$connection = new Mongo(); // Connexion à localhost:27017
$connection = new Mongo( "example.com" ); // Connexion à un hôte distant (en utilisant le port par défaut : 27017)
$connection = new Mongo( "example.com:65432" ); // connect to a remote host at a given port
?>
Vous n'avez pas à vous déconnecter explicitement de la base de données. Lorsque $connection sort du scope, la connexion sera fermée automatiquement et toutes les ressources utilisées par la base de données seront libérées.
La chapitre sur les connexion couvre les différents types de connexions.
La documentation de l'API de la classe Mongo et de la classe Mongo::__construct() permet d'avoir une bonne compréhension des options possibles avec bons nombres d'exemples.
Pour sélectionner une base de données, utilisez :
<?php
$db = $connection->dbname;
?>
La base de données n'a pas besoin d'avoir été créée auparavant ; vous pouvez simplement créer une nouvelle base de données en tentant de la sélectionner.
Attention aux fautes de frappe ! Vous pouvez par inadvertance créer une nouvelle base de données, ce qui peut rendre plus compliqué de trouver la cause d'une erreur :
<?php
$db = $connection->mybiglongdbname;
// Plus de codes ici...
$db = $connection->mybiglongdbanme;
// Maintenant, vous êtes connecté à une base de données différente !
?>
La documentation de l'API de la classe MongoDB contient plus d'informations sur les objets de bases de données.
Récupérer une connexion utilise la même syntaxe que de récupérer une base de données :
<?php
$db = $connection->baz;
$collection = $db->foobar;
// ou, plus succinctement
$collection = $connection->baz->foobar;
?>
Une collection est similaire à une table (si vous êtes familier avec les bases de données relationnelles).
La documentation de l'API de la classe MongoCollection contient plus d'informations sur les objets de collection.
Les tableaux associatifs sont les objets basiques qui peuvent être insérés dans une collection d'une base de données. Un document "document" peut être :
<?php
$doc = array( "name" => "MongoDB",
"type" => "database",
"count" => 1,
"info" => (object)array( "x" => 203, "y" => 102),
"versions" => array("0.9.7", "0.9.8", "0.9.9")
);
?>
Notez que vous pouvez avoir des tableaux et des objets imbriqués.
Pour insérer ce document, utilisez la méthode MongoCollection::insert() :
<?php
$collection->insert( $doc );
?>
La documentation de l'API sur la méthode MongoCollection::insert() contient plus d'informations sur l'insertion des données.
Pour montrer que le document inséré dans l'étape précédante est bien présent, nous pouvons simplement utiliser la méthode MongoCollection::findOne() pour récupérer une seule document de la collection. Cette méthode est utile dans les cas où il n'y a qu'un seul document correspondant aux critères ou bien si vous ne souhaitez qu'un seul résultat.
<?php
$obj = $collection->findOne();
var_dump( $obj );
?>
et vous devriez voir :
array(6) {
["_id"]=>
object(MongoId)#8 (1) {
["$id"]=>
string(24) "4e2995576803fab768000000"
}
["name"]=>
string(7) "MongoDB"
["type"]=>
string(8) "database"
["count"]=>
int(1)
["info"]=>
array(2) {
["x"]=>
int(203)
["y"]=>
int(102)
}
["versions"]=>
array(3) {
[0]=>
string(5) "0.9.7"
[1]=>
string(5) "0.9.8"
[2]=>
string(5) "0.9.9"
}
}
Notez qu'il y a un champ _id qui a été ajouté automatiquement à votre document. _id est le champ de la clé primaire. Si votre document n'en spécifie pas une, le driver en ajoutera une automatiquement.
Si vous spécifiez votre propre champ _id, il doit être unique dans la collection. Par exemple :
<?php
$db->foo->insert(array("_id" => 1), array("safe" => true));
// ceci émettra une exception
$db->foo->insert(array("_id" => 1), array("safe" => true));
// ceci est correct, sachant que c'est une collection différente
$db->bar->insert(array("_id" => 1), array("safe" => true));
?>
Notez que ces insertions utilisent une second tableau : array("safe" => true). Ce second champ spécifie les options d'insertion. Par défaut, le driver n'attend pas la réponse de la base de données pour écrire, et donc, il ne récupère pas le _id. En spécifiant qu'il s'agit d'une écriture "sur" (safe), le driver attendra une réponse de la base de données afin de confirmer l'écriture. En général, toutes les écritures doivent utiliser l'option "safe" (l'option avait été omise dans les précédents exemples dans un souci de simplification).
La méthode MongoCollection::findOne() pour plus d'informations sur la recherche de données.
La classe MongoId vous fournira plus de détails sur les identifiants uniques.
La section sur les écritures couvrent les écritures sécurisées sur plusieurs niveaux, tel que fait par les méthodes MongoCollection::insert(), MongoCollection::update() et MongoCollection::remove().
Afin de faire des requêtes plus intéressantes, commençons par ajouter plusieurs documents simples dans notre collection. Ces documents seront de la forme array( "i" => value ); et nous pourrons les insérer efficacement via une boucle :
<?php
for($i=0; $i<100; $i++) {
$collection->insert( array( "i" => $i ) );
}
?>
Notez que vous pouvez insérer des tableaux avec des clés différentes dans la même collection. Cet aspect correspond à ce que nous avançons lorsque nous disons que MongoDB a "un schéma libre".
Maintenant que nous avons inséré 101 documents (le 100 noté dans la boucle, +1), nous pouvons vérifier le nombre de documents dans la collection en utilisant la méthode MongoCollection::count().
<?php
echo $collection->count();
?>
Afin de récupérer tous les documents d'une collection, vous devez utiliser la méthode MongoCollection::find(). Cette méthode retourne un objet MongoCursor qui vous permet de parcourir tous les documents correspondant à votre requête. Aussi, pour récupérer tous les documents et les afficher, vous pouvez faire ceci :
<?php
$cursor = $collection->find();
foreach ($cursor as $id => $value) {
echo "$id: ";
var_dump( $value );
}
?>
La documentation de l'API sur la méthode MongoCollection::find() contient plus d'informations sur la recherche de données.
Nous pouvons créer une requête à passer à la méthode MongoCollection::find() pour récupérer un sous-jeu de documents de notre collection. Par exemple, si vous voulez trouver les documents dont le champ "i" vaut "71", vous pouvez le faire comme ceci :
<?php
$query = array( "i" => 71 );
$cursor = $collection->find( $query );
while( $cursor->hasNext() ) {
var_dump( $cursor->getNext() );
}
?>
un seul document s'affichera :
array(2) {
["_id"]=>
object(MongoId)#6 (0) {
}
["i"]=>
int(71)
["_ns"]=>
"testCollection"
}
Vous pouvez utiliser une requête pour récupérer plusieurs documents depuis la collection. Par exemple, si vous voulez récupérer tous les documents dont le champ "i" est plus grand que 50, vous pouvez le faire comme ceci :
<?php
$query = array( "i" => array( '$gt' => 50 ) ); //notez les simples guillemets autour de '$gt'
$cursor = $coll->find( $query );
while( $cursor->hasNext() ) {
var_dump( $cursor->getNext() );
}
?>
Ceci devrait afficher les documents dont le champ "i" est supérieur à 50. Nous pouvons également spécifier un intervalle comme 20 < i <= 30 :
<?php
$query = array( "i" => array( "\$gt" => 20, "\$lte" => 30 ) );
$cursor = $coll->find( $query );
while( $cursor->hasNext() ) {
var_dump( $cursor->getNext() );
}
?>
Rappelez-vous de toujours échapper le symbole $ ou d'utiliser des guillemets simples. Sinon, PHP l'interprétera comme étant la variable $gt.
MongoDB supporte les indexes, et il est très simple de les ajouter à une collection. Pour créer un index, vous devez spécifier le nom du champ ainsi que sa direction : ascendant (1) ou descendant (-1). L'exemple suivant va créer un index ascendant sur le champ "i" :
<?php
$coll->ensureIndex( array( "i" => 1 ) ); // Création d'un index sur le champ "i"
$coll->ensureIndex( array( "i" => -1, "j" => 1 ) ); // Index descendant sur le champ "i", et ascendant sur le champ "j"
?>
L'indexation est une action critique pour les performances en lecture lorsque vos données grossissent. Si vous n'êtes pas familier avec l'indexation, reportez-vous à la documentation de la méthode MongoCollection::ensureIndex() ansi que la » documentation du coeur de l'indexation MongoDB.