PHP 5.4.33 Released

La classe MongoCursor

(PECL mongo >=0.9.0)

Introduction

Un curseur est utilisé pour itérer les résultats d'une requête. Par exemple regarder tous les résultats d'une requête quelconque :

Exemple #1 Utilisation basique de MongoCursor

<?php

$cursor 
$collection->find();
var_dump(iterator_to_array($cursor));

?>

En général, vous ne créez pas de MongoCursor en utilisant le constructeur mais en appelant MongoCollection::find() (comme ci-dessus).

Supposons que, dans l'exemple ci-dessus, $collection pèse 50Go. On ne voudra certainement pas tout charger en mémoire, c'est ce que permet un curseur : permettre au client d'accéder aux données au fur et à mesure.

Si nous avons des jeux de résultats très grands, nous pouvons itérer dessus, ceci chargera seulement quelques méga-octets dans la mémoire. Par exemple :

Exemple #2 Parcourt d'un MongoCursor

<?php

$cursor 
$collection->find();

foreach (
$cursor as $doc) {
    
// faire quelque chose avec chaque document $doc
}

?>
Les documents ici sont créés puis détruits au fur et à mesure de l'itération.

Notez que cela signifie qu'un curseur ne contient pas les données du jeu de résultats, il ne fait que les piloter. Ainsi si vous affichez un curseur (par exemple, avec var_dump() ou print_r()), vous n'obtiendrez que l'objet curseur, pas les documents. Pour obtenir les documents, vous pouvez utiliser une des techniques ci-dessus.

Etats des curseurs

Un MongoCursor a 2 états différents : Avant et après la requête. Lorsqu'un curseur est créé, il n'a pas encore contacté la base de données, il est en état pré-requête et le client peut toujours préciser ce qu'il attend de la requête, par exemple ajouter des limites, des tris ou encore des options avancées.

Lorsque le client tente de récupérer un résultat (en appelant la fonction MongoCursor::next(), directement ou indirectement), le curseur passe à l'état post-requête. À ce moment-là, la requête a été exécutée par la base et ne peut plus être modifiée.

Exemple #3 Ajout d'options à MongoCursor

<?php

$cursor 
$collection->find()->limit(10);

// la base n'a pas encore été interrogée,
// il est donc encore temps d'ajouter des options
$cursor $cursor->sort(array("a" => 1));

var_dump($cursor->getNext());
// maintenant, la base a été interrogée, et les options ne sont plus prises en compte

// Cet commnande va produire une exception :
$cursor->skip(4);
?>

Synopsis de la classe

MongoCursor implements Iterator {
/* Champs statiques */
static boolean $slaveOkay = FALSE ;
static integer $timeout = 30000 ;
/* Méthodes */
public MongoCursor addOption ( string $key , mixed $value )
public MongoCursor awaitData ([ bool $wait = true ] )
public MongoCursor batchSize ( int $batchSize )
public __construct ( MongoClient $connection , string $ns [, array $query = array() [, array $fields = array() ]] )
public int count ([ bool $foundOnly = FALSE ] )
public array current ( void )
public bool dead ( void )
protected void doQuery ( void )
public array explain ( void )
public MongoCursor fields ( array $f )
public array getNext ( void )
public array getReadPreference ( void )
public bool hasNext ( void )
public MongoCursor hint ( mixed $index )
public MongoCursor immortal ([ bool $liveForever = true ] )
public array info ( void )
public string key ( void )
public MongoCursor limit ( int $num )
public MongoCursor maxTimeMS ( int $ms )
public void next ( void )
public MongoCursor partial ([ bool $okay = true ] )
public void reset ( void )
public void rewind ( void )
public MongoCursor setFlag ( int $flag [, bool $set = true ] )
public MongoCursor setReadPreference ( string $read_preference [, array $tags ] )
public MongoCursor skip ( int $num )
public MongoCursor slaveOkay ([ bool $okay = true ] )
public MongoCursor snapshot ( void )
public MongoCursor sort ( array $fields )
public MongoCursor tailable ([ bool $tail = true ] )
public MongoCursor timeout ( int $ms )
public bool valid ( void )
}

Variables statiques

slaveOkay

Est ce que la requête doit avoir le drapeau "slaveOkay" activé, ce qui permet des lectures sur le secondaire (les secondaires sont par défaut déstinés à des sauvegardes et donc inaccessibles en lectures). Peut être surchargé avec MongoCursor::slaveOkay().

Cette fonctionalité est obsolète. Veuillez utiliser Préférences de lecture à la place.

timeout

Affecte le timeout en millisecondes pour les réponses des bases de données. Pour un timeout infini, utilisez -1. Peut être surchargé avec MongoCursor::timeout(). Ceci ne provoque pas une annulation de l'opération par le serveur MongoDB mais fait en sorte que le pilote s'arrête d'attendre une réponse et envoie une exception MongoCursorTimeoutException.

Voir aussi

Documentation de MongoDB » concernant les curseurs.

Sommaire

add a note add a note

User Contributed Notes 2 notes

up
1
adrian dot zurek at netmedia dot com dot pl
2 years ago
One *VERY* important note, if You do:
$cursor = $collection->find(array(), array('_id' => 0)); // ommit '_id' field in result

then:
var_dump(iterator_to_array($cursor));

will return only *ONE* document, not all!
up
1
Adil Baig @ AiDezigns
3 years ago
If you want to know whether a cursor returned any results it is faster to use 'hasNext()' than 'count'
To Top