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
  39 // Class FilterException {{{
  40 /**
  41  *  FilterException
  42  *
  43  *  This is Exception is thrown if any validation
  44  *  fails when save() is called.
  45  *
  46  */
  47 final class FilterException extends Exception
  48 {
  49 }
  50 // }}}
  51
  52 // array get_object_vars_ex(stdobj $obj) {{{
  53 /**
  54  *  Simple hack to avoid get private and protected variables
  55  *
  56  *  @param obj
  57  *
  58  *  @return array
  59  */
  60 function get_object_vars_ex($obj)
  61 {
  62     return get_object_vars($obj);
  63 }
  64 // }}}
  65
  66 /**
  67  *  ActiveMongo
  68  *
  69  *  Simple ActiveRecord pattern built on top of MongoDB. This class
  70  *  aims to provide easy iteration, data validation before update,
  71  *  and efficient update.
  72  *
  73  *  @author César D. Rodas <crodas@php.net>
  74  *  @license PHP License
  75  *  @package ActiveMongo
  76  *  @version 1.0
  77  *
  78  */
  79 abstract class ActiveMongo implements Iterator
  80 {
  81
  82     // properties {{{
  83     /**
  84      *  Current databases objects
  85      *
  86      *  @type array
  87      */
  88     private static $_dbs;
  89     /**
  90      *  Current collections objects
  91      *
  92      *  @type array
  93      */
  94     private static $_collections;
  95     /**
  96      *  Current connection to MongoDB
  97      *
  98      *  @type MongoConnection
  99      */
 100     private static $_conn;
 101     /**
 102      *  Database name
 103      *
 104      *  @type string
 105      */
 106     private static $_db;
 107     /**
 108      *  Host name
 109      *
 110      *  @type string
 111      */
 112     private static $_host;
 113     /**
 114      *  Current document
 115      *
 116      *  @type array
 117      */
 118     private $_current = array();
 119     /**
 120      *  Result cursor
 121      *
 122      *  @type MongoCursor
 123      */
 124     private $_cursor  = null;
 125     /**
 126      *  Current document ID
 127      *
 128      *  @type MongoID
 129      */
 130     private $_id;
 131
 132     private $_cloned = false;
 133     // }}}
 134
 135     // string getCollectionName() {{{
 136     /**
 137      *  Get Collection Name, by default the class name,
 138      *  but you it can be override at the class itself to give
 139      *  a custom name.
 140      *
 141      *  @return string Collection Name
 142      */
 143     protected function getCollectionName()
 144     {
 145         return strtolower(get_class($this));
 146     }
 147     // }}}
 148
 149     // string getDatabaseName() {{{
 150     /**
 151      *  Get Database Name, by default it is used
 152      *  the db name set by ActiveMong::connect()
 153      *
 154      *  @return string DB Name
 155      */
 156     protected function getDatabaseName()
 157     {
 158         if (is_null(self::$_db)) {
 159             throw new MongoException("There is no information about the default DB name");
 160         }
 161         return self::$_db;
 162     }
 163     // }}}
 164
 165     // void install() {{{
 166     /**
 167      *  Install.
 168      *
 169      *  This static method iterate over the classes lists,
 170      *  and execute the setup() method on every ActiveMongo
 171      *  subclass. You should do this just once.
 172      *
 173      */
 174     final public static function install()
 175     {
 176         $classes = array_reverse(get_declared_classes());
 177         foreach ($classes as $class)
 178         {
 179             if ($class == __CLASS__) {
 180                 break;
 181             }
 182             if (is_subclass_of($class, __CLASS__)) {
 183                 $obj = new $class;
 184                 $obj->setup();
 185             }
 186         }
 187     }
 188     // }}}
 189
 190     // void connection($db, $host) {{{
 191     /**
 192      *  Connect
 193      *
 194      *  This method setup parameters to connect to a MongoDB
 195      *  database. The connection is done when it is needed.
 196      *
 197      *  @param string $db   Database name
 198      *  @param string $host Host to connect
 199      *
 200      *  @return void
 201      */
 202     final public static function connect($db, $host='localhost')
 203     {
 204         self::$_host = $host;
 205         self::$_db   = $db;
 206     }
 207     // }}}
 208
 209     // MongoConnection _getConnection() {{{
 210     /**
 211      *  Get Connection
 212      *
 213      *  Get a valid database connection
 214      *
 215      *  @return MongoConnection
 216      */
 217     final protected function _getConnection()
 218     {
 219         if (is_null(self::$_conn)) {
 220             if (is_null(self::$_host)) {
 221                 self::$_host = 'localhost';
 222             }
 223             self::$_conn = new Mongo(self::$_host);
 224         }
 225         $dbname = $this->getDatabaseName();
 226         if (!isSet(self::$_dbs[$dbname])) {
 227             self::$_dbs[$dbname] = self::$_conn->selectDB($dbname);
 228         }
 229         return self::$_dbs[$dbname];
 230     }
 231     // }}}
 232
 233     // MongoCollection _getCollection() {{{
 234     /**
 235      *  Get Collection
 236      *
 237      *  Get a collection connection.
 238      *
 239      *  @return MongoCollection
 240      */
 241     final protected function _getCollection()
 242     {
 243         $colName = $this->getCollectionName();
 244         if (!isset(self::$_collections[$colName])) {
 245             self::$_collections[$colName] = self::_getConnection()->selectCollection($colName);
 246         }
 247         return self::$_collections[$colName];
 248     }
 249     // }}}
 250
 251     // bool getCurrentSubDocument(array &$document, string $parent_key, array $values, array $past_values) {{{
 252     /**
 253      *  Generate Sub-document
 254      *
 255      *  This method build the difference between the current sub-document,
 256      *  and the origin one. If there is no difference, it would do nothing,
 257      *  otherwise it would build a document containing the differences.
 258      *
 259      *  @param array  &$document    Document target
 260      *  @param string $parent_key   Parent key name
 261      *  @param array  $values       Current values
 262      *  @param array  $past_values  Original values
 263      *
 264      *  @return false
 265      */
 266     final function getCurrentSubDocument(&$document, $parent_key, Array $values, Array $past_values)
 267     {
 268         /**
 269          *  The current property is a embedded-document,
 270          *  now we're looking for differences with the
 271          *  previous value (because we're on an update).
 272          *
 273          *  It behaves exactly as getCurrentDocument,
 274          *  but this is simples (it doesn't support
 275          *  yet filters)
 276          */
 277         foreach ($values as $key => $value) {
 278             $super_key = "{$parent_key}.{$key}";
 279             if (is_array($value)) {
 280                 /**
 281                  *  Inner document detected
 282                  */
 283                 if (!isset($past_values[$key]) || !is_array($past_values[$key])) {
 284                     /**
 285                      *  We're lucky, it is a new sub-document,
 286                      *  we simple add it
 287                      */
 288                     $document['$set'][$super_key] = $value;
 289                 } else {
 290                     /**
 291                      *  This is a document like this, we need
 292                      *  to find out the differences to avoid
 293                      *  network overhead.
 294                      */
 295                     if (!$this->getCurrentSubDocument($document, $super_key, $value, $past_values[$key])) {
 296                         return false;
 297                     }
 298                 }
 299                 continue;
 300             } else if (!isset($past_values[$key]) || $past_values[$key] != $value) {
 301                 $document['$set'][$super_key] = $value;
 302             }
 303         }
 304
 305         foreach (array_diff(array_keys($past_values), array_keys($values)) as $key) {
 306             $super_key = "{$parent_key}.{$key}";
 307             $document['$unset'][$super_key] = 1;
 308         }
 309
 310         return true;
 311     }
 312     // }}}
 313
 314     // array getCurrentDocument(bool $update) {{{
 315     /**
 316      *    Get Current Document
 317      *
 318      *    Based on this object properties a new document (Array)
 319      *    is returned. If we're modifying an document, just the modified
 320      *    properties are included in this document, which uses $set,
 321      *    $unset, $pushAll and $pullAll.
 322      *
 323      *
 324      *    @param bool $update
 325      *
 326      *    @return array
 327      */
 328     final protected function getCurrentDocument($update=false, $current=false)
 329     {
 330         $document = array();
 331         $object   = get_object_vars_ex($this);
 332
 333         if (!$current) {
 334             $current = (array)$this->_current;
 335         }
 336
 337         $this->findReferences($object);
 338
 339         foreach ($object as $key => $value) {
 340             if (!$value) {
 341                 continue;
 342             }
 343             if ($update) {
 344                 if (is_array($value) && isset($current[$key])) {
 345                     /**
 346                      *  If the Field to update is an array, it has a different
 347                      *  behaviour other than $set and $unset. Fist, we need
 348                      *  need to check if it is an array or document, because
 349                      *  they can't be mixed.
 350                      *
 351                      */
 352                     if (!is_array($current[$key])) {
 353                         /**
 354                          *  We're lucky, the field wasn't
 355                          *  an array previously.
 356                          */
 357                         $this->_call_filter($key, $value, $current[$key]);
 358                         $document['$set'][$key] = $value;
 359                         continue;
 360                     }
 361
 362                     if (!$this->getCurrentSubDocument($document, $key, $value, $current[$key])) {
 363                         throw new Exception("{$key}: Array and documents are not compatible");
 364                     }
 365                 } else if(!isset($current[$key]) || $value !== $current[$key]) {
 366                     /**
 367                      *  It is 'linear' field that has changed, or
 368                      *  has been modified.
 369                      */
 370                     $past_value = isset($current[$key]) ? $current[$key] : null;
 371                     $this->_call_filter($key, $value, $past_value);
 372                     $document['$set'][$key] = $value;
 373                 }
 374             } else {
 375                 /**
 376                  *  It is a document insertation, so we
 377                  *  create the document.
 378                  */
 379                 $this->_call_filter($key, $value, null);
 380                 $document[$key] = $value;
 381             }
 382         }
 383
 384         /* Updated behaves in a diff. way */
 385         if ($update) {
 386             foreach (array_diff(array_keys($this->_current), array_keys($object)) as $property) {
 387                 if ($property == '_id') {
 388                     continue;
 389                 }
 390                 $document['$unset'][$property] = 1;
 391             }
 392         }
 393
 394         if (count($document) == 0) {
 395             return array();
 396         }
 397         return $document;
 398     }
 399     // }}}
 400
 401     // void _call_filter(string $key, mixed &$value, mixed $past_value) {{{
 402     /**
 403      *  *Internal Method*
 404      *
 405      *  This method check if the current document property has
 406      *  a filter method, if so, call it.
 407      *
 408      *  If the filter returns false, throw an Exception.
 409      *
 410      *  @return void
 411      */
 412     private function _call_filter($key, &$value, $past_value)
 413     {
 414         $filter = array($this, "{$key}_filter");
 415         if (is_callable($filter)) {
 416             $filter = call_user_func_array($filter, array(&$value, $past_value));
 417             if ($filter===false) {
 418                 throw new FilterException("{$key} filter failed");
 419             }
 420             $this->$key = $value;
 421         }
 422     }
 423     // }}}
 424
 425     // void setCursor(MongoCursor $obj) {{{
 426     /**
 427      *  Set Cursor
 428      *
 429      *  This method receive a MongoCursor and make
 430      *  it iterable.
 431      *
 432      *  @param MongoCursor $obj
 433      *
 434      *  @return void
 435      */
 436     final protected function setCursor(MongoCursor $obj)
 437     {
 438         $this->_cursor = $obj;
 439         $this->setResult($obj->getNext());
 440     }
 441     // }}}
 442
 443     // void reset() {{{
 444     /**
 445      *  Reset our Object, delete the current cursor if any, and reset
 446      *  unsets the values.
 447      *
 448      *  @return void
 449      */
 450     final function reset()
 451     {
 452         $this->_count = 0;
 453         $this->_cursor = null;
 454         $this->setResult(array());
 455     }
 456     // }}}
 457
 458     // void setResult(Array $obj) {{{
 459     /**
 460      *  Set Result
 461      *
 462      *  This method takes an document and copy it
 463      *  as properties in this object.
 464      *
 465      *  @param Array $obj
 466      *
 467      *  @return void
 468      */
 469     final protected function setResult($obj)
 470     {
 471         /* Unsetting previous results, if any */
 472         foreach (array_keys((array)$this->_current) as $key) {
 473             unset($this->$key);
 474         }
 475
 476         /* Add our current resultset as our object's property */
 477         foreach ((array)$obj as $key => $value) {
 478             if ($key[0] == '$') {
 479                 continue;
 480             }
 481             $this->$key = $value;
 482         }
 483
 484         /* Save our record */
 485         $this->_current = $obj;
 486     }
 487     // }}}
 488
 489     // this find([$_id]) {{{
 490     /**
 491      *    Simple find.
 492      *
 493      *    Really simple find, which uses this object properties
 494      *    for fast filtering
 495      *
 496      *    @return object this
 497      */
 498     final function find($_id = null)
 499     {
 500         $vars = get_object_vars_ex($this);
 501         foreach ($vars as $key => $value) {
 502             if (!$value) {
 503                 unset($vars[$key]);
 504             }
 505             if ($value InstanceOf ActiveMongo) {
 506                 $this->getColumnDeference($vars, $key, $value);
 507                 unset($vars[$key]); /* delete old value */
 508             }
 509         }
 510         if ($_id != null) {
 511             if (is_array($_id)) {
 512                 $vars['_id'] = array('$in' => $_id);
 513             } else {
 514                 $vars['_id'] = $_id;
 515             }
 516         }
 517         $res  = $this->_getCollection()->find($vars);
 518         $this->setCursor($res);
 519         return $this;
 520     }
 521     // }}}
 522
 523     // void save(bool $async) {{{
 524     /**
 525      *    Save
 526      *
 527      *    This method save the current document in MongoDB. If
 528      *    we're modifying a document, a update is performed, otherwise
 529      *    the document is inserted.
 530      *
 531      *    On updates, special operations such as $set, $pushAll, $pullAll
 532      *    and $unset in order to perform efficient updates
 533      *
 534      *    @param bool $async
 535      *
 536      *    @return void
 537      */
 538     final function save($async=true)
 539     {
 540         $update = isset($this->_id) && $this->_id InstanceOf MongoID;
 541         $conn   = $this->_getCollection();
 542         $obj    = $this->getCurrentDocument($update);
 543         if (count($obj) == 0) {
 544             return; /*nothing to do */
 545         }
 546
 547         /* PRE-save hook */
 548         $this->pre_save($update ? 'update' : 'create', $obj);
 549         if ($update) {
 550             $conn->update(array('_id' => $this->_id), $obj);
 551             foreach ($obj as $key => $value) {
 552                 if ($key[0] == '$') {
 553                     continue;
 554                 }
 555                 $this->_current[$key] = $value;
 556             }
 557             $this->on_update();
 558         } else {
 559             $conn->insert($obj, $async);
 560             $this->_id      = $obj['_id'];
 561             $this->_current = $obj;
 562             $this->on_save();
 563         }
 564     }
 565     // }}}
 566
 567     // bool delete() {{{
 568     /**
 569      *  Delete the current document
 570      *
 571      *  @return bool
 572      */
 573     final function delete()
 574     {
 575         if ($this->valid()) {
 576             return $this->_getCollection()->remove(array('_id' => $this->_id));
 577         }
 578         return false;
 579     }
 580     // }}}
 581
 582     // void drop() {{{
 583     /**
 584      *  Delete the current colleciton and all its documents
 585      *
 586      *  @return void
 587      */
 588     final static function drop()
 589     {
 590         $class = get_called_class();
 591         if ($class == __CLASS__) {
 592             return false;
 593         }
 594         $obj = new $class;
 595         return $obj->_getCollection()->drop();
 596     }
 597     // }}}
 598
 599     // int count() {{{
 600     /**
 601      *  Return the number of documents in the actual request. If
 602      *  we're not in a request, it will return 0.
 603      *
 604      *  @return int
 605      */
 606     final function count()
 607     {
 608         if ($this->valid()) {
 609             return $this->_cursor->count();
 610         }
 611         return 0;
 612     }
 613     // }}}
 614
 615     // ITERATOR {{{
 616
 617     // bool valid() {{{
 618     /**
 619      *    Valid
 620      *
 621      *    Return if we're on an iteration and if it is still valid
 622      *
 623      *    @return true
 624      */
 625     final function valid()
 626     {
 627         return $this->_cursor InstanceOf MongoCursor && $this->_cursor->valid();
 628     }
 629     // }}}
 630
 631     // bool next() {{{
 632     /**
 633      *    Move to the next document
 634      *
 635      *    @return bool
 636      */
 637     final function next()
 638     {
 639         if ($this->_cloned) {
 640             throw new MongoException("Cloned objects can't iterate");
 641         }
 642         return $this->_cursor->next();
 643     }
 644     // }}}
 645
 646     // this current() {{{
 647     /**
 648      *    Return the current object, and load the current document
 649      *    as this object property
 650      *
 651      *    @return object
 652      */
 653     final function current()
 654     {
 655         $this->setResult($this->_cursor->current());
 656         return $this;
 657     }
 658     // }}}
 659
 660     // bool rewind() {{{
 661     /**
 662      *    Go to the first document
 663      */
 664     final function rewind()
 665     {
 666         return $this->_cursor->rewind();
 667     }
 668     // }}}
 669
 670     // }}}
 671
 672     // REFERENCES {{{
 673
 674     // array getReference() {{{
 675     /**
 676      *  ActiveMongo extended the Mongo references, adding
 677      *  the concept of 'dynamic' requests, saving in the database
 678      *  the current query with its options (sort, limit, etc).
 679      *
 680      *  This is useful to associate a document with a given
 681      *  request. To undestand this better please see the 'reference'
 682      *  example.
 683      *
 684      *  @return array
 685      */
 686     final function getReference($dynamic=false)
 687     {
 688         if (!$this->getID()) {
 689             return null;
 690         }
 691
 692         $document = array(
 693             '$ref'  => $this->getCollectionName(),
 694             '$id'   => $this->getID(),
 695             '$db'   => $this->getDatabaseName(),
 696             'class' => get_class($this),
 697         );
 698
 699         if ($dynamic && $this->valid()) {
 700             $cursor = $this->_cursor;
 701             if (!is_callable(array($cursor, "getQuery"))) {
 702                 throw new Exception("Please upgrade your PECL/Mongo module to use this feature");
 703             }
 704             $document['dynamic'] = array();
 705             $query  = $cursor->getQuery();
 706             foreach ($query as $type => $value) {
 707                 $document['dynamic'][$type] = $value;
 708             }
 709         }
 710         return $document;
 711     }
 712     // }}}
 713
 714     // void getCurrentReferences($document, &$refs) {{{
 715     /**
 716      *  Get Current References
 717      *
 718      *  Inspect the current document trying to get any references,
 719      *  if any.
 720      *
 721      *  @param array $document   Current document
 722      *  @param array &$refs      References found in the document.
 723      *  @param array $parent_key Parent key
 724      *
 725      *  @return void
 726      */
 727     final protected function getCurrentReferences($document, &$refs, $parent_key=null)
 728     {
 729         foreach ($document as $key => $value) {
 730            if (is_array($value)) {
 731                if (MongoDBRef::isRef($value)) {
 732                    $pkey   = $parent_key;
 733                    $pkey[] = $key;
 734                    $refs[] = array('ref' => $value, 'key' => $pkey);
 735                } else {
 736                    $parent_key[] = $key;
 737                    $this->getCurrentReferences($value, $refs, $parent_key);
 738                }
 739            }
 740         }
 741     }
 742     // }}}
 743
 744     // void doDeferencing() {{{
 745     /**
 746      *  Perform a deferencing in the current document, if there is
 747      *  any reference.
 748      *
 749      *  ActiveMongo will do its best to group references queries as much
 750      *  as possible, in order to perform as less request as possible.
 751      *
 752      *  ActiveMongo doesn't rely on MongoDB references, but it can support
 753      *  it, but it is prefered to use our referencing.
 754      *
 755      *  @experimental
 756      */
 757     final function doDeferencing($refs=array())
 758     {
 759         /* Get current document */
 760         $document = get_object_vars_ex($this);
 761
 762         if (count($refs)==0) {
 763             /* Inspect the whole document */
 764             $this->getCurrentReferences($document, $refs);
 765         }
 766
 767         $db = $this->_getConnection();
 768
 769         /* Gather information about ActiveMongo Objects
 770          * that we need to create
 771          */
 772         $classes = array();
 773         foreach ($refs as $ref) {
 774             if (!isset($ref['ref']['class'])) {
 775
 776                 /* Support MongoDBRef {{{ */
 777                 /* MongoDB 'normal' reference */
 778                 /* Offset the current document to the right spot */
 779                 /* Very inefficient, never use it, instead use ActiveMongo References */
 780                 $obj = & $document;
 781                 foreach ($ref['key'] as $key) {
 782                     $obj = & $obj[$key];
 783                 }
 784                 $obj = MongoDBRef::get($db, $ref['ref']);
 785
 786                 /* Dirty hack, override our current document
 787                  * property with the value itself, in order to
 788                  * avoid replace a MongoDB reference by its content
 789                  */
 790                 $_obj = & $this->_current;
 791                 foreach ($ref['key'] as $key) {
 792                     $_obj = & $_obj[$key];
 793                 }
 794                 $_obj = MongoDBRef::get($db, $ref['ref']);
 795
 796
 797                 /* Delete reference variable */
 798                 unset($obj, $_obj);
 799                 /* }}} */
 800
 801             } else {
 802                 /* ActiveMongo Reference FTW! */
 803                 $classes[$ref['ref']['class']][] = $ref;
 804             }
 805         }
 806
 807         /* {{{ Create needed objects to query MongoDB and replace
 808          * our references by its objects documents.
 809          *
 810          */
 811         foreach ($classes as $class => $refs) {
 812             $req = new $class;
 813
 814             /* Load list of IDs */
 815             $ids = array();
 816             foreach ($refs as $ref) {
 817                 $ids[] = $ref['ref']['$id'];
 818             }
 819
 820             /* Search to MongoDB once for all IDs found */
 821             $req->find($ids);
 822
 823             if ($req->count() != count($refs)) {
 824                 $total    = $req->count();
 825                 $expected = count($refs);
 826                 throw new MongoException("Dereferencing error, MongoDB replied {$total} objects, we expected {$expected}");
 827             }
 828
 829             /* Replace our references by its objects */
 830             foreach ($refs as $ref) {
 831                 $id    = $ref['ref']['$id'];
 832                 $place = $ref['key'];
 833                 $req->rewind();
 834                 while ($req->getID() != $id && $req->next());
 835
 836                 assert($req->getID() == $id);
 837
 838                 $obj = & $document;
 839                 foreach ($ref['key'] as $key) {
 840                     $obj = & $obj[$key];
 841                 }
 842                 $obj = clone $req;
 843
 844                 /* Delete reference variable */
 845                 unset($obj);
 846             }
 847
 848             /* Release request, remember we
 849              * safely cloned it,
 850              */
 851             unset($req);
 852         }
 853         // }}}
 854
 855         /* Replace the current document by the new deferenced objects */
 856         foreach ($document as $key => $value) {
 857             $this->$key = $value;
 858         }
 859     }
 860     // }}}
 861
 862     // void getColumnDeference(&$document, $propety, ActiveMongo Obj) {{{
 863     /**
 864      *  Prepare a "selector" document to search treaing the property
 865      *  as a reference to the given ActiveMongo object.
 866      *
 867      */
 868     final function getColumnDeference(&$document, $property, ActiveMongo $obj)
 869     {
 870         $document["{$property}.\$id"] = $obj->getID();
 871     }
 872     // }}}
 873
 874     // void findReferences(&$document) {{{
 875     /**
 876      *  Check if in the current document to insert or update
 877      *  exists any references to other ActiveMongo Objects.
 878      *
 879      *  @return void
 880      */
 881     final function findReferences(&$document)
 882     {
 883         if (!is_array($document)) {
 884             return;
 885         }
 886         foreach($document as &$value) {
 887             if ($value InstanceOf ActiveMongo) {
 888                 $value = $value->getReference();
 889             } else if (is_array($value)) {
 890                 $this->findReferences($value);
 891             }
 892         }
 893         /* trick: delete last var. reference */
 894         unset($value);
 895     }
 896     // }}}
 897
 898     // void __clone() {{{
 899     /**
 900      *  Cloned objects are rarely used, but ActiveMongo
 901      *  uses it to create different objects per everyrecord,
 902      *  which is used at deferencing. Therefore cloned object
 903      *  do not contains the recordset, just the actual document,
 904      *  so iterations are not allowed.
 905      *
 906      */
 907     final function __clone()
 908     {
 909         unset($this->_cursor);
 910         $this->_cloned = true;
 911     }
 912     // }}}
 913
 914     // }}}
 915
 916     // GET DOCUMENT ID {{{
 917
 918     // getID() {{{
 919     /**
 920      *  Return the current document ID. If there is
 921      *  no document it would return false.
 922      *
 923      *  @return object|false
 924      */
 925     final public function getID()
 926     {
 927         if ($this->_id instanceof MongoID) {
 928             return $this->_id;
 929         }
 930         return false;
 931     }
 932     // }}}
 933
 934     // string key() {{{
 935     /**
 936      *    Return the current key
 937      *
 938      *    @return string
 939      */
 940     final function key()
 941     {
 942         return $this->getID();
 943     }
 944     // }}}
 945
 946     // }}}
 947
 948     // HOOKS {{{
 949
 950     // void pre_save($action, & $document) {{{
 951     /**
 952      *    PRE-save Hook,
 953      *
 954      *    This method is fired just before an insert or updated. The document
 955      *    is passed by reference, so it can be modified. Also if for instance
 956      *    one property is missing an Exception could be thrown to avoid
 957      *    the insert.
 958      *
 959      *
 960      *    @param string $action     Update or Create
 961      *    @param array  &$document Document that will be sent to MongoDB.
 962      *
 963      *    @return void
 964      */
 965     protected function pre_save($action, Array &$document)
 966     {
 967     }
 968     // }}}
 969
 970     // void on_save() {{{
 971     /**
 972      *    On Save hook
 973      *
 974      *    This method is fired right after an insert is performed.
 975      *
 976      *    @return void
 977      */
 978     protected function on_save()
 979     {
 980     }
 981     // }}}
 982
 983     // void on_update() {{{
 984     /**
 985      *    On Update hook
 986      *
 987      *    This method is fired right after an update is performed.
 988      *
 989      *    @return void
 990      */
 991     protected function on_update()
 992     {
 993     }
 994     // }}}
 995
 996     // void on_iterate() {{{
 997     /**
 998      *    On Iterate Hook
 999      *
1000      *    This method is fired right after a new document is loaded
1001      *    from the recorset, it could be useful to load references to other
1002      *    documents.
1003      *
1004      *    @return void
1005      */
1006     protected function on_iterate()
1007     {
1008     }
1009     // }}}
1010
1011     // }}}
1012
1013     // void setup() {{{
1014     /**
1015      *  This method should contain all the indexes, and shard keys
1016      *  needed by the current collection. This try to make
1017      *  installation on development environments easier.
1018      */
1019     function setup()
1020     {
1021     }
1022     // }}}
1023
1024     // bool addIndex(array $columns, array $options) {{{
1025     /**
1026      *  addIndex
1027      *
1028      *  Create an Index in the current collection.
1029      *
1030      *  @param array $columns L ist of columns
1031      *  @param array $options Options
1032      *
1033      *  @return bool
1034      */
1035     final function addIndex($columns, $options=array())
1036     {
1037         $default_options = array(
1038             'background' => 1,
1039         );
1040
1041        foreach ($default_options as $option => $value) {
1042             if (!isset($options[$option])) {
1043                 $options[$option] = $value;
1044             }
1045         }
1046
1047         $collection = $this->_getCollection();
1048
1049         return $collection->ensureIndex($columns, $options);
1050     }
1051     // }}}
1052
1053     // string __toString() {{{
1054     /**
1055      *  To String
1056      *
1057      *  If this object is treated as a string,
1058      *  it would return its ID.
1059      *
1060      *  @return string
1061      */
1062     final function __toString()
1063     {
1064         return (string)$this->getID();
1065     }
1066     // }}}
1067
1068     // array sendCmd(array $cmd) {{{
1069     /**
1070      *  This method sends a command to the current
1071      *  database.
1072      *
1073      *  @param array $cmd Current command
1074      *
1075      *  @return array
1076      */
1077     final protected function sendCmd($cmd)
1078     {
1079         return $this->_getConnection()->command($cmd);
1080     }
1081     // }}}
1082
1083 }
1084
1085 /*
1086  * Local variables:
1087  * tab-width: 4
1088  * c-basic-offset: 4
1089  * End:
1090  * vim600: sw=4 ts=4 fdm=marker
1091  * vim<600: sw=4 ts=4
1092  */