Skip to content

Commit cd46da2

Browse files
alcaeusalcaeus
committed
PHPLIB-989: Move persistable class documentation to tutorial
1 parent ecdacff commit cd46da2

File tree

4 files changed

+121
-109
lines changed

4 files changed

+121
-109
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/persistable-classes`
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: 0 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -87,115 +87,6 @@ are aliases of one another).
8787

8888
.. seealso:: :php:`Deserialization from BSON <manual/en/mongodb.persistence.deserialization.php>` in the PHP manual
8989

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-
19990
Emulating the Legacy Driver
20091
---------------------------
20192

‎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/persistable-classes
2021
/tutorial/stable-api

‎docs/tutorial/persistable-classes.txt

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
===================
2+
Persistable classes
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+
The driver's :php:`persistence specification <mongodb.persistence>` outlines how
15+
classes implementing its :php:`MongoDB\\BSON\\Persistable
16+
<mongodb-bson-persistable>` interface are serialized to and deserialized from
17+
BSON. The :php:`Persistable <mongodb-bson-persistable>` interface is analogous
18+
to PHP's :php:`Serializable interface <class.serializable>`.
19+
20+
The driver automatically handles serialization and deserialization for classes
21+
implementing the :php:`Persistable <mongodb-bson-persistable>` interface without
22+
requiring the use of the ``typeMap`` option. This is done by encoding the name
23+
of the PHP class in a special property within the BSON document.
24+
25+
.. note::
26+
27+
When deserializing a PHP variable from BSON, the encoded class name of a
28+
:php:`Persistable <mongodb-bson-persistable>` object will override any class
29+
specified in the type map, but it will not override ``"array"`` and
30+
``"stdClass"`` or ``"object"``. This is discussed in the
31+
:php:`persistence specification <mongodb.persistence>` but it bears
32+
repeating.
33+
34+
Consider the following class definition:
35+
36+
.. code-block:: php
37+
38+
<?php
39+
40+
class Person implements MongoDB\BSON\Persistable
41+
{
42+
private MongoDB\BSON\ObjectId $id;
43+
private string $name;
44+
private MongoDB\BSON\UTCDateTime $createdAt;
45+
46+
public function __construct(string $name)
47+
{
48+
$this->id = new MongoDB\BSON\ObjectId;
49+
$this->name = $name;
50+
$this->createdAt = new MongoDB\BSON\UTCDateTime;
51+
}
52+
53+
function bsonSerialize()
54+
{
55+
return [
56+
'_id' => $this->id,
57+
'name' => $this->name,
58+
'createdAt' => $this->createdAt,
59+
];
60+
}
61+
62+
function bsonUnserialize(array $data)
63+
{
64+
$this->id = $data['_id'];
65+
$this->name = $data['name'];
66+
$this->createdAt = $data['createdAt'];
67+
}
68+
}
69+
70+
The following example constructs a ``Person`` object, inserts it into the
71+
database, and reads it back as an object of the same type:
72+
73+
.. code-block:: php
74+
75+
<?php
76+
77+
$collection = (new MongoDB\Client)->test->persons;
78+
79+
$result = $collection->insertOne(new Person('Bob'));
80+
81+
$person = $collection->findOne(['_id' => $result->getInsertedId()]);
82+
83+
var_dump($person);
84+
85+
The output would then resemble:
86+
87+
.. code-block:: none
88+
89+
object(Person)#18 (3) {
90+
["id":"Person":private]=>
91+
object(MongoDB\BSON\ObjectId)#15 (1) {
92+
["oid"]=>
93+
string(24) "56fad2c36118fd2e9820cfc1"
94+
}
95+
["name":"Person":private]=>
96+
string(3) "Bob"
97+
["createdAt":"Person":private]=>
98+
object(MongoDB\BSON\UTCDateTime)#17 (1) {
99+
["milliseconds"]=>
100+
int(1459278531218)
101+
}
102+
}
103+
104+
The same document in the MongoDB shell might display as:
105+
106+
.. code-block:: js
107+
108+
{
109+
"_id" : ObjectId("56fad2c36118fd2e9820cfc1"),
110+
"__pclass" : BinData(128,"UGVyc29u"),
111+
"name" : "Bob",
112+
"createdAt" : ISODate("2016-03-29T19:08:51.218Z")
113+
}
114+
115+
.. note::
116+
117+
:php:`MongoDB\\BSON\\Persistable <mongodb-bson-persistable>` may only be used
118+
for root and embedded BSON documents. It may not be used for BSON arrays.

0 commit comments

Comments
 (0)