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 /**
  48  *  ActiveMongo
  49  *
  50  *  Simple ActiveRecord pattern built on top of MongoDB
  51  *
  52  *    @author César D. Rodas <crodas@php.net>
  53  *
  54  */
  55 abstract class ActiveMongo implements Iterator
  56 {
  57
  58     // properties {{{
  59     /**
  60      *    Current collections
  61      *
  62      *    @type array
  63      */
  64     private static $_collections;
  65     /**
  66      *    Current connection to MongoDB
  67      *
  68      *    @type MongoConnection
  69      */
  70     private static $_conn;
  71     /**
  72      *    Database name
  73      *
  74      *    @type string
  75      */
  76     private static $_db;
  77     /**
  78      *    Host name
  79      *
  80      *    @type string
  81      */
  82     private static $_host;
  83     /**
  84      *    Current document
  85      *
  86      *    @type array
  87      */
  88     private $_current = array();
  89     /**
  90      *    Result cursor
  91      *
  92      *    @type MongoCursor
  93      */
  94     private $_cursor  = null;
  95     /**
  96      *    Number of total documents in this recordset
  97      *
  98      *    @type int
  99      */
 100     private $_count   = 0;
 101     /**
 102      *    Current document ID
 103      *
 104      *    @type MongoID
 105      */
 106     private $_id;
 107     // }}}
 108
 109     // string _getCollectionName() {{{
 110     /**
 111      *  Get Collection Name, by default the class name,
 112      *  but you it can be override at the class itself to give
 113      *  a custom name.
 114      *
 115      *  @return string Colleciton Name
 116      */
 117     protected function _getCollectionName()
 118     {
 119         return strtolower(get_class($this));
 120     }
 121     // }}}
 122
 123     // void connection($db, $host) {{{
 124     /**
 125      *  Connect
 126      *
 127      *  This method setup parameters to connect to a MongoDB
 128      *  database. The connection is done when it is needed.
 129      *
 130      *  @param string $db   Database name
 131      *  @param string $host Host to connect
 132      *
 133      *  @return void
 134      */
 135     final public static function connect($db, $host='localhost')
 136     {
 137         self::$_host = $host;
 138         self::$_db   = $db;
 139     }
 140     // }}}
 141
 142     // MongoConnection _getConnection() {{{
 143     /**
 144      *  Get Connection
 145      *
 146      *  Get a valid database connection
 147      *
 148      *  @return MongoConnection
 149      */
 150     final protected static function _getConnection()
 151     {
 152         if (is_null(self::$_conn)) {
 153             self::$_conn = new Mongo(self::$_host);
 154         }
 155         return self::$_conn->selectDB(self::$_db);
 156     }
 157     // }}}
 158
 159     // MongoCollection _getCollection() {{{
 160     /**
 161      *  Get Collection
 162      *
 163      *  Get a collection connection.
 164      *
 165      *  @return MongoCollection
 166      */
 167     final protected function _getCollection()
 168     {
 169         $colName = $this->_getCollectionName();
 170         if (!isset(self::$_collections[$colName])) {
 171             self::$_collections[$colName] = self::_getConnection()->selectCollection($colName);
 172         }
 173         return self::$_collections[$colName];
 174     }
 175     // }}}
 176
 177
 178     // int count() {{{
 179     /**
 180      *  Return the number of documents in the actual request. If
 181      *  we're not in a request, it will return -1.
 182      *
 183      *  @return int
 184      */
 185     function count()
 186     {
 187         if ($this->valid()) {
 188             return $this->_count;
 189         }
 190         return -1;
 191     }
 192     // }}}
 193
 194     // array getCurrentDocument(bool $update) {{{
 195     /**
 196      *    Get Current Document
 197      *
 198      *    Based on this object properties a new document (Array)
 199      *    is returned. If we're modifying an document, just the modified
 200      *    properties are included in this document, which uses $set,
 201      *    $unset, $pushAll and $pullAll.
 202      *
 203      *
 204      *    @param bool $update
 205      *
 206      *    @return array
 207      */
 208     final protected function getCurrentDocument($update=false)
 209     {
 210         $vars    = array();
 211         $current = (array)$this->_current;
 212         $push    = array();
 213         $pull    = array();
 214         $unset   = array();
 215         $object  = get_object_vars_ex($this);
 216
 217         foreach ($object as $key => $value) {
 218             if (!$value) {
 219                 if ($update) {
 220                     $unset[$key] = 1;
 221                 }
 222                 continue;
 223             }
 224
 225             if ($update) {
 226                 if (is_array($value) && isset($current[$key])) {
 227                     $toPush = array_diff($value, $current[$key]);
 228                     $toPull = array_diff($current[$key], $value);
 229                     if (count($toPush) > 0) {
 230                         $push[$key] = array_values($toPush);
 231                     }
 232                     if (count($toPull) > 0) {
 233                         $pull[$key] = array_values($toPull);
 234                     }
 235                 } else if(!isset($current[$key]) || $value !== $current[$key]) {
 236                     $filter = array($this, "{$key}_filter");
 237                     if (is_callable($filter)) {
 238                         $filter = call_user_func_array($filter, array(&$value, isset($current[$key]) ? $current[$key] : null));
 239                         if (!$filter) {
 240                             throw new FilterException("{$key} filter failed");
 241                         }
 242                     }
 243                     $vars[$key] = $value;
 244                 }
 245             } else {
 246                 $filter = array($this, "{$key}_filter");
 247                 if (is_callable($filter)) {
 248                     $filter = call_user_func_array($filter, array(&$value, null));
 249                     if (!$filter) {
 250                         throw new FilterException("{$key} filter failed");
 251                     }
 252                 }
 253                 $vars[$key] = $value;
 254             }
 255         }
 256
 257         /* Updated behaves in a diff. way */
 258         if ($update) {
 259             foreach (array_diff(array_keys($this->_current), array_keys($object)) as $property) {
 260                 $unset[$property] = 1;
 261             }
 262             if (count($vars) > 0) {
 263                 $vars = array('$set' => $vars);
 264             }
 265             if (count($push) > 0) {
 266                 $vars['$pushAll'] = $push;
 267             }
 268             if (count($pull) > 0) {
 269                 $vars['$pullAll'] = $pull;
 270             }
 271             if (count($unset) > 0) {
 272                 $vars['$unset'] = $unset;
 273             }
 274         }
 275
 276         if (count($vars) == 0) {
 277             return array();
 278         }
 279         return $vars;
 280     }
 281     // }}}
 282
 283     // void setCursor(MongoCollection $obj) {{{
 284     /**
 285      *  Set Cursor
 286      *
 287      *  This method receive a MongoCursor and make
 288      *  it iterable.
 289      *
 290      *  @param MongoCursor $obj
 291      *
 292      *  @return void
 293      */
 294     final protected function setCursor($obj)
 295     {
 296         $this->_cursor = $obj;
 297         $this->_count  = $obj->count();
 298         if ($this->_count) {
 299             $this->setResult($obj->getNext());
 300         } else {
 301             $this->setResult(array());
 302         }
 303     }
 304     // }}}
 305
 306     // void setResult(Array $obj) {{{
 307     /**
 308      *  Set Result
 309      *
 310      *  This method takes an document and copy it
 311      *  as properties in this object.
 312      *
 313      *  @param Array $obj
 314      *
 315      *  @return void
 316      */
 317     final protected function setResult($obj)
 318     {
 319         /* Unsetting previous results, if any */
 320         foreach (array_keys($this->_current) as $key) {
 321             unset($this->$key);
 322         }
 323
 324         /* Add our current resultset as our object's property */
 325         foreach ($obj as $key => $value) {
 326             $this->$key = $value;
 327         }
 328
 329         /* Save our record */
 330         $this->_current = $obj;
 331     }
 332     // }}}
 333
 334     // this find() {{{
 335     /**
 336      *    Simple find
 337      *
 338      *    Really simple find, which uses this object properties
 339      *    for fast filtering
 340      *
 341      *    @return object this
 342      */
 343     final function find()
 344     {
 345         $vars = $this->getCurrentDocument();
 346         $res  = $this->_getCollection()->find($vars);
 347         $this->setCursor($res);
 348         return $this;
 349     }
 350     // }}}
 351
 352     // void save(bool $async) {{{
 353     /**
 354      *    Save
 355      *
 356      *    This method save the current document in MongoDB. If
 357      *    we're modifying a document, a update is performed, otherwise
 358      *    the document is inserted.
 359      *
 360      *    On updates, special operations such as $set, $pushAll, $pullAll
 361      *    and $unset in order to perform efficient updates
 362      *
 363      *    @param bool $async
 364      *
 365      *    @return void
 366      */
 367     final function save($async=true)
 368     {
 369         $update = isset($this->_id) && $this->_id InstanceOf MongoID;
 370         $conn   = $this->_getCollection();
 371         $obj    = $this->getCurrentDocument($update);
 372         if (count($obj) == 0) {
 373             return; /*nothing to do */
 374         }
 375         /* PRE-save hook */
 376         $this->pre_save($update ? 'update' : 'create', $obj);
 377         if ($update) {
 378             $conn->update(array('_id' => $this->_id), $obj);
 379             $conn->save($obj);
 380             foreach ($obj as $key => $value) {
 381                 $this->_current[$key] = $value;
 382             }
 383         } else {
 384             $conn->insert($obj, $async);
 385             $this->_id      = $obj['_id'];
 386             $this->_current = $obj;
 387         }
 388         /* post-save hook */
 389         $this->on_save();
 390     }
 391     // }}}
 392
 393     // bool delete() {{{
 394     /**
 395      *  Delete the current document
 396      *
 397      *  @return bool
 398      */
 399     final function delete()
 400     {
 401         if ($this->valid()) {
 402             return $this->_getCollection()->remove(array('_id' => $this->_id));
 403         }
 404         return false;
 405     }
 406     // }}}
 407
 408     // void drop() {{{
 409     /**
 410      *  Delete the current colleciton and all its documents
 411      *
 412      *  @return void
 413      */
 414     final function drop()
 415     {
 416         $this->_getCollection()->drop();
 417         $this->setResult(array());
 418         $this->_cursor = null;
 419     }
 420     // }}}
 421
 422     // bool valid() {{{
 423     /**
 424      *    Valid
 425      *
 426      *    Return if we're on an iteration and if it is still valid
 427      *
 428      *    @return true
 429      */
 430     final function valid()
 431     {
 432         return $this->_cursor InstanceOf MongoCursor && $this->_cursor->valid();
 433     }
 434     // }}}
 435
 436     // bool next() {{{
 437     /**
 438      *    Move to the next document
 439      *
 440      *    @return bool
 441      */
 442     final function next()
 443     {
 444         return $this->_cursor->next();
 445     }
 446     // }}}
 447
 448     // this current() {{{
 449     /**
 450      *    Return the current object, and load the current document
 451      *    as this object property
 452      *
 453      *    @return object
 454      */
 455     final function current()
 456     {
 457         $this->setResult($this->_cursor->current());
 458         return $this;
 459     }
 460     // }}}
 461
 462     // bool rewind() {{{
 463     /**
 464      *    Go to the first document
 465      */
 466     final function rewind()
 467     {
 468         return $this->_cursor->rewind();
 469     }
 470     // }}}
 471
 472     // string key() {{{
 473     /**
 474      *    Return the current key
 475      *
 476      *    @return string
 477      */
 478     final function key()
 479     {
 480         return $this->_cursor->key();
 481     }
 482     // }}}
 483
 484     // void pre_save($action, & $document) {{{
 485     /**
 486      *    PRE-save Hook,
 487      *
 488      *    This method is fired just before an insert or updated. The document
 489      *    is passed by reference, so it can be modified. Also if for instance
 490      *    one property is missing an Exception could be thrown to avoid
 491      *    the insert.
 492      *
 493      *
 494      *    @param string $action     Update or Create
 495      *    @param array  &$document Document that will be sent to MongoDB.
 496      *
 497      *    @return void
 498      */
 499     protected function pre_save($action, Array &$document)
 500     {
 501     }
 502     // }}}
 503
 504     // void on_save() {{{
 505     /**
 506      *    On Save hook
 507      *
 508      *    This method is fired right after an insert is performed.
 509      *
 510      *    @return void
 511      */
 512     protected function on_save()
 513     {
 514     }
 515     // }}}
 516
 517     // void on_iterate() {{{
 518     /**
 519      *    On Iterate Hook
 520      *
 521      *    This method is fired right after a new document is loaded
 522      *    from the recorset, it could be useful to load references to other
 523      *    documents.
 524      *
 525      *    @return void
 526      */
 527     protected function on_iterate()
 528     {
 529     }
 530     // }}}
 531
 532 }
 533
 534 /*
 535  * Local variables:
 536  * tab-width: 4
 537  * c-basic-offset: 4
 538  * End:
 539  * vim600: sw=4 ts=4 fdm=marker
 540  * vim<600: sw=4 ts=4
 541  */