mongodb/transistor

Simple MongoDB Object<->Document Mapper

0.1.0 2015-04-22 22:03 UTC

Requires

• ext-mongodb: >=0.5

BSD 2-Clause

• Hannes Magnusson

• database
• orm
• persistence
• mongodb
• odm
• driver

README

The new PHP Driver for MongoDB provides a MongoDB\BSON\Persistable interface which declares two methods to be called when storing the object, and the other when re-constructing it.

This transistor trait adds example implementation of the two methods and introduces lightweight change tracking. This allows the object to be seamlessly updated as well.

Example classes

<?php
class Person implements MongoDB\BSON\Persistable {
    use MongoDB\Transistor;
    protected $_id;
    protected $username;
    protected $email;
    protected $name;
    protected $addresses = array();
    protected $_lastModified;
    protected $_created;
}

class Address implements MongoDB\BSON\Persistable {
    use MongoDB\Transistor;
    protected $_id;
    protected $streetAddress;
    protected $city;
    protected $postalCode;
}
?>

See Person.php and Address.php for the full implementation of these example classes -- although this is really it. No annotations or anything. implements MongoDB\BSON\Persistable and use MongoDB\Transistor is the magic.

Simple usage

<?php
/* Construct a new person */
$person = new Person("bjori", "[e-mail]", "Hannes Magnusson");

/* Insert it */
insert($person);

/* Find a person based on its username */
$person = findOne(array("username" => "bjori"));

/* Get an instance of the Person object again */
var_dump($person);
?>

The above example will output something similar to

object(Person)#8 (7) {
  ["_id"]=>
  object(MongoDB\BSON\ObjectID)#4 (1) {
    ["oid"]=>
    string(24) "553586e2bd21b971774b7da1"
  }
  ["username"]=>
  string(5) "bjori"
  ["email"]=>
  string(13) "[e-mail]"
  ["name"]=>
  string(16) "Hannes Magnusson"
  ["addresses"]=>
  array(0) {
  }
  ["_lastModified"]=>
  NULL
  ["_created"]=>
  object(MongoDB\BSON\UTCDatetime)#7 (0) {
  }
}

Updating the object

<?php
/* Continuing from previous example, $person is instanceof Person */
$person->setName("Dr. " . $person->getName());

/* Update the document */
update(array("username" => "bjori"), $person);

/* Retrieve it again */
$person = findOne(array("username" => "bjori"));

/* Get an instance of the Person object again */
var_dump($person);
?>

The above example will output something similar to

object(Person)#9 (7) {
  ["_id"]=>
  object(MongoDB\BSON\ObjectID)#4 (1) {
    ["oid"]=>
    string(24) "553586e2bd21b971774b7da1"
  }
  ["username"]=>
  string(5) "bjori"
  ["email"]=>
  string(13) "[e-mail]"
  ["name"]=>
  string(16) "Dr. Hannes Magnusson"
  ["addresses"]=>
  array(0) {
  }
  ["_lastModified"]=>
  NULL
  ["_created"]=>
  object(MongoDB\BSON\UTCDatetime)#7 (0) {
  }
}

Adding embedded objects

<?php
/* Continuing from previous example, $person is instanceof Person */

/* Construct a new Address object */
$address = new Address("Manabraut 4", "Kopavogur", 200);
$person->addAddress($address);

/* Update the object with a new Address embedded object */
update(array("username" => "bjori"), $person);

$person = findOne(array("username" => "bjori"));
var_dump($person);
?>

The above example will output something similar to

object(Person)#10 (7) {
  ["_id"]=>
  object(MongoDB\BSON\ObjectID)#4 (1) {
    ["oid"]=>
    string(24) "553586e2bd21b971774b7da1"
  }
  ["username"]=>
  string(5) "bjori"
  ["email"]=>
  string(13) "[e-mail]"
  ["name"]=>
  string(16) "Dr. Hannes Magnusson"
  ["addresses"]=>
  array(1) {
    [0]=>
    object(Address)#%d (%d) {
      ["_id"]=>
      object(MongoDB\BSON\ObjectID)#%d (%d) {
        ["oid"]=>
        string(24) "%s"
      }
      ["streetAddress"]=>
      string(11) "Manabraut 4"
      ["city"]=>
      string(9) "Kopavogur"
      ["postalCode"]=>
      int(200)
      ["_created"]=>
      object(MongoDB\BSON\UTCDatetime)#%d (0) {
      }
    }
  }
  ["_lastModified"]=>
  NULL
  ["_created"]=>
  object(MongoDB\BSON\UTCDatetime)#7 (0) {
  }
}

Helpers

The insert(), update() and findOne() helpers in the example above don't do anything other then wrap their respective methods on the MongoDB\Driver\Manager and setting the TypeMap, and are only there to reduce error checking needed in the examples.

Performance

Since the actual object (un-)serialization is done by the extension itself there is nothing for PHP to do -- the trait itself is under 200 lines of dead simple code.

I'm sure there are dragons, so use with care.