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