Skip to content

Commit 1043a3a

Browse files
alcaeusalcaeus
authored
PHPLIB-989: Move persistable class documentation to tutorial (#987)
* PHPLIB-989: Move persistable class documentation to tutorial * Move legacy driver section from BSON reference to upgrade guide * Move type map documentation to persistable classes tutorial * Rename persistence tutorial and move sections around
1 parent f7ba251 commit 1043a3a

File tree

5 files changed

+232
-214
lines changed

5 files changed

+232
-214
lines changed

‎docs/index.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,8 @@ following pages should help you get started:
3535

3636
- :doc:`/tutorial/gridfs`
3737

38+
- :doc:`/tutorial/modeling-bson-data`
39+
3840
- :doc:`/reference/bson`
3941

4042
Code examples can be found in the ``examples`` directory in the source code.

‎docs/reference/bson.txt‎

Lines changed: 2 additions & 212 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@ By default, the |php-library| returns BSON documents as
2121
:phpclass:`MongoDB\\Model\\BSONDocument` objects and BSON arrays as
2222
:phpclass:`MongoDB\\Model\\BSONArray` objects, respectively.
2323

24-
BSON Classes
25-
------------
24+
Classes
25+
-------
2626

2727
.. phpclass:: MongoDB\\Model\\BSONArray
2828

@@ -49,213 +49,3 @@ BSON Classes
4949
class. During BSON and JSON serialization, instances of this class will
5050
serialize as a document type (:php:`object casting
5151
<types.type-juggling#language.types.typecasting>` is used internally).
52-
53-
.. _php-type-map:
54-
55-
Type Maps
56-
---------
57-
58-
Most methods that read data from MongoDB support a ``typeMap`` option, which
59-
allows control over how BSON is converted to PHP. Additionally,
60-
the :phpclass:`MongoDB\\Client`, :phpclass:`MongoDB\\Database`, and
61-
:phpclass:`MongoDB\\Collection` classes accept a ``typeMap`` option, which can
62-
be used to specify a default type map to apply to any supporting methods and
63-
selected classes (e.g. :phpmethod:`MongoDB\\Client::selectDatabase()`).
64-
65-
The :phpclass:`MongoDB\\Client`, :phpclass:`MongoDB\\Database`, and
66-
:phpclass:`MongoDB\\Collection` classes use the following type map by
67-
default:
68-
69-
.. code-block:: php
70-
71-
[
72-
'array' => 'MongoDB\Model\BSONArray',
73-
'document' => 'MongoDB\Model\BSONDocument',
74-
'root' => 'MongoDB\Model\BSONDocument',
75-
]
76-
77-
The type map above will convert BSON documents and arrays to
78-
:phpclass:`MongoDB\\Model\\BSONDocument` and
79-
:phpclass:`MongoDB\\Model\\BSONArray` objects, respectively. The ``root`` and
80-
``document`` keys are used to distinguish the top-level BSON document from
81-
embedded documents, respectively.
82-
83-
A type map may specify any class that implements
84-
:php:`MongoDB\\BSON\\Unserializable <mongodb-bson-unserializable>` as well as
85-
``"array"``, ``"stdClass``", and ``"object"`` (``"stdClass``" and ``"object"``
86-
are aliases of one another).
87-
88-
.. seealso:: :php:`Deserialization from BSON <manual/en/mongodb.persistence.deserialization.php>` in the PHP manual
89-
90-
``Persistable`` Classes
91-
-----------------------
92-
93-
The driver's :php:`persistence specification <mongodb.persistence>` outlines how
94-
classes implementing its :php:`MongoDB\\BSON\\Persistable
95-
<mongodb-bson-persistable>` interface are serialized to and deserialized from
96-
BSON. The :php:`Persistable <mongodb-bson-persistable>` interface is analogous
97-
to PHP's :php:`Serializable interface <class.serializable>`.
98-
99-
The driver automatically handles serialization and deserialization for classes
100-
implementing the :php:`Persistable <mongodb-bson-persistable>` interface without
101-
requiring the use of the ``typeMap`` option. This is done by encoding the name
102-
of the PHP class in a special property within the BSON document.
103-
104-
.. note::
105-
106-
When deserializing a PHP variable from BSON, the encoded class name of a
107-
:php:`Persistable <mongodb-bson-persistable>` object will override any class
108-
specified in the type map, but it will not override ``"array"`` and
109-
``"stdClass"`` or ``"object"``. This is discussed in the
110-
:php:`persistence specification <mongodb.persistence>` but it bears
111-
repeating.
112-
113-
Consider the following class definition:
114-
115-
.. code-block:: php
116-
117-
<?php
118-
119-
class Person implements MongoDB\BSON\Persistable
120-
{
121-
private $id;
122-
private $name;
123-
private $createdAt;
124-
125-
public function __construct($name)
126-
{
127-
$this->id = new MongoDB\BSON\ObjectId;
128-
$this->name = (string) $name;
129-
$this->createdAt = new MongoDB\BSON\UTCDateTime;
130-
}
131-
132-
function bsonSerialize()
133-
{
134-
return [
135-
'_id' => $this->id,
136-
'name' => $this->name,
137-
'createdAt' => $this->createdAt,
138-
];
139-
}
140-
141-
function bsonUnserialize(array $data)
142-
{
143-
$this->id = $data['_id'];
144-
$this->name = $data['name'];
145-
$this->createdAt = $data['createdAt'];
146-
}
147-
}
148-
149-
The following example constructs a ``Person`` object, inserts it into the
150-
database, and reads it back as an object of the same type:
151-
152-
.. code-block:: php
153-
154-
<?php
155-
156-
$collection = (new MongoDB\Client)->test->persons;
157-
158-
$result = $collection->insertOne(new Person('Bob'));
159-
160-
$person = $collection->findOne(['_id' => $result->getInsertedId()]);
161-
162-
var_dump($person);
163-
164-
The output would then resemble:
165-
166-
.. code-block:: none
167-
168-
object(Person)#18 (3) {
169-
["id":"Person":private]=>
170-
object(MongoDB\BSON\ObjectId)#15 (1) {
171-
["oid"]=>
172-
string(24) "56fad2c36118fd2e9820cfc1"
173-
}
174-
["name":"Person":private]=>
175-
string(3) "Bob"
176-
["createdAt":"Person":private]=>
177-
object(MongoDB\BSON\UTCDateTime)#17 (1) {
178-
["milliseconds"]=>
179-
int(1459278531218)
180-
}
181-
}
182-
183-
The same document in the MongoDB shell might display as:
184-
185-
.. code-block:: js
186-
187-
{
188-
"_id" : ObjectId("56fad2c36118fd2e9820cfc1"),
189-
"__pclass" : BinData(128,"UGVyc29u"),
190-
"name" : "Bob",
191-
"createdAt" : ISODate("2016-03-29T19:08:51.218Z")
192-
}
193-
194-
.. note::
195-
196-
:php:`MongoDB\\BSON\\Persistable <mongodb-bson-persistable>` may only be used
197-
for root and embedded BSON documents. It may not be used for BSON arrays.
198-
199-
Emulating the Legacy Driver
200-
---------------------------
201-
202-
The legacy ``mongo`` extension returned both BSON documents and arrays as PHP
203-
arrays. While PHP arrays are convenient to work with, this behavior was
204-
problematic:
205-
206-
- Different BSON types could deserialize to the same PHP value (e.g.
207-
``{"0": "foo"}`` and ``["foo"]``), which made it impossible to infer the
208-
original BSON type.
209-
210-
- Numerically-indexed PHP arrays would be serialized as BSON documents if there
211-
was a gap in their key sequence. Such gaps were easily caused by unsetting a
212-
key to remove an element and forgetting to numerically reindex the array.
213-
214-
The |php-library|'s :phpclass:`BSONDocument <MongoDB\\Model\\BSONDocument>` and
215-
:phpclass:`BSONArray <MongoDB\\Model\\BSONArray>` classes address these concerns
216-
by preserving the BSON type information during serialization and
217-
deserialization; however, some users may still prefer the legacy behavior. If
218-
desired, you can use the ``typeMap`` option to have the library return
219-
everything as a PHP array:
220-
221-
.. code-block:: php
222-
223-
<?php
224-
225-
$client = new MongoDB\Client(
226-
'mongodb://127.0.0.1/',
227-
[],
228-
[
229-
'typeMap' => [
230-
'array' => 'array',
231-
'document' => 'array',
232-
'root' => 'array',
233-
],
234-
]
235-
);
236-
237-
$document = $client->test->zips->findOne(['_id' => '94301']);
238-
239-
var_dump($document);
240-
241-
The above example would output something similar to:
242-
243-
.. code-block:: php
244-
245-
array(5) {
246-
["_id"]=>
247-
string(5) "94301"
248-
["city"]=>
249-
string(9) "PALO ALTO"
250-
["loc"]=>
251-
array(2) {
252-
[0]=>
253-
float(-122.149685)
254-
[1]=>
255-
float(37.444324)
256-
}
257-
["pop"]=>
258-
int(15965)
259-
["state"]=>
260-
string(2) "CA"
261-
}

‎docs/tutorial.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,5 @@ Tutorials
1717
/tutorial/indexes
1818
/tutorial/tailable-cursor
1919
/tutorial/example-data
20+
/tutorial/modeling-bson-data
2021
/tutorial/stable-api

‎docs/tutorial/modeling-bson-data.txt‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
==================
2+
Modeling BSON Data
3+
==================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
14+
Type Maps
15+
---------
16+
17+
Most methods that read data from MongoDB support a ``typeMap`` option, which
18+
allows control over how BSON is converted to PHP. Additionally,
19+
the :phpclass:`MongoDB\\Client`, :phpclass:`MongoDB\\Database`, and
20+
:phpclass:`MongoDB\\Collection` classes accept a ``typeMap`` option, which can
21+
be used to specify a default type map to apply to any supporting methods and
22+
selected classes (e.g. :phpmethod:`MongoDB\\Client::selectDatabase()`).
23+
24+
The :phpclass:`MongoDB\\Client`, :phpclass:`MongoDB\\Database`, and
25+
:phpclass:`MongoDB\\Collection` classes use the following type map by
26+
default:
27+
28+
.. code-block:: php
29+
30+
[
31+
'array' => 'MongoDB\Model\BSONArray',
32+
'document' => 'MongoDB\Model\BSONDocument',
33+
'root' => 'MongoDB\Model\BSONDocument',
34+
]
35+
36+
The type map above will convert BSON documents and arrays to
37+
:phpclass:`MongoDB\\Model\\BSONDocument` and
38+
:phpclass:`MongoDB\\Model\\BSONArray` objects, respectively. The ``root`` and
39+
``document`` keys are used to distinguish the top-level BSON document from
40+
embedded documents, respectively.
41+
42+
A type map may specify any class that implements
43+
:php:`MongoDB\\BSON\\Unserializable <mongodb-bson-unserializable>` as well as
44+
``"array"``, ``"stdClass``", and ``"object"`` (``"stdClass``" and ``"object"``
45+
are aliases of one another).
46+
47+
.. seealso:: :php:`Deserialization from BSON <manual/en/mongodb.persistence.deserialization.php>` in the PHP manual
48+
49+
50+
Persistable Classes
51+
-------------------
52+
53+
The driver's :php:`persistence specification <mongodb.persistence>` outlines how
54+
classes implementing its :php:`MongoDB\\BSON\\Persistable
55+
<mongodb-bson-persistable>` interface are serialized to and deserialized from
56+
BSON. The :php:`Persistable <mongodb-bson-persistable>` interface is analogous
57+
to PHP's :php:`Serializable interface <class.serializable>`.
58+
59+
The driver automatically handles serialization and deserialization for classes
60+
implementing the :php:`Persistable <mongodb-bson-persistable>` interface without
61+
requiring the use of the ``typeMap`` option. This is done by encoding the name
62+
of the PHP class in a special property within the BSON document.
63+
64+
.. note::
65+
66+
When deserializing a PHP variable from BSON, the encoded class name of a
67+
:php:`Persistable <mongodb-bson-persistable>` object will override any class
68+
specified in the type map, but it will not override ``"array"`` and
69+
``"stdClass"`` or ``"object"``. This is discussed in the
70+
:php:`persistence specification <mongodb.persistence>` but it bears
71+
repeating.
72+
73+
Consider the following class definition:
74+
75+
.. code-block:: php
76+
77+
<?php
78+
79+
class Person implements MongoDB\BSON\Persistable
80+
{
81+
private MongoDB\BSON\ObjectId $id;
82+
private string $name;
83+
private MongoDB\BSON\UTCDateTime $createdAt;
84+
85+
public function __construct(string $name)
86+
{
87+
$this->id = new MongoDB\BSON\ObjectId;
88+
$this->name = $name;
89+
$this->createdAt = new MongoDB\BSON\UTCDateTime;
90+
}
91+
92+
function bsonSerialize()
93+
{
94+
return [
95+
'_id' => $this->id,
96+
'name' => $this->name,
97+
'createdAt' => $this->createdAt,
98+
];
99+
}
100+
101+
function bsonUnserialize(array $data)
102+
{
103+
$this->id = $data['_id'];
104+
$this->name = $data['name'];
105+
$this->createdAt = $data['createdAt'];
106+
}
107+
}
108+
109+
The following example constructs a ``Person`` object, inserts it into the
110+
database, and reads it back as an object of the same type:
111+
112+
.. code-block:: php
113+
114+
<?php
115+
116+
$collection = (new MongoDB\Client)->test->persons;
117+
118+
$result = $collection->insertOne(new Person('Bob'));
119+
120+
$person = $collection->findOne(['_id' => $result->getInsertedId()]);
121+
122+
var_dump($person);
123+
124+
The output would then resemble:
125+
126+
.. code-block:: none
127+
128+
object(Person)#18 (3) {
129+
["id":"Person":private]=>
130+
object(MongoDB\BSON\ObjectId)#15 (1) {
131+
["oid"]=>
132+
string(24) "56fad2c36118fd2e9820cfc1"
133+
}
134+
["name":"Person":private]=>
135+
string(3) "Bob"
136+
["createdAt":"Person":private]=>
137+
object(MongoDB\BSON\UTCDateTime)#17 (1) {
138+
["milliseconds"]=>
139+
int(1459278531218)
140+
}
141+
}
142+
143+
The same document in the MongoDB shell might display as:
144+
145+
.. code-block:: js
146+
147+
{
148+
"_id" : ObjectId("56fad2c36118fd2e9820cfc1"),
149+
"__pclass" : BinData(128,"UGVyc29u"),
150+
"name" : "Bob",
151+
"createdAt" : ISODate("2016-03-29T19:08:51.218Z")
152+
}
153+
154+
.. note::
155+
156+
:php:`MongoDB\\BSON\\Persistable <mongodb-bson-persistable>` may only be used
157+
for root and embedded BSON documents. It may not be used for BSON arrays.
158+
.. _php-type-map:

0 commit comments

Comments
 (0)