ActiveMongo.php

   1 <?php
   2 /*
   3   +----------------------------------------------------------------------+
   4   | Copyright (c) 2009 The PHP Group                                     |
   5   +----------------------------------------------------------------------+
   6   | This source file is subject to version 3.0 of the PHP license,       |
   7   | that is bundled with this package in the file LICENSE, and is        |
   8   | available through the world-wide-web at the following url:           |
   9   | http://www.php.net/license/3_0.txt.                                  |
  10   | If you did not receive a copy of the PHP license and are unable to   |
  11   | obtain it through the world-wide-web, please send a note to          |
  12   | license@php.net so we can mail you a copy immediately.               |
  13   +----------------------------------------------------------------------+
  14   | Authors: Cesar Rodas <crodas@php.net>                                |
  15   +----------------------------------------------------------------------+
  16 */
  17
  18
  19 // Class FilterException {{{
  20 /**
  21  *  FilterException
  22  *
  23  *  This is Exception is thrown if any validation
  24  *  fails when save() is called.
  25  *
  26  */
  27 final class FilterException extends Exception
  28 {
  29 }
  30 // }}}
  31
  32 // array get_object_vars_ex(stdobj $obj) {{{
  33 /**
  34  *  Simple hack to avoid get private and protected variables
  35  *
  36  *  @param obj
  37  *
  38  *  @return array
  39  */
  40 function get_object_vars_ex($obj)
  41 {
  42     return get_object_vars($obj);
  43 }
  44 // }}}
  45
  46 /**
  47  *  ActiveMongo
  48  *
  49  *  Simple ActiveRecord pattern built on top of MongoDB. This class
  50  *  aims to provide easy iteration, data validation before update,
  51  *  and efficient update.
  52  *
  53  *  @author César D. Rodas <crodas@php.net>
  54  *  @license PHP License
  55  *  @package ActiveMongo
  56  *  @version 1.0
  57  *
  58  */
  59 abstract class ActiveMongo implements Iterator
  60 {
  61
  62     // properties {{{
  63     /**
  64      *    Current collections
  65      *
  66      *    @type array
  67      */
  68     private static $_collections;
  69     /**
  70      *    Current connection to MongoDB
  71      *
  72      *    @type MongoConnection
  73      */
  74     private static $_conn;
  75     /**
  76      *    Database name
  77      *
  78      *    @type string
  79      */
  80     private static $_db;
  81     /**
  82      *    Host name
  83      *
  84      *    @type string
  85      */
  86     private static $_host;
  87     /**
  88      *    Current document
  89      *
  90      *    @type array
  91      */
  92     private $_current = array();
  93     /**
  94      *    Result cursor
  95      *
  96      *    @type MongoCursor
  97      */
  98     private $_cursor  = null;
  99     /**
 100      *    Current document ID
 101      *
 102      *    @type MongoID
 103      */
 104     private $_id;
 105     // }}}
 106
 107     // string getCollectionName() {{{
 108     /**
 109      *  Get Collection Name, by default the class name,
 110      *  but you it can be override at the class itself to give
 111      *  a custom name.
 112      *
 113      *  @return string Colleciton Name
 114      */
 115     protected function getCollectionName()
 116     {
 117         return strtolower(get_class($this));
 118     }
 119     // }}}
 120
 121     // void install() {{{
 122     /**
 123      *  Install.
 124      *
 125      *  This static method iterate over the classes lists,
 126      *  and execute the setup() method on every ActiveMongo
 127      *  subclass. You should do this just once.
 128      *
 129      */
 130     final public static function install()
 131     {
 132         $classes = array_reverse(get_declared_classes());
 133         foreach ($classes as $class)
 134         {
 135             if ($class == __CLASS__) {
 136                 break;
 137             }
 138             if (is_subclass_of($class, __CLASS__)) {
 139                 $obj = new $class;
 140                 $obj->setup();
 141             }
 142         }
 143     }
 144     // }}}
 145
 146     // void connection($db, $host) {{{
 147     /**
 148      *  Connect
 149      *
 150      *  This method setup parameters to connect to a MongoDB
 151      *  database. The connection is done when it is needed.
 152      *
 153      *  @param string $db   Database name
 154      *  @param string $host Host to connect
 155      *
 156      *  @return void
 157      */
 158     final public static function connect($db, $host='localhost')
 159     {
 160         self::$_host = $host;
 161         self::$_db   = $db;
 162     }
 163     // }}}
 164
 165     // MongoConnection _getConnection() {{{
 166     /**
 167      *  Get Connection
 168      *
 169      *  Get a valid database connection
 170      *
 171      *  @return MongoConnection
 172      */
 173     final protected static function _getConnection()
 174     {
 175         if (is_null(self::$_conn)) {
 176             self::$_conn = new Mongo(self::$_host);
 177         }
 178         return self::$_conn->selectDB(self::$_db);
 179     }
 180     // }}}
 181
 182     // MongoCollection _getCollection() {{{
 183     /**
 184      *  Get Collection
 185      *
 186      *  Get a collection connection.
 187      *
 188      *  @return MongoCollection
 189      */
 190     final protected function _getCollection()
 191     {
 192         $colName = $this->getCollectionName();
 193         return self::_getConnection()->selectCollection($colName);
 194     }
 195     // }}}
 196
 197     // bool getCurrentSubDocument(array &$document, string $parent_key, array $values, array $past_values) {{{
 198     /**
 199      *  Generate Sub-document
 200      *
 201      *  This method build the difference between the current sub-document,
 202      *  and the origin one. If there is no difference, it would do nothing,
 203      *  otherwise it would build a document containing the differences.
 204      *
 205      *  @param array  &$document    Document target
 206      *  @param string $parent_key   Parent key name
 207      *  @param array  $values       Current values
 208      *  @param array  $past_values  Original values
 209      *
 210      *  @return false
 211      */
 212     function getCurrentSubDocument(&$document, $parent_key, Array $values, Array $past_values)
 213     {
 214         /**
 215          *  The current property is a embedded-document,
 216          *  now we're looking for differences with the
 217          *  previous value (because we're on an update).
 218          *
 219          *  It behaves exactly as getCurrentDocument,
 220          *  but this is simples (it doesn't support
 221          *  yet filters)
 222          */
 223         foreach ($values as $key => $value) {
 224             $super_key = "{$parent_key}.{$key}";
 225             if (is_array($value)) {
 226                 /**
 227                  *  Inner document detected
 228                  */
 229                 if (!isset($past_values[$key]) || !is_array($past_values[$key])) {
 230                     /**
 231                      *  We're lucky, it is a new sub-document,
 232                      *  we simple add it
 233                      */
 234                     $document['$set'][$super_key] = $value;
 235                 } else {
 236                     /**
 237                      *  This is a document like this, we need
 238                      *  to find out the differences to avoid
 239                      *  network overhead.
 240                      */
 241                     if (!$this->getCurrentSubDocument($document, $super_key, $value, $past_values[$key])) {
 242                         return false;
 243                     }
 244                 }
 245                 continue;
 246             }
 247             if (!isset($past_values[$key]) || $past_values[$key] != $value) {
 248                 $document['$set'][$super_key] = $value;
 249             }
 250         }
 251
 252         foreach (array_diff(array_keys($past_values), array_keys($values)) as $key) {
 253             $super_key = "{$parent_key}.{$key}";
 254             $document['$unset'][$super_key] = 1;
 255         }
 256
 257         return true;
 258     }
 259     // }}}
 260
 261     // array getCurrentDocument(bool $update) {{{
 262     /**
 263      *    Get Current Document
 264      *
 265      *    Based on this object properties a new document (Array)
 266      *    is returned. If we're modifying an document, just the modified
 267      *    properties are included in this document, which uses $set,
 268      *    $unset, $pushAll and $pullAll.
 269      *
 270      *
 271      *    @param bool $update
 272      *
 273      *    @return array
 274      */
 275     final protected function getCurrentDocument($update=false, $current=false)
 276     {
 277         $document = array();
 278         $object   = get_object_vars_ex($this);
 279
 280         if (!$current) {
 281             $current = (array)$this->_current;
 282         }
 283
 284         foreach ($object as $key => $value) {
 285             if (!$value) {
 286                 continue;
 287             }
 288             if ($update) {
 289                 if (is_array($value) && isset($current[$key])) {
 290                     /**
 291                      *  If the Field to update is an array, it has a different
 292                      *  behaviour other than $set and $unset. Fist, we need
 293                      *  need to check if it is an array or document, because
 294                      *  they can't be mixed.
 295                      *
 296                      */
 297                     if (!is_array($current[$key])) {
 298                         /**
 299                          *  We're lucky, the field wasn't
 300                          *  an array previously.
 301                          */
 302                         $this->_call_filter($key, $value, $current[$key]);
 303                         $document['$set'][$key] = $value;
 304                         continue;
 305                     }
 306
 307                     if (!$this->getCurrentSubDocument($document, $key, $value, $current[$key])) {
 308                         throw new Exception("{$key}: Array and documents are not compatible");
 309                     }
 310                 } else if(!isset($current[$key]) || $value !== $current[$key]) {
 311                     /**
 312                      *  It is 'linear' field that has changed, or
 313                      *  has been modified.
 314                      */
 315                     $past_value = isset($current[$key]) ? $current[$key] : null;
 316                     $this->_call_filter($key, $value, $past_value);
 317                     $document['$set'][$key] = $value;
 318                 }
 319             } else {
 320                 /**
 321                  *  It is a document insertation, so we
 322                  *  create the document.
 323                  */
 324                 $this->_call_filter($key, $value, null);
 325                 $document[$key] = $value;
 326             }
 327         }
 328
 329         /* Updated behaves in a diff. way */
 330         if ($update) {
 331             foreach (array_diff(array_keys($this->_current), array_keys($object)) as $property) {
 332                 if ($property == '_id') {
 333                     continue;
 334                 }
 335                 $document['$unset'][$property] = 1;
 336             }
 337         }
 338
 339         if (count($document) == 0) {
 340             return array();
 341         }
 342         return $document;
 343     }
 344     // }}}
 345
 346     // void _call_filter(string $key, mixed &$value, mixed $past_value) {{{
 347     /**
 348      *  *Internal Method*
 349      *
 350      *  This method check if the current document property has
 351      *  a filter method, if so, call it.
 352      *
 353      *  If the filter returns false, throw an Exception.
 354      *
 355      *  @return void
 356      */
 357     private function _call_filter($key, &$value, $past_value)
 358     {
 359         $filter = array($this, "{$key}_filter");
 360         if (is_callable($filter)) {
 361             $filter = call_user_func_array($filter, array(&$value, $past_value));
 362             if ($filter===false) {
 363                 throw new FilterException("{$key} filter failed");
 364             }
 365             $this->$key = $value;
 366         }
 367     }
 368     // }}}
 369
 370     // void setCursor(MongoCursor $obj) {{{
 371     /**
 372      *  Set Cursor
 373      *
 374      *  This method receive a MongoCursor and make
 375      *  it iterable.
 376      *
 377      *  @param MongoCursor $obj
 378      *
 379      *  @return void
 380      */
 381     final protected function setCursor(MongoCursor $obj)
 382     {
 383         $this->_cursor = $obj;
 384         $this->setResult($obj->getNext());
 385     }
 386     // }}}
 387
 388     // void reset() {{{
 389     /**
 390      *  Reset our Object, delete the current cursor if any, and reset
 391      *  unsets the values.
 392      *
 393      *  @return void
 394      */
 395     final function reset()
 396     {
 397         $this->_count = 0;
 398         $this->_cursor = null;
 399         $this->setResult(array());
 400     }
 401     // }}}
 402
 403     // void setResult(Array $obj) {{{
 404     /**
 405      *  Set Result
 406      *
 407      *  This method takes an document and copy it
 408      *  as properties in this object.
 409      *
 410      *  @param Array $obj
 411      *
 412      *  @return void
 413      */
 414     final protected function setResult($obj)
 415     {
 416         /* Unsetting previous results, if any */
 417         foreach (array_keys((array)$this->_current) as $key) {
 418             unset($this->$key);
 419         }
 420
 421         /* Add our current resultset as our object's property */
 422         foreach ((array)$obj as $key => $value) {
 423             $this->$key = $value;
 424         }
 425
 426         /* Save our record */
 427         $this->_current = $obj;
 428     }
 429     // }}}
 430
 431     // this find([$_id]) {{{
 432     /**
 433      *    Simple find
 434      *
 435      *    Really simple find, which uses this object properties
 436      *    for fast filtering
 437      *
 438      *    @return object this
 439      */
 440     function find(MongoID $_id = null)
 441     {
 442         $vars = $this->getCurrentDocument();
 443         if ($_id != null) {
 444             $vars['_id'] = $_id;
 445         }
 446         $res  = $this->_getCollection()->find($vars);
 447         $this->setCursor($res);
 448         return $this;
 449     }
 450     // }}}
 451
 452     // void save(bool $async) {{{
 453     /**
 454      *    Save
 455      *
 456      *    This method save the current document in MongoDB. If
 457      *    we're modifying a document, a update is performed, otherwise
 458      *    the document is inserted.
 459      *
 460      *    On updates, special operations such as $set, $pushAll, $pullAll
 461      *    and $unset in order to perform efficient updates
 462      *
 463      *    @param bool $async
 464      *
 465      *    @return void
 466      */
 467     final function save($async=true)
 468     {
 469         $update = isset($this->_id) && $this->_id InstanceOf MongoID;
 470         $conn   = $this->_getCollection();
 471         $obj    = $this->getCurrentDocument($update);
 472         if (count($obj) == 0) {
 473             return; /*nothing to do */
 474         }
 475         /* PRE-save hook */
 476         $this->pre_save($update ? 'update' : 'create', $obj);
 477         if ($update) {
 478             $conn->update(array('_id' => $this->_id), $obj);
 479             foreach ($obj as $key => $value) {
 480                 $this->_current[$key] = $value;
 481             }
 482             $this->on_update();
 483         } else {
 484             $conn->insert($obj, $async);
 485             $this->_id      = $obj['_id'];
 486             $this->_current = $obj;
 487             $this->on_save();
 488         }
 489     }
 490     // }}}
 491
 492     // bool delete() {{{
 493     /**
 494      *  Delete the current document
 495      *
 496      *  @return bool
 497      */
 498     final function delete()
 499     {
 500         if ($this->valid()) {
 501             return $this->_getCollection()->remove(array('_id' => $this->_id));
 502         }
 503         return false;
 504     }
 505     // }}}
 506
 507     // void drop() {{{
 508     /**
 509      *  Delete the current colleciton and all its documents
 510      *
 511      *  @return void
 512      */
 513     final function drop()
 514     {
 515         $this->_getCollection()->drop();
 516         $this->setResult(array());
 517         $this->_cursor = null;
 518     }
 519     // }}}
 520
 521     // int count() {{{
 522     /**
 523      *  Return the number of documents in the actual request. If
 524      *  we're not in a request, it will return 0.
 525      *
 526      *  @return int
 527      */
 528     final function count()
 529     {
 530         if ($this->valid()) {
 531             return $this->_cursor->count();
 532         }
 533         return 0;
 534     }
 535     // }}}
 536
 537     // bool valid() {{{
 538     /**
 539      *    Valid
 540      *
 541      *    Return if we're on an iteration and if it is still valid
 542      *
 543      *    @return true
 544      */
 545     final function valid()
 546     {
 547         return $this->_cursor InstanceOf MongoCursor && $this->_cursor->valid();
 548     }
 549     // }}}
 550
 551     // bool next() {{{
 552     /**
 553      *    Move to the next document
 554      *
 555      *    @return bool
 556      */
 557     final function next()
 558     {
 559         return $this->_cursor->next();
 560     }
 561     // }}}
 562
 563     // this current() {{{
 564     /**
 565      *    Return the current object, and load the current document
 566      *    as this object property
 567      *
 568      *    @return object
 569      */
 570     final function current()
 571     {
 572         $this->setResult($this->_cursor->current());
 573         return $this;
 574     }
 575     // }}}
 576
 577     // bool rewind() {{{
 578     /**
 579      *    Go to the first document
 580      */
 581     final function rewind()
 582     {
 583         return $this->_cursor->rewind();
 584     }
 585     // }}}
 586
 587     // getID() {{{
 588     /**
 589      *  Return the current document ID. If there is
 590      *  no document it would return false.
 591      *
 592      *  @return object|false
 593      */
 594     final public function getID()
 595     {
 596         if ($this->_id instanceof MongoID) {
 597             return $this->_id;
 598         }
 599         return false;
 600     }
 601     // }}}
 602
 603     // string key() {{{
 604     /**
 605      *    Return the current key
 606      *
 607      *    @return string
 608      */
 609     final function key()
 610     {
 611         return $this->getID();
 612     }
 613     // }}}
 614
 615     // void pre_save($action, & $document) {{{
 616     /**
 617      *    PRE-save Hook,
 618      *
 619      *    This method is fired just before an insert or updated. The document
 620      *    is passed by reference, so it can be modified. Also if for instance
 621      *    one property is missing an Exception could be thrown to avoid
 622      *    the insert.
 623      *
 624      *
 625      *    @param string $action     Update or Create
 626      *    @param array  &$document Document that will be sent to MongoDB.
 627      *
 628      *    @return void
 629      */
 630     protected function pre_save($action, Array &$document)
 631     {
 632     }
 633     // }}}
 634
 635     // void on_save() {{{
 636     /**
 637      *    On Save hook
 638      *
 639      *    This method is fired right after an insert is performed.
 640      *
 641      *    @return void
 642      */
 643     protected function on_save()
 644     {
 645     }
 646     // }}}
 647
 648     // void on_update() {{{
 649     /**
 650      *    On Update hook
 651      *
 652      *    This method is fired right after an update is performed.
 653      *
 654      *    @return void
 655      */
 656     protected function on_update()
 657     {
 658     }
 659     // }}}
 660
 661     // void on_iterate() {{{
 662     /**
 663      *    On Iterate Hook
 664      *
 665      *    This method is fired right after a new document is loaded
 666      *    from the recorset, it could be useful to load references to other
 667      *    documents.
 668      *
 669      *    @return void
 670      */
 671     protected function on_iterate()
 672     {
 673     }
 674     // }}}
 675
 676     // setup() {{{
 677     /**
 678      *  This method should contain all the indexes, and shard keys
 679      *  needed by the current collection. This try to make
 680      *  installation on development environments easier.
 681      */
 682     function setup()
 683     {
 684     }
 685     // }}}
 686
 687 }
 688
 689 /*
 690  * Local variables:
 691  * tab-width: 4
 692  * c-basic-offset: 4
 693  * End:
 694  * vim600: sw=4 ts=4 fdm=marker
 695  * vim<600: sw=4 ts=4
 696  */