Documentation updates

[jmikola]

See http://jmikola.github.io/mongo-php-library/ for a preview.

[moderndeveloperllc]

Does this include documents with _pclass attributes? If so that might be worth mentioning. The sentence could be construed to mean only that the type option is not supported.

[jmikola]

__pclass would still apply here. Based on the persistence specification, it is only ignored if the type map specifies "array" or "object" (i.e. stdClass) or if the class found in the __pclass field is not suitable (e.g. not found, not implementing an interface). I'll clarify that in these documentation blurbs.
, found but missing an interface).

[jmikola]

@moderndeveloperllc: I added notes on when Persistable kicks in and also created a separate BSON tutorial page. Thanks for the feedback.

[moderndeveloperllc]

@jmikola Thanks! I see the tutorial/bson on the github.io, but not your repo for some reason. Perhaps I'm just not looking in the right spot. It may be useful to show how the data looks when viewed with the mongo shell. I added a created date to the class to show how to use a type like UTCDateTime.

<?php
class Person implements MongoDB\BSON\Persistable
{
    private $id;
    private $name;
    private $createdDate;

    public function __construct($name)
    {
        $this->id = new MongoDB\BSON\ObjectID();
        $this->name = (string) $name;
        $this->createdDate = new MongoDB\BSON\UTCDateTime(round(microtime(true)*1000));
    }

    public function bsonSerialize()
    {
        return ['_id' => $this->id, 'name' => $this->name, 'created' => $this->createdDate];
    }

    public function bsonUnserialize(array $data)
    {
        $this->id = $data['_id'];
        $this->name = $data['name'];
        $this->createdDate = $data['created'];
    }

    public function getDate()
    {
        return $this->createdDate->toDateTime();
    }
}

$collection = (new MongoDB\Client)->demo->persons;

$result = $collection->insertOne(new Person('Bob'));

printf("Inserted %d person\n", $result->getInsertedCount());

$person = $collection->findOne(['_id' => $result->getInsertedId()]);

var_dump($person);

with the data showing in the mongo shell as:

> db.persons.findOne()
{
    "_id" : ObjectId("56f9a635f8ddd706292de031"),
    "__pclass" : BinData(128,"UGVyc29u"),
    "name" : "Bob",
    "created" : ISODate("2016-03-28T21:46:29.738Z")
}

and the var_dump as:

object(Person)[18]
  private 'id' => 
    object(MongoDB\BSON\ObjectID)[15]
      public 'oid' => string '56f9a635f8ddd706292de031' (length=24)
  private 'name' => string 'Bob' (length=3)
  private 'createdDate' => 
    object(MongoDB\BSON\UTCDateTime)[17]
      public 'milliseconds' => int 1459201589738

[jmikola]

I see the tutorial/bson on the github.io, but not your repo for some reason.

@moderndeveloperllc: I actually forgot to add the bson.md file when committing. Thanks for catching that!

It may be useful to show how the data looks when viewed with the mongo shell. I added a created date to the class to show how to use a type like UTCDateTime.

Added both of these examples. Thanks! I also left a note in PHPC-536 to come back and revise this example once UTCDateTime's constructor is enhanced to default to the current time.

[jmikola]

Manually merged to v1.0 in 749f0aa, which has since been merged up to master and deployed.

[moderndeveloperllc]

Nice. And thanks for cleaning up my example for readability. I had been wondering about the very thing PHPC-536 addresses.