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