lib/ActiveMongo.php

   1 <?php
   2 /*
   3   +---------------------------------------------------------------------------------+
   4   | Copyright (c) 2010 ActiveMongo                                                  |
   5   +---------------------------------------------------------------------------------+
   6   | Redistribution and use in source and binary forms, with or without              |
   7   | modification, are permitted provided that the following conditions are met:     |
   8   | 1. Redistributions of source code must retain the above copyright               |
   9   |    notice, this list of conditions and the following disclaimer.                |
  10   |                                                                                 |
  11   | 2. Redistributions in binary form must reproduce the above copyright            |
  12   |    notice, this list of conditions and the following disclaimer in the          |
  13   |    documentation and/or other materials provided with the distribution.         |
  14   |                                                                                 |
  15   | 3. All advertising materials mentioning features or use of this software        |
  16   |    must display the following acknowledgement:                                  |
  17   |    This product includes software developed by César D. Rodas.                  |
  18   |                                                                                 |
  19   | 4. Neither the name of the César D. Rodas nor the                               |
  20   |    names of its contributors may be used to endorse or promote products         |
  21   |    derived from this software without specific prior written permission.        |
  22   |                                                                                 |
  23   | THIS SOFTWARE IS PROVIDED BY CÉSAR D. RODAS ''AS IS'' AND ANY                   |
  24   | EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED       |
  25   | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE          |
  26   | DISCLAIMED. IN NO EVENT SHALL CÉSAR D. RODAS BE LIABLE FOR ANY                  |
  27   | DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES      |
  28   | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;    |
  29   | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND     |
  30   | ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT      |
  31   | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS   |
  32   | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE                     |
  33   +---------------------------------------------------------------------------------+
  34   | Authors: César Rodas <crodas@php.net>                                           |
  35   +---------------------------------------------------------------------------------+
  36 */
  37
  38 // array get_document_vars(stdobj $obj) {{{
  39 /**
  40  *  Simple hack to avoid get private and protected variables
  41  *
  42  *  @param object $obj
  43  *  @param bool   $include_id
  44  *
  45  *  @return array
  46  */
  47 function get_document_vars($obj, $include_id=TRUE)
  48 {
  49     $document =  get_object_vars($obj);
  50     if ($include_id && $obj->getID()) {
  51         $document['_id'] = $obj->getID();
  52     }
  53     return $document;
  54 }
  55 // }}}
  56
  57 /**
  58  *  ActiveMongo
  59  *
  60  *  Simple ActiveRecord pattern built on top of MongoDB. This class
  61  *  aims to provide easy iteration, data validation before update,
  62  *  and efficient update.
  63  *
  64  *  @author César D. Rodas <crodas@php.net>
  65  *  @license BSD License
  66  *  @package ActiveMongo
  67  *  @version 1.0
  68  *
  69  */
  70 abstract class ActiveMongo implements Iterator, Countable, ArrayAccess
  71 {
  72
  73     //{{{ Constants
  74     const FIND_AND_MODIFY = 0x001;
  75     // }}}
  76
  77     // properties {{{
  78     /**
  79      *  Current databases objects
  80      *
  81      *  @type array
  82      */
  83     private static $_dbs;
  84     /**
  85      *  Current collections objects
  86      *
  87      *  @type array
  88      */
  89     private static $_collections;
  90     /**
  91      *  Current connection to MongoDB
  92      *
  93      *  @type MongoConnection
  94      */
  95     private static $_conn;
  96     /**
  97      *  Database name
  98      *
  99      *  @type string
 100      */
 101     private static $_db;
 102     /**
 103      *  List of events handlers
 104      *
 105      *  @type array
 106      */
 107     static private $_events = array();
 108     /**
 109      *  List of global events handlers
 110      *
 111      *  @type array
 112      */
 113     static private $_super_events = array();
 114     /**
 115      *  Host name
 116      *
 117      *  @type string
 118      */
 119     private static $_host;
 120     /**
 121      *  User (Auth)
 122      *
 123      *  @type string
 124      */
 125     private static $_user;
 126
 127         /**
 128      *  Password (Auth)
 129      *
 130      *  @type string
 131      */
 132     private static $_pwd;
 133
 134     /**
 135      *  Current document
 136      *
 137      *  @type array
 138      */
 139     private $_current = array();
 140     /**
 141      *  Result cursor
 142      *
 143      *  @type MongoCursor
 144      */
 145     private $_cursor  = NULL;
 146     /**
 147      *  Extended result cursor, used for FindAndModify now
 148      *
 149      *  @type int
 150      */
 151     private $_cursor_ex  = NULL;
 152     private $_cursor_ex_value;
 153     /**
 154      *  Count the findandmodify result counts
 155      *
 156      *  @tyep array
 157      */
 158     private $_findandmodify_cnt = 0;
 159     /* value to modify */
 160     private $_findandmodify;
 161
 162     /* {{{ Silly but useful query abstraction  */
 163     private $_cached  = FALSE;
 164     private $_query   = NULL;
 165     private $_sort    = NULL;
 166     private $_limit   = 0;
 167     private $_skip    = 0;
 168     private $_properties = NULL;
 169     /* }}} */
 170
 171     /**
 172      *  Current document ID
 173      *
 174      *  @type MongoID
 175      */
 176     private $_id;
 177
 178     /**
 179      *  Tell if the current object
 180      *  is cloned or not.
 181      *
 182      *  @type bool
 183      */
 184     private $_cloned = FALSE;
 185     // }}}
 186
 187     // GET CONNECTION CONFIG {{{
 188
 189     // string getCollectionName() {{{
 190     /**
 191      *  Get Collection Name, by default the class name,
 192      *  but you it can be override at the class itself to give
 193      *  a custom name.
 194      *
 195      *  @return string Collection Name
 196      */
 197     protected function getCollectionName()
 198     {
 199         if (isset($this)) {
 200             return strtolower(get_class($this));
 201         } else {
 202             return strtolower(get_called_class());
 203         }
 204     }
 205     // }}}
 206
 207     // string getDatabaseName() {{{
 208     /**
 209      *  Get Database Name, by default it is used
 210      *  the db name set by ActiveMong::connect()
 211      *
 212      *  @return string DB Name
 213      */
 214     protected function getDatabaseName()
 215     {
 216         if (is_NULL(self::$_db)) {
 217             throw new ActiveMongo_Exception("There is no information about the default DB name");
 218         }
 219         return self::$_db;
 220     }
 221     // }}}
 222
 223     // void install() {{{
 224     /**
 225      *  Install.
 226      *
 227      *  This static method iterate over the classes lists,
 228      *  and execute the setup() method on every ActiveMongo
 229      *  subclass. You should do this just once.
 230      *
 231      */
 232     final public static function install()
 233     {
 234         $classes = array_reverse(get_declared_classes());
 235         foreach ($classes as $class)
 236         {
 237             if ($class == __CLASS__) {
 238                 break;
 239             }
 240             if (is_subclass_of($class, __CLASS__)) {
 241                 $obj = new $class;
 242                 $obj->setup();
 243             }
 244         }
 245     }
 246     // }}}
 247
 248     // void connection($db, $host) {{{
 249     /**
 250      *  Connect
 251      *
 252      *  This method setup parameters to connect to a MongoDB
 253      *  database. The connection is done when it is needed.
 254      *
 255      *  @param string $db   Database name
 256      *  @param string $host Host to connect
 257      *  @param string $user   User (Auth)
 258      *  @param string $pwd Password (Auth)
 259      *
 260      *  @return void
 261      */
 262     final public static function connect($db, $host='localhost', $user = NULL, $pwd=NULL)
 263     {
 264         self::$_host = $host;
 265         self::$_db   = $db;
 266         self::$_user = $user;
 267         self::$_pwd   = $pwd;
 268     }
 269     // }}}
 270
 271     // MongoConnection _getConnection() {{{
 272     /**
 273      *  Get Connection
 274      *
 275      *  Get a valid database connection
 276      *
 277      *  @return MongoConnection
 278      */
 279     final protected function _getConnection()
 280     {
 281         if (is_NULL(self::$_conn)) {
 282             if (is_NULL(self::$_host)) {
 283                 self::$_host = 'localhost';
 284             }
 285             self::$_conn = new Mongo(self::$_host);
 286         }
 287         if (isset($this)) {
 288             $dbname = $this->getDatabaseName();
 289         } else {
 290             $dbname = self::getDatabaseName();
 291         }
 292         if (!isSet(self::$_dbs[$dbname])) {
 293             self::$_dbs[$dbname] = self::$_conn->selectDB($dbname);
 294         }
 295         if ( !is_NULL(self::$_user ) &&   !is_NULL(self::$_pwd )  ) {
 296             self::$_dbs[$dbname]->authenticate(self::$_user,self::$_pwd);
 297         }
 298
 299
 300         return self::$_dbs[$dbname];
 301     }
 302     // }}}
 303
 304     // MongoCollection _getCollection() {{{
 305     /**
 306      *  Get Collection
 307      *
 308      *  Get a collection connection.
 309      *
 310      *  @return MongoCollection
 311      */
 312     final protected function _getCollection()
 313     {
 314         if (isset($this)) {
 315             $colName = $this->getCollectionName();
 316         } else {
 317             $colName = self::getCollectionName();
 318         }
 319         if (!isset(self::$_collections[$colName])) {
 320             self::$_collections[$colName] = self::_getConnection()->selectCollection($colName);
 321         }
 322         return self::$_collections[$colName];
 323     }
 324     // }}}
 325
 326     // }}}
 327
 328     // GET DOCUMENT TO SAVE OR UPDATE {{{
 329
 330     // getDocumentVars() {{{
 331     /**
 332      *  getDocumentVars
 333      *
 334      *
 335      *
 336      */
 337     final protected function getDocumentVars()
 338     {
 339         $variables = array();
 340         foreach ((array)$this->__sleep() as $var) {
 341             if (!property_exists($this, $var)) {
 342                 continue;
 343             }
 344             $variables[$var] = $this->$var;
 345         }
 346         return $variables;
 347     }
 348     // }}}
 349
 350     // bool getCurrentSubDocument(array &$document, string $parent_key, array $values, array $past_values) {{{
 351     /**
 352      *  Generate Sub-document
 353      *
 354      *  This method build the difference between the current sub-document,
 355      *  and the origin one. If there is no difference, it would do nothing,
 356      *  otherwise it would build a document containing the differences.
 357      *
 358      *  @param array  &$document    Document target
 359      *  @param string $parent_key   Parent key name
 360      *  @param array  $values       Current values
 361      *  @param array  $past_values  Original values
 362      *
 363      *  @return FALSE
 364      */
 365     final function getCurrentSubDocument(&$document, $parent_key, Array $values, Array $past_values)
 366     {
 367         /**
 368          *  The current property is a embedded-document,
 369          *  now we're looking for differences with the
 370          *  previous value (because we're on an update).
 371          *
 372          *  It behaves exactly as getCurrentDocument,
 373          *  but this is simples (it doesn't support
 374          *  yet filters)
 375          */
 376         foreach ($values as $key => $value) {
 377             $super_key = "{$parent_key}.{$key}";
 378             if (is_array($value)) {
 379                 /**
 380                  *  Inner document detected
 381                  */
 382                 if (!array_key_exists($key, $past_values) || !is_array($past_values[$key])) {
 383                     /**
 384                      *  We're lucky, it is a new sub-document,
 385                      *  we simple add it
 386                      */
 387                     $document['$set'][$super_key] = $value;
 388                 } else {
 389                     /**
 390                      *  This is a document like this, we need
 391                      *  to find out the differences to avoid
 392                      *  network overhead.
 393                      */
 394                     if (!$this->getCurrentSubDocument($document, $super_key, $value, $past_values[$key])) {
 395                         return FALSE;
 396                     }
 397                 }
 398                 continue;
 399             } else if (!array_key_exists($key, $past_values) || $past_values[$key] !== $value) {
 400                 $document['$set'][$super_key] = $value;
 401             }
 402         }
 403
 404         foreach (array_diff(array_keys($past_values), array_keys($values)) as $key) {
 405             $super_key = "{$parent_key}.{$key}";
 406             $document['$unset'][$super_key] = 1;
 407         }
 408
 409         return TRUE;
 410     }
 411     // }}}
 412
 413     // array getCurrentDocument(bool $update) {{{
 414     /**
 415      *    Get Current Document
 416      *
 417      *    Based on this object properties a new document (Array)
 418      *    is returned. If we're modifying an document, just the modified
 419      *    properties are included in this document, which uses $set,
 420      *    $unset, $pushAll and $pullAll.
 421      *
 422      *
 423      *    @param bool $update
 424      *
 425      *    @return array
 426      */
 427     final protected function getCurrentDocument($update=FALSE, $current=FALSE)
 428     {
 429         $document = array();
 430         $object   = $this->getDocumentVars();
 431
 432         if (!$current) {
 433             $current = (array)$this->_current;
 434         }
 435
 436
 437         $this->findReferences($object);
 438
 439         $this->triggerEvent('before_validate', array(&$object, $current));
 440         $this->triggerEvent('before_validate_'.($update?'update':'creation'), array(&$object, $current));
 441
 442         foreach ($object as $key => $value) {
 443             if ($update) {
 444                 if (is_array($value) && isset($current[$key])) {
 445                     /**
 446                      *  If the Field to update is an array, it has a different
 447                      *  behaviour other than $set and $unset. Fist, we need
 448                      *  need to check if it is an array or document, because
 449                      *  they can't be mixed.
 450                      *
 451                      */
 452                     if (!is_array($current[$key])) {
 453                         /**
 454                          *  We're lucky, the field wasn't
 455                          *  an array previously.
 456                          */
 457                         $this->runFilter($key, $value, $current[$key]);
 458                         $document['$set'][$key] = $value;
 459                         continue;
 460                     }
 461
 462                     if (!$this->getCurrentSubDocument($document, $key, $value, $current[$key])) {
 463                         throw new Exception("{$key}: Array and documents are not compatible");
 464                     }
 465                 } else if(!array_key_exists($key, $current) || $value !== $current[$key]) {
 466                     /**
 467                      *  It is 'linear' field that has changed, or
 468                      *  has been modified.
 469                      */
 470                     $past_value = isset($current[$key]) ? $current[$key] : NULL;
 471                     $this->runFilter($key, $value, $past_value);
 472                     $document['$set'][$key] = $value;
 473                 }
 474             } else {
 475                 /**
 476                  *  It is a document insertation, so we
 477                  *  create the document.
 478                  */
 479                 $this->runFilter($key, $value, NULL);
 480                 $document[$key] = $value;
 481             }
 482         }
 483
 484         /* Updated behaves in a diff. way */
 485         if ($update) {
 486             foreach (array_diff(array_keys($this->_current), array_keys($object)) as $property) {
 487                 if ($property == '_id') {
 488                     continue;
 489                 }
 490                 $document['$unset'][$property] = 1;
 491             }
 492         }
 493
 494         if (count($document) == 0) {
 495             return array();
 496         }
 497
 498         $this->triggerEvent('after_validate', array(&$document));
 499         $this->triggerEvent('after_validate_'.($update?'update':'creation'), array(&$object));
 500
 501         return $document;
 502     }
 503     // }}}
 504
 505     // }}}
 506
 507     // EVENT HANDLERS {{{
 508
 509     // addEvent($action, $callback) {{{
 510     /**
 511      *  addEvent
 512      *
 513      */
 514     final static function addEvent($action, $callback)
 515     {
 516         if (!is_callable($callback)) {
 517             throw new Exception("Invalid callback");
 518         }
 519
 520         $class = get_called_class();
 521         if ($class == __CLASS__) {
 522             $events = & self::$_super_events;
 523         } else {
 524             $events = & self::$_events[$class];
 525         }
 526         if (!isset($events[$action])) {
 527             $events[$action] = array();
 528         }
 529         $events[$action][] = $callback;
 530         return TRUE;
 531     }
 532     // }}}
 533
 534     // triggerEvent(string $event, Array $events_params) {{{
 535     final function triggerEvent($event, Array $events_params = array())
 536     {
 537         if (!isset($this)) {
 538             $class = get_called_class();
 539         } else {
 540             $class = get_class($this);
 541         }
 542         $events  = & self::$_events[$class][$event];
 543         $sevents = & self::$_super_events[$event];
 544
 545         /* Super-Events handler receives the ActiveMongo class name as first param */
 546         $sevents_params = array_merge(array($class), $events_params);
 547
 548         foreach (array('events', 'sevents') as $event_type) {
 549             if (count($$event_type) > 0) {
 550                 $params = "{$event_type}_params";
 551                 foreach ($$event_type as $fnc) {
 552                     if (call_user_func_array($fnc, $$params) === FALSE) {
 553                         return;
 554                     }
 555                 }
 556             }
 557         }
 558
 559         /* Some natives events are allowed to be called
 560          * as methods, if they exists
 561          */
 562         if (!isset($this)) {
 563             return;
 564         }
 565         switch ($event) {
 566         case 'before_create':
 567         case 'before_update':
 568         case 'before_validate':
 569         case 'before_delete':
 570         case 'before_drop':
 571         case 'before_query':
 572         case 'after_create':
 573         case 'after_update':
 574         case 'after_validate':
 575         case 'after_delete':
 576         case 'after_drop':
 577         case 'after_query':
 578             $fnc    = array($this, $event);
 579             $params = "events_params";
 580             if (is_callable($fnc)) {
 581                 call_user_func_array($fnc, $$params);
 582             }
 583             break;
 584         }
 585     }
 586     // }}}
 587
 588      // void runFilter(string $key, mixed &$value, mixed $past_value) {{{
 589     /**
 590      *  *Internal Method*
 591      *
 592      *  This method check if the current document property has
 593      *  a filter method, if so, call it.
 594      *
 595      *  If the filter returns FALSE, throw an Exception.
 596      *
 597      *  @return void
 598      */
 599     protected function runFilter($key, &$value, $past_value)
 600     {
 601         $filter = array($this, "{$key}_filter");
 602         if (is_callable($filter)) {
 603             $filter = call_user_func_array($filter, array(&$value, $past_value));
 604             if ($filter===FALSE) {
 605                 throw new ActiveMongo_FilterException("{$key} filter failed");
 606             }
 607             $this->$key = $value;
 608         }
 609     }
 610     // }}}
 611
 612     // }}}
 613
 614     // void setCursor(MongoCursor $obj) {{{
 615     /**
 616      *  Set Cursor
 617      *
 618      *  This method receive a MongoCursor and make
 619      *  it iterable.
 620      *
 621      *  @param MongoCursor $obj
 622      *
 623      *  @return void
 624      */
 625     final protected function setCursor(MongoCursor $obj)
 626     {
 627         $this->_cursor = $obj;
 628         $obj->reset();
 629         $this->setResult($obj->getNext());
 630     }
 631     // }}}
 632
 633     // void setResult(Array $obj) {{{
 634     /**
 635      *  Set Result
 636      *
 637      *  This method takes an document and copy it
 638      *  as properties in this object.
 639      *
 640      *  @param Array $obj
 641      *
 642      *  @return void
 643      */
 644     final protected function setResult($obj)
 645     {
 646         /* Unsetting previous results, if any */
 647         foreach (array_keys(get_document_vars($this, FALSE)) as $key) {
 648             unset($this->$key);
 649         }
 650         $this->_id = NULL;
 651
 652         /* Add our current resultset as our object's property */
 653         foreach ((array)$obj as $key => $value) {
 654             if ($key[0] == '$') {
 655                 continue;
 656             }
 657             $this->$key = $value;
 658         }
 659
 660         /* Save our record */
 661         $this->_current = $obj;
 662     }
 663     // }}}
 664
 665     // this find([$_id]) {{{
 666     /**
 667      *    Simple find.
 668      *
 669      *    Really simple find, which uses this object properties
 670      *    for fast filtering
 671      *
 672      *    @return object this
 673      */
 674     final function find($_id = NULL)
 675     {
 676         $vars = get_document_vars($this);
 677         $parent_class = __CLASS__;
 678         foreach ($vars as $key => $value) {
 679             if (!$value) {
 680                 unset($vars[$key]);
 681             }
 682             if ($value InstanceOf $parent_class) {
 683                 $this->getColumnDeference($vars, $key, $value);
 684                 unset($vars[$key]); /* delete old value */
 685             }
 686         }
 687         if ($_id != NULL) {
 688             if (is_array($_id)) {
 689                 $vars['_id'] = array('$in' => $_id);
 690             } else {
 691                 $vars['_id'] = $_id;
 692             }
 693         }
 694         $res  = $this->_getCollection()->find($vars);
 695         $this->setCursor($res);
 696         return $this;
 697     }
 698     // }}}
 699
 700     // void save(bool $async) {{{
 701     /**
 702      *    Save
 703      *
 704      *    This method save the current document in MongoDB. If
 705      *    we're modifying a document, a update is performed, otherwise
 706      *    the document is inserted.
 707      *
 708      *    On updates, special operations such as $set, $pushAll, $pullAll
 709      *    and $unset in order to perform efficient updates
 710      *
 711      *    @param bool $async
 712      *
 713      *    @return void
 714      */
 715     final function save($async=TRUE)
 716     {
 717         $update   = isset($this->_id) && $this->_id InstanceOf MongoID;
 718         $conn     = $this->_getCollection();
 719         $document = $this->getCurrentDocument($update);
 720         $object   = $this->getDocumentVars();
 721
 722         if (isset($this->_id)) {
 723             $object['_id'] = $this->_id;
 724         }
 725
 726         if (count($document) == 0) {
 727             return; /*nothing to do */
 728         }
 729
 730          /* PRE-save hook */
 731         $this->triggerEvent('before_'.($update ? 'update' : 'create'), array(&$document, $object));
 732
 733         if ($update) {
 734             $conn->update(array('_id' => $this->_id), $document, array('safe' => $async));
 735             if (isset($document['$set'])) {
 736                 foreach ($document['$set'] as $key => $value) {
 737                     if (strpos($key, ".") === FALSE) {
 738                         $this->_current[$key] = $value;
 739                         $this->$key = $value;
 740                     } else {
 741                         $keys = explode(".", $key);
 742                         $key  = $keys[0];
 743                         $arr  = & $this->$key;
 744                         $arrc = & $this->_current[$key];
 745                         for ($i=1; $i < count($keys)-1; $i++) {
 746                             $arr  = &$arr[$keys[$i]];
 747                             $arrc = &$arrc[$keys[$i]];
 748                         }
 749                         $arr [ $keys[$i] ] = $value;
 750                         $arrc[ $keys[$i] ] = $value;
 751                     }
 752                 }
 753             }
 754             if (isset($document['$unset'])) {
 755                 foreach ($document['$unset'] as $key => $value) {
 756                     if (strpos($key, ".") === FALSE) {
 757                         unset($this->_current[$key]);
 758                         unset($this->$key);
 759                     } else {
 760                         $keys = explode(".", $key);
 761                         $key  = $keys[0];
 762                         $arr  = & $this->$key;
 763                         $arrc = & $this->_current[$key];
 764                         for ($i=1; $i < count($keys)-1; $i++) {
 765                             $arr  = &$arr[$keys[$i]];
 766                             $arrc = &$arrc[$keys[$i]];
 767                         }
 768                         unset($arr [ $keys[$i] ]);
 769                         unset($arrc[ $keys[$i] ]);
 770                     }
 771                 }
 772             }
 773         } else {
 774             $conn->insert($document, $async);
 775             $this->setResult($document);
 776         }
 777
 778         $this->triggerEvent('after_'.($update ? 'update' : 'create'), array($document, $object));
 779
 780         return TRUE;
 781     }
 782     // }}}
 783
 784     // bool delete() {{{
 785     /**
 786      *  Delete the current document
 787      *
 788      *  @return bool
 789      */
 790     final function delete()
 791     {
 792
 793         $document = array('_id' => $this->_id);
 794         if ($this->_cursor InstanceOf MongoCursor) {
 795             $this->triggerEvent('before_delete', array($document));
 796             $result = $this->_getCollection()->remove($document);
 797             $this->triggerEvent('after_delete', array($document));
 798             $this->setResult(array());
 799             return $result;
 800         } else {
 801             $criteria = (array) $this->_query;
 802
 803             /* remove */
 804             $this->triggerEvent('before_delete', array($document));
 805             $this->_getCollection()->remove($criteria);
 806             $this->triggerEvent('after_delete', array($document));
 807
 808             /* reset object */
 809             $this->reset();
 810
 811             return TRUE;
 812         }
 813         return FALSE;
 814     }
 815     // }}}
 816
 817     // Update {{{
 818     /**
 819      *  Multiple updates.
 820      *
 821      *  This method perform multiple updates when a given
 822      *  criteria matchs (using where).
 823      *
 824      *  By default the update is perform safely, but it can be
 825      *  changed.
 826      *
 827      *  After the operation is done, the criteria is deleted.
 828      *
 829      *  @param array $value Values to set
 830      *  @param bool  $safe  Whether or not peform the operation safely
 831      *
 832      *  @return bool
 833      *
 834      */
 835     function update(Array $value, $safe=TRUE)
 836     {
 837         $this->_assertNotInQuery();
 838
 839         $criteria = (array) $this->_query;
 840         $options  = array('multiple' => TRUE, 'safe' => $safe);
 841
 842         /* update */
 843         $col = $this->_getCollection();
 844         $col->update($criteria, array('$set' => $value), $options);
 845
 846         /* reset object */
 847         $this->reset();
 848
 849         return TRUE;
 850     }
 851     // }}}
 852
 853     // void drop() {{{
 854     /**
 855      *  Delete the current colleciton and all its documents
 856      *
 857      *  @return void
 858      */
 859     final static function drop()
 860     {
 861         $class = get_called_class();
 862         if ($class == __CLASS__) {
 863             return FALSE;
 864         }
 865         $obj = new $class;
 866         $obj->triggerEvent('before_drop');
 867         $result = $obj->_getCollection()->drop();
 868         $obj->triggerEvent('after_drop');
 869         if ($result['ok'] != 1) {
 870             throw new ActiveMongo_Exception($result['errmsg']);
 871         }
 872         return TRUE;
 873
 874     }
 875     // }}}
 876
 877     // int count() {{{
 878     /**
 879      *  Return the number of documents in the actual request. If
 880      *  we're not in a request, it will return 0.
 881      *
 882      *  @return int
 883      */
 884     final function count()
 885     {
 886         if ($this->valid()) {
 887             return $this->_cursor->count();
 888         }
 889         return 0;
 890     }
 891     // }}}
 892
 893     // void setup() {{{
 894     /**
 895      *  This method should contain all the indexes, and shard keys
 896      *  needed by the current collection. This try to make
 897      *  installation on development environments easier.
 898      */
 899     function setup()
 900     {
 901     }
 902     // }}}
 903
 904     // batchInsert {{{
 905     /**
 906      *  Perform a batchInsert of objects.
 907      *
 908      *  @param array $documents         Arrays of documents to insert
 909      *  @param bool  $safe              True if a safe will be performed, this means data validation, and wait for MongoDB OK reply
 910      *  @param bool  $on_error_continue If an error happen while validating an object, if it should continue or not
 911      *
 912      *  @return bool
 913      */
 914     final public static function batchInsert(Array $documents, $safe=TRUE, $on_error_continue=TRUE)
 915     {
 916         if (__CLASS__ == get_called_class()) {
 917             throw new ActiveMongo_Exception("Invalid batchInsert usage");
 918         }
 919
 920         if ($safe) {
 921             foreach ($documents as $id => $doc) {
 922                 $valid = FALSE;
 923                 if (is_array($doc)) {
 924                     try {
 925                         self::triggerEvent('before_create', array(&$doc));
 926                         self::triggerEvent('before_validate', array(&$doc, $doc));
 927                         self::triggerEvent('before_validate_creation', array(&$doc, $doc));
 928                         $valid = TRUE;
 929                     } catch (Exception $e) {}
 930                 }
 931                 if (!$valid) {
 932                     if (!$on_error_continue) {
 933                         throw new ActiveMongo_FilterException("Document $id is invalid");
 934                     }
 935                     unset($documents[$id]);
 936                 }
 937             }
 938         }
 939
 940         return self::_getCollection()->batchInsert($documents, array("safe" => $safe));
 941     }
 942     // }}}
 943
 944     // bool addIndex(array $columns, array $options) {{{
 945     /**
 946      *  addIndex
 947      *
 948      *  Create an Index in the current collection.
 949      *
 950      *  @param array $columns L ist of columns
 951      *  @param array $options Options
 952      *
 953      *  @return bool
 954      */
 955     final function addIndex($columns, $options=array())
 956     {
 957         $default_options = array(
 958             'background' => 1,
 959         );
 960
 961        foreach ($default_options as $option => $value) {
 962             if (!isset($options[$option])) {
 963                 $options[$option] = $value;
 964             }
 965         }
 966
 967         $collection = $this->_getCollection();
 968
 969         return $collection->ensureIndex($columns, $options);
 970     }
 971     // }}}
 972
 973     // Array getIndexes() {{{
 974     /**
 975      *  Return an array with all indexes
 976      *
 977      *  @return array
 978      */
 979     final static function getIndexes()
 980     {
 981         return self::_getCollection()->getIndexInfo();
 982     }
 983     // }}}
 984
 985     // string __toString() {{{
 986     /**
 987      *  To String
 988      *
 989      *  If this object is treated as a string,
 990      *  it would return its ID.
 991      *
 992      *  @return string
 993      */
 994     function __toString()
 995     {
 996         return (string)$this->getID();
 997     }
 998     // }}}
 999
1000     // array sendCmd(array $cmd) {{{
1001     /**
1002      *  This method sends a command to the current
1003      *  database.
1004      *
1005      *  @param array $cmd Current command
1006      *
1007      *  @return array
1008      */
1009     final protected function sendCmd($cmd)
1010     {
1011         return $this->_getConnection()->command($cmd);
1012     }
1013     // }}}
1014
1015     // ITERATOR {{{
1016
1017     // array getArray() {{{
1018     /**
1019      *  Return the current document as an array
1020      *  instead of a ActiveMongo object
1021      *
1022      *  @return Array
1023      */
1024     final function getArray()
1025     {
1026         return get_document_vars($this);
1027     }
1028     // }}}
1029
1030     // void reset() {{{
1031     /**
1032      *  Reset our Object, delete the current cursor if any, and reset
1033      *  unsets the values.
1034      *
1035      *  @return void
1036      */
1037     final function reset()
1038     {
1039         $this->_properties = NULL;
1040         $this->_cursor     = NULL;
1041         $this->_cursor_ex  = NULL;
1042         $this->_query      = NULL;
1043         $this->_sort       = NULL;
1044         $this->_limit      = 0;
1045         $this->_skip       = 0;
1046         $this->setResult(array());
1047     }
1048     // }}}
1049
1050     // bool valid() {{{
1051     /**
1052      *    Valid
1053      *
1054      *    Return if we're on an iteration and if it is still valid
1055      *
1056      *    @return TRUE
1057      */
1058     final function valid()
1059     {
1060         $valid = FALSE;
1061         if (!$this->_cursor_ex) {
1062             if (!$this->_cursor InstanceOf MongoCursor) {
1063                  $this->doQuery();
1064             }
1065             $valid = $this->_cursor InstanceOf MongoCursor && $this->_cursor->valid();
1066         } else {
1067             switch ($this->_cursor_ex) {
1068             case self::FIND_AND_MODIFY:
1069                 if ($this->_limit > $this->_findandmodify_cnt) {
1070                     $this->_execFindAndModify();
1071                     $valid = $this->_cursor_ex_value['ok'] == 1;
1072                 }
1073                 break;
1074             default:
1075                 throw new ActiveMongo_Exception("Invalid _cursor_ex value");
1076             }
1077         }
1078
1079         return $valid;
1080     }
1081     // }}}
1082
1083     // bool next() {{{
1084     /**
1085      *    Move to the next document
1086      *
1087      *    @return bool
1088      */
1089     final function next()
1090     {
1091         if ($this->_cloned) {
1092             throw new ActiveMongo_Exception("Cloned objects can't iterate");
1093         }
1094         if (!$this->_cursor_ex) {
1095             $result =  $this->_cursor->next();
1096             $this->current();
1097             return $result;
1098         } else {
1099             switch ($this->_cursor_ex) {
1100             case self::FIND_AND_MODIFY:
1101                 $this->_cursor_ex_value = NULL;
1102                 break;
1103             default:
1104                 throw new ActiveMongo_Exception("Invalid _cursor_ex value");
1105             }
1106         }
1107     }
1108     // }}}
1109
1110     // this current() {{{
1111     /**
1112      *    Return the current object, and load the current document
1113      *    as this object property
1114      *
1115      *    @return object
1116      */
1117     final function current()
1118     {
1119         if (!$this->_cursor_ex) {
1120             $this->setResult($this->_cursor->current());
1121         } else {
1122             switch ($this->_cursor_ex) {
1123             case self::FIND_AND_MODIFY:
1124                 if (count($this->_cursor_ex_value) == 0) {
1125                     $this->_execFindAndModify();
1126                 }
1127                 $this->setResult($this->_cursor_ex_value['value']);
1128                 break;
1129             default:
1130                 throw new ActiveMongo_Exception("Invalid _cursor_ex value");
1131             }
1132         }
1133         return $this;
1134     }
1135     // }}}
1136
1137     // bool rewind() {{{
1138     /**
1139      *    Go to the first document
1140      */
1141     final function rewind()
1142     {
1143         if (!$this->_cursor_ex) {
1144             /* rely on MongoDB cursor */
1145             if (!$this->_cursor InstanceOf MongoCursor) {
1146                 $this->doQuery();
1147             }
1148             $result = $this->_cursor->rewind();
1149             $this->current();
1150             return $result;
1151         } else {
1152             switch ($this->_cursor_ex) {
1153             case self::FIND_AND_MODIFY:
1154                 $this->_findandmodify_cnt = 0;
1155                 break;
1156             default:
1157                 throw new ActiveMongo_Exception("Invalid _cursor_ex value");
1158             }
1159         }
1160     }
1161     // }}}
1162
1163     // }}}
1164
1165     //  ARRAY ACCESS {{{
1166     final function offsetExists($offset)
1167     {
1168         return isset($this->$offset);
1169     }
1170
1171     final function offsetGet($offset)
1172     {
1173         return $this->$offset;
1174     }
1175
1176     final function offsetSet($offset, $value)
1177     {
1178         $this->$offset = $value;
1179     }
1180
1181     final function offsetUnset($offset)
1182     {
1183         unset($this->$offset);
1184     }
1185     // }}}
1186
1187     // REFERENCES {{{
1188
1189     // array getReference() {{{
1190     /**
1191      *  ActiveMongo extended the Mongo references, adding
1192      *  the concept of 'dynamic' requests, saving in the database
1193      *  the current query with its options (sort, limit, etc).
1194      *
1195      *  This is useful to associate a document with a given
1196      *  request. To undestand this better please see the 'reference'
1197      *  example.
1198      *
1199      *  @return array
1200      */
1201     final function getReference($dynamic=FALSE)
1202     {
1203         if (!$this->getID() && !$dynamic) {
1204             return NULL;
1205         }
1206
1207         $document = array(
1208             '$ref'  => $this->getCollectionName(),
1209             '$id'   => $this->getID(),
1210             '$db'   => $this->getDatabaseName(),
1211             'class' => get_class($this),
1212         );
1213
1214         if ($dynamic) {
1215             if (!$this->_cursor InstanceOf MongoCursor && $this->_cursor_ex === NULL) {
1216                 $this->doQuery();
1217             }
1218
1219             if (!$this->_cursor InstanceOf MongoCursor) {
1220                 throw new ActiveMongo_Exception("Only MongoDB native cursor could have dynamic references");
1221             }
1222
1223             $cursor = $this->_cursor;
1224             if (!is_callable(array($cursor, "Info"))) {
1225                 throw new Exception("Please upgrade your PECL/Mongo module to use this feature");
1226             }
1227             $document['dynamic'] = array();
1228             $query  = $cursor->Info();
1229             foreach ($query as $type => $value) {
1230                 $document['dynamic'][$type] = $value;
1231             }
1232         }
1233         return $document;
1234     }
1235     // }}}
1236
1237     // void getDocumentReferences($document, &$refs) {{{
1238     /**
1239      *  Get Current References
1240      *
1241      *  Inspect the current document trying to get any references,
1242      *  if any.
1243      *
1244      *  @param array $document   Current document
1245      *  @param array &$refs      References found in the document.
1246      *  @param array $parent_key Parent key
1247      *
1248      *  @return void
1249      */
1250     final protected function getDocumentReferences($document, &$refs, $parent_key=NULL)
1251     {
1252         foreach ($document as $key => $value) {
1253            if (is_array($value)) {
1254                if (MongoDBRef::isRef($value)) {
1255                    $pkey   = $parent_key;
1256                    $pkey[] = $key;
1257                    $refs[] = array('ref' => $value, 'key' => $pkey);
1258                } else {
1259                    $parent_key1 = $parent_key;
1260                    $parent_key1[] = $key;
1261                    $this->getDocumentReferences($value, $refs, $parent_key1);
1262                }
1263            }
1264         }
1265     }
1266     // }}}
1267
1268     // object _deferencingCreateObject(string $class) {{{
1269     /**
1270      *  Called at deferencig time
1271      *
1272      *  Check if the given string is a class, and it is a sub class
1273      *  of ActiveMongo, if it is instance and return the object.
1274      *
1275      *  @param string $class
1276      *
1277      *  @return object
1278      */
1279     private function _deferencingCreateObject($class)
1280     {
1281         if (!is_subclass_of($class, __CLASS__)) {
1282             throw new ActiveMongo_Exception("Fatal Error, imposible to create ActiveMongo object of {$class}");
1283         }
1284         return new $class;
1285     }
1286     // }}}
1287
1288     // void _deferencingRestoreProperty(array &$document, array $keys, mixed $req) {{{
1289     /**
1290      *  Called at deferencig time
1291      *
1292      *  This method iterates $document until it could match $keys path, and
1293      *  replace its value by $req.
1294      *
1295      *  @param array &$document Document to replace
1296      *  @param array $keys      Path of property to change
1297      *  @param mixed $req       Value to replace.
1298      *
1299      *  @return void
1300      */
1301     private function _deferencingRestoreProperty(&$document, $keys, $req)
1302     {
1303         $obj = & $document;
1304
1305         /* find the $req proper spot */
1306         foreach ($keys as $key) {
1307             $obj = & $obj[$key];
1308         }
1309
1310         $obj = $req;
1311
1312         /* Delete reference variable */
1313         unset($obj);
1314     }
1315     // }}}
1316
1317     // object _deferencingQuery($request) {{{
1318     /**
1319      *  Called at deferencig time
1320      *
1321      *  This method takes a dynamic reference and request
1322      *  it to MongoDB.
1323      *
1324      *  @param array $request Dynamic reference
1325      *
1326      *  @return this
1327      */
1328     private function _deferencingQuery($request)
1329     {
1330         $collection = $this->_getCollection();
1331         $cursor     = $collection->find($request['query'], $request['fields']);
1332         if ($request['limit'] > 0) {
1333             $cursor->limit($request['limit']);
1334         }
1335         if ($request['skip'] > 0) {
1336             $cursor->skip($request['skip']);
1337         }
1338
1339         $this->setCursor($cursor);
1340
1341         return $this;
1342     }
1343     // }}}
1344
1345     // void doDeferencing() {{{
1346     /**
1347      *  Perform a deferencing in the current document, if there is
1348      *  any reference.
1349      *
1350      *  ActiveMongo will do its best to group references queries as much
1351      *  as possible, in order to perform as less request as possible.
1352      *
1353      *  ActiveMongo doesn't rely on MongoDB references, but it can support
1354      *  it, but it is prefered to use our referencing.
1355      *
1356      *  @experimental
1357      */
1358     final function doDeferencing($refs=array())
1359     {
1360         /* Get current document */
1361         $document = get_document_vars($this);
1362
1363         if (count($refs)==0) {
1364             /* Inspect the whole document */
1365             $this->getDocumentReferences($document, $refs);
1366         }
1367
1368         $db = $this->_getConnection();
1369
1370         /* Gather information about ActiveMongo Objects
1371          * that we need to create
1372          */
1373         $classes = array();
1374         foreach ($refs as $ref) {
1375             if (!isset($ref['ref']['class'])) {
1376
1377                 /* Support MongoDBRef, we do our best to be compatible {{{ */
1378                 /* MongoDB 'normal' reference */
1379
1380                 $obj = MongoDBRef::get($db, $ref['ref']);
1381
1382                 /* Offset the current document to the right spot */
1383                 /* Very inefficient, never use it, instead use ActiveMongo References */
1384
1385                 $this->_deferencingRestoreProperty($document, $ref['key'], $obj);
1386
1387                 /* Dirty hack, override our current document
1388                  * property with the value itself, in order to
1389                  * avoid replace a MongoDB reference by its content
1390                  */
1391                 $this->_deferencingRestoreProperty($this->_current, $ref['key'], $obj);
1392
1393                 /* }}} */
1394
1395             } else {
1396
1397                 if (isset($ref['ref']['dynamic'])) {
1398                     /* ActiveMongo Dynamic Reference */
1399
1400                     /* Create ActiveMongo object */
1401                     $req = $this->_deferencingCreateObject($ref['ref']['class']);
1402
1403                     /* Restore saved query */
1404                     $req->_deferencingQuery($ref['ref']['dynamic']);
1405
1406                     $results = array();
1407
1408                     /* Add the result set */
1409                     foreach ($req as $result) {
1410                         $results[]  = clone $result;
1411                     }
1412
1413                     /* add  information about the current reference */
1414                     foreach ($ref['ref'] as $key => $value) {
1415                         $results[$key] = $value;
1416                     }
1417
1418                     $this->_deferencingRestoreProperty($document, $ref['key'], $results);
1419
1420                 } else {
1421                     /* ActiveMongo Reference FTW! */
1422                     $classes[$ref['ref']['class']][] = $ref;
1423                 }
1424             }
1425         }
1426
1427         /* {{{ Create needed objects to query MongoDB and replace
1428          * our references by its objects documents.
1429          */
1430         foreach ($classes as $class => $refs) {
1431             $req = $this->_deferencingCreateObject($class);
1432
1433             /* Load list of IDs */
1434             $ids = array();
1435             foreach ($refs as $ref) {
1436                 $ids[] = $ref['ref']['$id'];
1437             }
1438
1439             /* Search to MongoDB once for all IDs found */
1440             $req->find($ids);
1441
1442
1443             /* Replace our references by its objects */
1444             foreach ($refs as $ref) {
1445                 $id    = $ref['ref']['$id'];
1446                 $place = $ref['key'];
1447                 $req->rewind();
1448                 while ($req->getID() != $id && $req->next());
1449
1450                 $this->_deferencingRestoreProperty($document, $place, clone $req);
1451
1452                 unset($obj);
1453             }
1454
1455             /* Release request, remember we
1456              * safely cloned it,
1457              */
1458             unset($req);
1459         }
1460         // }}}
1461
1462         /* Replace the current document by the new deferenced objects */
1463         foreach ($document as $key => $value) {
1464             $this->$key = $value;
1465         }
1466     }
1467     // }}}
1468
1469     // void getColumnDeference(&$document, $propety, ActiveMongo Obj) {{{
1470     /**
1471      *  Prepare a "selector" document to search treaing the property
1472      *  as a reference to the given ActiveMongo object.
1473      *
1474      */
1475     final function getColumnDeference(&$document, $property, ActiveMongo $obj)
1476     {
1477         $document["{$property}.\$id"] = $obj->getID();
1478     }
1479     // }}}
1480
1481     // void findReferences(&$document) {{{
1482     /**
1483      *  Check if in the current document to insert or update
1484      *  exists any references to other ActiveMongo Objects.
1485      *
1486      *  @return void
1487      */
1488     final function findReferences(&$document)
1489     {
1490         if (!is_array($document)) {
1491             return;
1492         }
1493         foreach($document as &$value) {
1494             $parent_class = __CLASS__;
1495             if (is_array($value)) {
1496                 if (MongoDBRef::isRef($value)) {
1497                     /*  If the property we're inspecting is a reference,
1498                      *  we need to remove the values, restoring the valid
1499                      *  Reference.
1500                      */
1501                     $arr = array(
1502                         '$ref'=>1, '$id'=>1, '$db'=>1, 'class'=>1, 'dynamic'=>1
1503                     );
1504                     foreach (array_keys($value) as $key) {
1505                         if (!isset($arr[$key])) {
1506                             unset($value[$key]);
1507                         }
1508                     }
1509                 } else {
1510                     $this->findReferences($value);
1511                 }
1512             } else if ($value InstanceOf $parent_class) {
1513                 $value = $value->getReference();
1514             }
1515         }
1516         /* trick: delete last var. reference */
1517         unset($value);
1518     }
1519     // }}}
1520
1521     // void __clone() {{{
1522     /**
1523      *  Cloned objects are rarely used, but ActiveMongo
1524      *  uses it to create different objects per everyrecord,
1525      *  which is used at deferencing. Therefore cloned object
1526      *  do not contains the recordset, just the actual document,
1527      *  so iterations are not allowed.
1528      *
1529      */
1530     final function __clone()
1531     {
1532         unset($this->_cursor);
1533         $this->_cloned = TRUE;
1534     }
1535     // }}}
1536
1537     // }}}
1538
1539     // GET DOCUMENT ID {{{
1540
1541     // getID() {{{
1542     /**
1543      *  Return the current document ID. If there is
1544      *  no document it would return FALSE.
1545      *
1546      *  @return object|FALSE
1547      */
1548     final public function getID()
1549     {
1550         if ($this->_id instanceof MongoID) {
1551             return $this->_id;
1552         }
1553         return FALSE;
1554     }
1555     // }}}
1556
1557     // string key() {{{
1558     /**
1559      *    Return the current key
1560      *
1561      *    @return string
1562      */
1563     final function key()
1564     {
1565         return (string)$this->getID();
1566     }
1567     // }}}
1568
1569     // }}}
1570
1571     // Fancy (and silly) query abstraction {{{
1572
1573     // _assertNotInQuery() {{{
1574     /**
1575      *  Check if we can modify the query or not. We cannot modify
1576      *  the query if we're iterating over and oldest query, in this case the
1577      *  object must be reset.
1578      *
1579      *  @return void
1580      */
1581     final private function _assertNotInQuery()
1582     {
1583         if ($this->_cursor InstanceOf MongoCursor || $this->_cursor_ex != NULL) {
1584             throw new ActiveMongo_Exception("You cannot modify the query, please reset the object");
1585         }
1586     }
1587     // }}}
1588
1589     // bool servedFromCache() {{{
1590     /**
1591      *  Return True if the current result
1592      *  was provided by a before_query hook (aka cache)
1593      *  or False if it was retrieved from MongoDB
1594      *
1595      *  @return bool
1596      */
1597     final function servedFromCache()
1598     {
1599         return $this->_cached;
1600     }
1601     // }}}
1602
1603     // doQuery() {{{
1604     /**
1605      *  Build the current request and send it to MongoDB.
1606      *
1607      *  @return this
1608      */
1609     final function doQuery($use_cache=TRUE)
1610     {
1611         if ($this->_cursor_ex) {
1612             switch ($this->_cursor_ex) {
1613             case self::FIND_AND_MODIFY:
1614                 $this->_cursor_ex_value = NULL;
1615                 return;
1616             default:
1617                 throw new ActiveMongo_Exception("Invalid _cursor_ex value");
1618             }
1619         }
1620         $this->_assertNotInQuery();
1621
1622         $query = array(
1623             'collection' => $this->getCollectionName(),
1624             'query'      => (array)$this->_query,
1625             'properties' => (array)$this->_properties,
1626             'sort'       => (array)$this->_sort,
1627             'skip'       => $this->_skip,
1628             'limit'      => $this->_limit
1629         );
1630
1631         $this->_cached = FALSE;
1632
1633         self::triggerEvent('before_query', array(&$query, &$documents, $use_cache));
1634
1635         if ($documents InstanceOf MongoCursor && $use_cache) {
1636             $this->_cached = TRUE;
1637             $this->setCursor($documents);
1638             return $this;
1639         }
1640
1641         $col = $this->_getCollection();
1642         if (count($query['properties']) > 0) {
1643             $cursor = $col->find($query['query'], $query['properties']);
1644         } else {
1645             $cursor = $col->find($query['query']);
1646         }
1647         if (count($query['sort']) > 0) {
1648             $cursor->sort($query['sort']);
1649         }
1650         if ($query['limit'] > 0) {
1651             $cursor->limit($query['limit']);
1652         }
1653         if ($query['skip'] > 0) {
1654             $cursor->skip($query['skip']);
1655         }
1656
1657         self::triggerEvent('after_query', array($query, $cursor));
1658
1659         /* Our cursor must be sent to ActiveMongo */
1660         $this->setCursor($cursor);
1661
1662         return $this;
1663     }
1664     // }}}
1665
1666     // properties($props) {{{
1667     /**
1668      *  Select 'properties' or 'columns' to be included in the document,
1669      *  by default all properties are included.
1670      *
1671      *  @param array $props
1672      *
1673      *  @return this
1674      */
1675     final function properties($props)
1676     {
1677         $this->_assertNotInQuery();
1678
1679         if (!is_array($props) && !is_string($props)) {
1680             return FALSE;
1681         }
1682
1683         if (is_string($props)) {
1684             $props = explode(",", $props);
1685         }
1686
1687         foreach ($props as $id => $name) {
1688             $props[trim($name)] = 1;
1689             unset($props[$id]);
1690         }
1691
1692
1693         /* _id should always be included */
1694         $props['_id'] = 1;
1695
1696         $this->_properties = $props;
1697
1698         return $this;
1699     }
1700
1701     final function columns($properties)
1702     {
1703        return $this->properties($properties);
1704     }
1705     // }}}
1706
1707     // where($property, $value) {{{
1708     /**
1709      *  Where abstraction.
1710      *
1711      */
1712     final function where($property_str, $value=NULL)
1713     {
1714         $this->_assertNotInQuery();
1715
1716         if (is_array($property_str)) {
1717             if ($value != NULL) {
1718                 throw new ActiveMongo_Exception("Invalid parameters");
1719             }
1720             foreach ($property_str as $property => $value) {
1721                 if (is_numeric($property)) {
1722                     $property = $value;
1723                     $value    = NULL;
1724                 }
1725                 $this->where($property, $value);
1726             }
1727             return $this;
1728         }
1729
1730         $column = explode(" ", trim($property_str));
1731         if (count($column) != 1 && count($column) != 2) {
1732             throw new ActiveMongo_Exception("Failed while parsing '{$property_str}'");
1733         } else if (count($column) == 2) {
1734
1735             $exp_scalar = TRUE;
1736             switch (strtolower($column[1])) {
1737             case '>':
1738             case '$gt':
1739                 $op = '$gt';
1740                 break;
1741
1742             case '>=':
1743             case '$gte':
1744                 $op = '$gte';
1745                 break;
1746
1747             case '<':
1748             case '$lt':
1749                 $op = '$lt';
1750                 break;
1751
1752             case '<=':
1753             case '$lte':
1754                 $op = '$lte';
1755                 break;
1756
1757             case '==':
1758             case '$eq':
1759             case '=':
1760                 if (is_array($value)) {
1761                     $op = '$all';
1762                     $exp_scalar = FALSE;
1763                 } else {
1764                     $op = NULL;
1765                 }
1766                 break;
1767
1768             case '!=':
1769             case '<>':
1770             case '$ne':
1771                 if (is_array($value)) {
1772                     $op = '$nin';
1773                     $exp_scalar = FALSE;
1774                 } else {
1775                     $op = '$ne';
1776                 }
1777                 break;
1778
1779             case '%':
1780             case 'mod':
1781             case '$mod':
1782                 $op         = '$mod';
1783                 $exp_scalar = FALSE;
1784                 break;
1785
1786             case 'exists':
1787             case '$exists':
1788                 if ($value === NULL) {
1789                     $value = 1;
1790                 }
1791                 $op = '$exists';
1792                 break;
1793
1794             /* regexp  */
1795             case 'regexp':
1796             case 'regex':
1797                 $value = new MongoRegex($value);
1798                 $op = NULL;
1799                 break;
1800
1801             /* arrays */
1802             case 'in':
1803             case '$in':
1804                 $exp_scalar = FALSE;
1805                 $op = '$in';
1806                 break;
1807
1808             case '$nin':
1809             case 'nin':
1810                 $exp_scalar = FALSE;
1811                 $op = '$nin';
1812                 break;
1813
1814
1815             /* geo operations */
1816             case 'near':
1817             case '$near':
1818                 $op = '$near';
1819                 $exp_scalar = FALSE;
1820                 break;
1821
1822             default:
1823                 throw new ActiveMongo_Exception("Failed to parse '{$column[1]}'");
1824             }
1825
1826             if ($exp_scalar && is_array($value)) {
1827                 throw new ActiveMongo_Exception("Cannot use comparing operations with Array");
1828             } else if (!$exp_scalar && !is_array($value)) {
1829                 throw new ActiveMongo_Exception("The operation {$column[1]} expected an Array");
1830             }
1831
1832             if ($op) {
1833                 $value = array($op => $value);
1834             }
1835         } else if (is_array($value)) {
1836             $value = array('$in' => $value);
1837         }
1838
1839         $spot = & $this->_query[$column[0]];
1840         if (is_array($spot) && is_array($value)) {
1841             $spot[key($value)] =  current($value);
1842         } else {
1843             /* simulate AND among same properties if
1844              * multiple values is passed for same property
1845              */
1846             if (isset($spot)) {
1847                 if (is_array($spot)) {
1848                     $spot['$all'][] = $value;
1849                 } else {
1850                     $spot = array('$all' => array($spot, $value));
1851                 }
1852             } else {
1853                 $spot =  $value;
1854             }
1855         }
1856
1857         return $this;
1858     }
1859     // }}}
1860
1861     // sort($sort_str) {{{
1862     /**
1863      *  Abstract the documents sorting.
1864      *
1865      *  @param string $sort_str List of properties to use as sorting
1866      *
1867      *  @return this
1868      */
1869     final function sort($sort_str)
1870     {
1871         $this->_assertNotInQuery();
1872
1873         $this->_sort = array();
1874         foreach ((array)explode(",", $sort_str) as $sort_part_str) {
1875             $sort_part = explode(" ", trim($sort_part_str), 2);
1876             switch(count($sort_part)) {
1877             case 1:
1878                 $sort_part[1] = 'ASC';
1879                 break;
1880             case 2:
1881                 break;
1882             default:
1883                 throw new ActiveMongo_Exception("Don't know how to parse {$sort_part_str}");
1884             }
1885
1886             switch (strtoupper($sort_part[1])) {
1887             case 'ASC':
1888                 $sort_part[1] = 1;
1889                 break;
1890             case 'DESC':
1891                 $sort_part[1] = -1;
1892                 break;
1893             default:
1894                 throw new ActiveMongo_Exception("Invalid sorting direction `{$sort_part[1]}`");
1895             }
1896             $this->_sort[ $sort_part[0] ] = $sort_part[1];
1897         }
1898
1899         return $this;
1900     }
1901     // }}}
1902
1903     // limit($limit, $skip) {{{
1904     /**
1905      *  Abstract the limitation and pagination of documents.
1906      *
1907      *  @param int $limit Number of max. documents to retrieve
1908      *  @param int $skip  Number of documents to skip
1909      *
1910      *  @return this
1911      */
1912     final function limit($limit=0, $skip=0)
1913     {
1914         $this->_assertNotInQuery();
1915
1916         if ($limit < 0 || $skip < 0) {
1917             return FALSE;
1918         }
1919         $this->_limit = $limit;
1920         $this->_skip  = $skip;
1921
1922         return $this;
1923     }
1924     // }}}
1925
1926     // FindAndModify(Array $document) {{{
1927     /**
1928      *  findAndModify
1929      *
1930      *
1931      */
1932     final function findAndModify($document)
1933     {
1934         $this->_assertNotInQuery();
1935
1936         if (count($document) === 0) {
1937             throw new ActiveMongo_Exception("Empty \$document is not allowed");
1938         }
1939
1940         $this->_cursor_ex     = self::FIND_AND_MODIFY;
1941         $this->_findandmodify = $document;
1942
1943         return $this;
1944     }
1945
1946     private function _execFindAndModify()
1947     {
1948         $query = (array)$this->_query;
1949
1950         $query = array(
1951             "findandmodify" => $this->getCollectionName(),
1952             "query" => $query,
1953             "update" => array('$set' => $this->_findandmodify),
1954             "new" => TRUE,
1955         );
1956         if (isset($this->_sort)) {
1957             $query["sort"] =  $this->_sort;
1958         }
1959         $this->_cursor_ex_value = $this->sendCMD($query);
1960
1961         $this->_findandmodify_cnt++;
1962     }
1963     // }}}
1964
1965     // }}}
1966
1967     // __sleep() {{{
1968     /**
1969      *  Return a list of properties to serialize, to save
1970      *  into MongoDB
1971      *
1972      *  @return array
1973      */
1974     function __sleep()
1975     {
1976         return array_keys(get_document_vars($this));
1977     }
1978     // }}}
1979
1980 }
1981
1982 require_once dirname(__FILE__)."/Validators.php";
1983 require_once dirname(__FILE__)."/Exceptions.php";
1984
1985 /*
1986  * Local variables:
1987  * tab-width: 4
1988  * c-basic-offset: 4
1989  * End:
1990  * vim600: sw=4 ts=4 fdm=marker
1991  * vim<600: sw=4 ts=4
1992  */