Skip to content

Commit b645f49

Browse files
jmikolajmikola
committed
Merge branch 'v1.7' into v1.8
2 parents 143800d + 42b9f2e commit b645f49

File tree

5 files changed

+86
-94
lines changed

5 files changed

+86
-94
lines changed

Diff for: ‎README.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,10 @@ This library provides a high-level abstraction around the lower-level
77
[PHP driver](https://github.com/mongodb/mongo-php-driver) (`mongodb` extension).
88

99
While the extension provides a limited API for executing commands, queries, and
10-
write operations, this library implements an API similar to that of the
11-
[legacy PHP driver](https://php.net/manual/en/book.mongo.php). It contains
12-
abstractions for client, database, and collection objects, and provides methods
13-
for CRUD operations and common commands (e.g. index and collection management).
10+
write operations, this library implements a full-featured API similar to that of
11+
other MongoDB drivers. It contains abstractions for client, database, and
12+
collection objects, and provides methods for CRUD operations and common commands
13+
(e.g. index and collection management).
1414

1515
If you are developing an application with MongoDB, you should consider using
1616
this library, or another high-level abstraction, instead of the extension alone.

Diff for: ‎docs/index.txt

+3-4
Original file line numberDiff line numberDiff line change
@@ -35,10 +35,9 @@ following pages should help you get started:
3535

3636
- :doc:`/reference/bson`
3737

38-
If you have previously worked with the
39-
`legacy PHP driver <http://php.net/manual/en/book.mongo.php>`_ (i.e. ``mongo``
40-
extension), it will be helpful to review the :doc:`/upgrade` for a summary of
41-
API changes between the old driver and this library.
38+
If you have previously worked with the legacy ``mongo`` extension, it will be
39+
helpful to review the :doc:`/upgrade` for a summary of API changes between the
40+
old driver and this library.
4241

4342
New to MongoDB?
4443
---------------

Diff for: ‎docs/reference/bson.txt

+3-3
Original file line numberDiff line numberDiff line change
@@ -199,9 +199,9 @@ The same document in the MongoDB shell might display as:
199199
Emulating the Legacy Driver
200200
---------------------------
201201

202-
The legacy :php:`mongo extension <mongo>` returned both BSON documents and
203-
arrays as PHP arrays. While PHP arrays are convenient to work with, this
204-
behavior was problematic:
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:
205205

206206
- Different BSON types could deserialize to the same PHP value (e.g.
207207
``{"0": "foo"}`` and ``["foo"]``), which made it impossible to infer the

Diff for: ‎docs/reference/method/MongoDBClient__construct.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ By default, the |php-library| deserializes BSON documents and arrays
113113
as :phpclass:`MongoDB\\Model\\BSONDocument` and
114114
:phpclass:`MongoDB\\Model\\BSONArray` objects, respectively. The following
115115
example demonstrates how to have the library unserialize everything as a PHP
116-
array, as was done in the legacy :php:`mongo extension <mongo>`.
116+
array, as was done in the legacy ``mongo`` extension.
117117

118118
.. code-block:: php
119119

Diff for: ‎docs/upgrade.txt

+75-82
Original file line numberDiff line numberDiff line change
@@ -14,22 +14,20 @@ Overview
1414
--------
1515

1616
The |php-library| and underlying :php:`mongodb extension <mongodb>` have notable
17-
API differences from the legacy :php:`mongo extension <mongo>`. This page will
18-
summarize those differences for the benefit of those upgrading from the legacy
19-
driver.
17+
API differences from the legacy ``mongo`` extension. This page will summarize
18+
those differences for the benefit of those upgrading from the legacy driver.
2019

2120
Additionally, a community-developed `mongo-php-adapter
2221
<https://github.com/alcaeus/mongo-php-adapter>`_ library exists, which
23-
implements the `mongo extension <http://php.net/mongo>`_ API using this library
24-
and the new driver. While this adapter library is not officially supported by
25-
MongoDB, it does bear mentioning.
22+
implements the ``mongo`` extension API using this library and the new driver.
23+
While this adapter library is not officially supported by MongoDB, it does bear
24+
mentioning.
2625

2726
BSON Type Classes
2827
-----------------
2928

30-
When upgrading from the legacy driver,
31-
`type classes <https://www.php.net/manual/en/mongo.types.php>`_ such as
32-
:php:`MongoId <mongoid>` must be replaced with classes in the
29+
When upgrading from the legacy driver, type classes such as MongoId must be
30+
replaced with classes in the
3331
`MongoDB\\BSON namespace <https://www.php.net/manual/en/book.bson.php>`_. The
3432
new driver also introduces interfaces for its BSON types, which should be
3533
preferred if applications need to type hint against BSON values.
@@ -44,67 +42,66 @@ the new driver.
4442
- BSON type class
4543
- BSON type interface
4644

47-
* - :php:`MongoId <mongoid>`
45+
* - MongoId
4846
- :php:`MongoDB\\BSON\\ObjectId <mongodb_bson_objectid>`
4947
- :php:`MongoDB\\BSON\\ObjectIdInterface <mongodb_bson_objectidinterface>`
5048

51-
* - :php:`MongoCode <mongocode>`
49+
* - MongoCode
5250
- :php:`MongoDB\\BSON\\Javascript <mongodb_bson_javascript>`
5351
- :php:`MongoDB\\BSON\\JavascriptInterface <mongodb_bson_javascriptinterface>`
5452

55-
* - :php:`MongoDate <mongodate>`
53+
* - MongoDate
5654
- :php:`MongoDB\\BSON\\UTCDateTime <mongodb_bson_utcdatetime>`
5755
- :php:`MongoDB\\BSON\\UTCDateTimeInterface <mongodb_bson_utcdatetimeinterface>`
5856

59-
* - :php:`MongoRegex <mongoregex>`
57+
* - MongoRegex
6058
- :php:`MongoDB\\BSON\\Regex <mongodb_bson_regex>`
6159
- :php:`MongoDB\\BSON\\RegexInterface <mongodb_bson_regexinterface>`
6260

63-
* - :php:`MongoBinData <mongobindata>`
61+
* - MongoBinData
6462
- :php:`MongoDB\\BSON\\Binary <mongodb_bson_binary>`
6563
- :php:`MongoDB\\BSON\\BinaryInterface <mongodb_bson_binaryinterface>`
6664

67-
* - :php:`MongoInt32 <mongoint32>`
65+
* - MongoInt32
6866
- Not implemented. [1]_
6967
-
7068

71-
* - :php:`MongoInt64 <mongoint64>`
69+
* - MongoInt64
7270
- :php:`MongoDB\\BSON\\Int64 <mongodb_bson_int64>`
7371
- Not implemented. [2]_
7472

75-
* - :php:`MongoDBRef <mongodbref>`
73+
* - MongoDBRef
7674
- Not implemented. [3]_
7775
-
7876

79-
* - :php:`MongoMinKey <mongominkey>`
77+
* - MongoMinKey
8078
- :php:`MongoDB\\BSON\\MinKey <mongodb_bson_minkey>`
8179
- :php:`MongoDB\\BSON\\MinKeyInterface <mongodb_bson_minkeyinterface>`
8280

83-
* - :php:`MongoMaxKey <mongomaxkey>`
81+
* - MongoMaxKey
8482
- :php:`MongoDB\\BSON\\MaxKey <mongodb_bson_maxkey>`
8583
- :php:`MongoDB\\BSON\\MaxKeyInterface <mongodb_bson_maxkeyinterface>`
8684

87-
* - :php:`MongoTimestamp <mongotimestamp>`
85+
* - MongoTimestamp
8886
- :php:`MongoDB\\BSON\\Timestamp <mongodb_bson_timestamp>`
8987
- :php:`MongoDB\\BSON\\TimestampInterface <mongodb_bson_timestampinterface>`
9088

91-
.. [1] The new driver does not implement an equivalent class for
92-
:php:`MongoInt32 <mongoint32>`. When decoding BSON, 32-bit integers will
93-
always be represented as a PHP integer. When encoding BSON, PHP integers will
94-
encode as either a 32-bit or 64-bit integer depending on their value.
89+
.. [1] The new driver does not implement an equivalent class for MongoInt32.
90+
When decoding BSON, 32-bit integers will always be represented as a PHP
91+
integer. When encoding BSON, PHP integers will encode as either a 32-bit or
92+
64-bit integer depending on their value.
9593

9694
.. [2] :php:`MongoDB\\BSON\\Int64 <mongodb_bson_int64>` does not have an
9795
interface defined. The new driver does not allow applications to instantiate
9896
this type (i.e. its constructor is private) and it is only created during
9997
BSON decoding when a 64-bit integer cannot be represented as a PHP integer on
10098
a 32-bit platform.
10199

102-
.. [3] The new driver does not implement an equivalent class for
103-
:php:`MongoDBRef <mongodbref>` since
104-
:manual:`DBRefs </reference/database-references>` are merely a BSON document
105-
with a particular structure and not a proper BSON type. The new driver also
106-
does not provide any helpers for working with DBRef objects, since their use
107-
is not encouraged.
100+
.. [3] The new driver does not implement an equivalent class for MongoDBRef
101+
since :manual:`DBRefs </reference/database-references>` are merely a BSON
102+
document with a particular structure and not a proper BSON type. The new
103+
driver also does not provide any helpers for working with DBRef objects,
104+
since their use is not encouraged.
108105

109106
Collection API
110107
--------------
@@ -116,15 +113,13 @@ and `Index Management
116113
<https://github.com/mongodb/specifications/blob/master/source/index-management.rst>`_
117114
specifications. Although some method names have changed in accordance with the
118115
new specifications, the new class provides the same functionality as the legacy
119-
driver's :php:`MongoCollection <mongocollection>` class with some notable
120-
exceptions.
116+
driver's MongoCollection class with some notable exceptions.
121117

122118
A guiding principle in designing the new APIs was that explicit method names are
123119
preferable to overloaded terms found in the old API. For instance,
124-
:php:`MongoCollection::save() <mongocollection.save>` and
125-
:php:`MongoCollection::findAndModify() <mongocollection.findandmodify>`
126-
have different modes of operation, depending on their arguments. Methods were
127-
also split to distinguish between :manual:`updating specific fields
120+
``MongoCollection::save()`` and ``MongoCollection::findAndModify()`` have
121+
different modes of operation, depending on their arguments. Methods were also
122+
split to distinguish between :manual:`updating specific fields
128123
</tutorial/modify-documents>` and :manual:`full-document replacement
129124
</tutorial/modify-documents/#replace-the-document>`.
130125

@@ -134,116 +129,115 @@ equivalent method(s) in the new driver.
134129
.. list-table::
135130
:header-rows: 1
136131

137-
* - :php:`MongoCollection <mongocollection>` method
132+
* - MongoCollection method
138133
- :phpclass:`MongoDB\\Collection` method(s)
139134

140-
* - :php:`MongoCollection::aggregate() <mongocollection.aggregate>`
135+
* - ``MongoCollection::aggregate()``
141136
- :phpmethod:`MongoDB\\Collection::aggregate()`
142137

143-
* - :php:`MongoCollection::aggregateCursor() <mongocollection.aggregatecursor>`
138+
* - ``MongoCollection::aggregateCursor()``
144139
- :phpmethod:`MongoDB\\Collection::aggregate()`
145140

146-
* - :php:`MongoCollection::batchInsert() <mongocollection.batchinsert>`
141+
* - ``MongoCollection::batchInsert()``
147142
- :phpmethod:`MongoDB\\Collection::insertMany()`
148143

149-
* - :php:`MongoCollection::count() <mongocollection.count>`
144+
* - ``MongoCollection::count()``
150145
- :phpmethod:`MongoDB\\Collection::count()`
151146

152-
* - :php:`MongoCollection::createDBRef() <mongocollection.createdbref>`
147+
* - ``MongoCollection::createDBRef()``
153148
- Not yet implemented. [3]_
154149

155-
* - :php:`MongoCollection::createIndex() <mongocollection.createindex>`
150+
* - ``MongoCollection::createIndex()``
156151
- :phpmethod:`MongoDB\\Collection::createIndex()`
157152

158-
* - :php:`MongoCollection::deleteIndex() <mongocollection.deleteindex>`
153+
* - ``MongoCollection::deleteIndex()``
159154
- :phpmethod:`MongoDB\\Collection::dropIndex()`
160155

161-
* - :php:`MongoCollection::deleteIndexes() <mongocollection.deleteindexes>`
156+
* - ``MongoCollection::deleteIndexes()``
162157
- :phpmethod:`MongoDB\\Collection::dropIndexes()`
163158

164-
* - :php:`MongoCollection::drop() <mongocollection.drop>`
159+
* - ``MongoCollection::drop()``
165160
- :phpmethod:`MongoDB\\Collection::drop()`
166161

167-
* - :php:`MongoCollection::distinct() <mongocollection.distinct>`
162+
* - ``MongoCollection::distinct()``
168163
- :phpmethod:`MongoDB\\Collection::distinct()`
169164

170-
* - :php:`MongoCollection::ensureIndex() <mongocollection.ensureindex>`
165+
* - ``MongoCollection::ensureIndex()``
171166
- :phpmethod:`MongoDB\\Collection::createIndex()`
172167

173-
* - :php:`MongoCollection::find() <mongocollection.find>`
168+
* - ``MongoCollection::find()``
174169
- :phpmethod:`MongoDB\\Collection::find()`
175170

176-
* - :php:`MongoCollection::findAndModify() <mongocollection.findandmodify>`
171+
* - ``MongoCollection::findAndModify()``
177172
- :phpmethod:`MongoDB\\Collection::findOneAndDelete()`,
178173
:phpmethod:`MongoDB\\Collection::findOneAndReplace()`, and
179174
:phpmethod:`MongoDB\\Collection::findOneAndUpdate()`
180175

181-
* - :php:`MongoCollection::findOne() <mongocollection.findone>`
176+
* - ``MongoCollection::findOne()``
182177
- :phpmethod:`MongoDB\\Collection::findOne()`
183178

184-
* - :php:`MongoCollection::getDBRef() <mongocollection.getdbref>`
179+
* - ``MongoCollection::getDBRef()``
185180
- Not implemented. [3]_
186181

187-
* - :php:`MongoCollection::getIndexInfo() <mongocollection.getindexinfo>`
182+
* - ``MongoCollection::getIndexInfo()``
188183
- :phpmethod:`MongoDB\\Collection::listIndexes()`
189184

190-
* - :php:`MongoCollection::getName() <mongocollection.getname>`
185+
* - ``MongoCollection::getName()``
191186
- :phpmethod:`MongoDB\\Collection::getCollectionName()`
192187

193-
* - :php:`MongoCollection::getReadPreference() <mongocollection.getreadpreference>`
194-
- Not implemented.
188+
* - ``MongoCollection::getReadPreference()``
189+
- :phpmethod:`MongoDB\\Collection::getReadPreference()`
195190

196-
* - :php:`MongoCollection::getSlaveOkay() <mongocollection.getslaveokay>`
191+
* - ``MongoCollection::getSlaveOkay()``
197192
- Not implemented.
198193

199-
* - :php:`MongoCollection::getWriteConcern() <mongocollection.getwriteconcern>`
200-
- Not implemented.
194+
* - ``MongoCollection::getWriteConcern()``
195+
- :phpmethod:`MongoDB\\Collection::getWriteConcern()`
201196

202-
* - :php:`MongoCollection::group() <mongocollection.group>`
197+
* - ``MongoCollection::group()``
203198
- Not implemented. Use :phpmethod:`MongoDB\\Database::command()`. See
204199
`Group Command Helper`_ for an example.
205200

206-
* - :php:`MongoCollection::insert() <mongocollection.insert>`
201+
* - ``MongoCollection::insert()``
207202
- :phpmethod:`MongoDB\\Collection::insertOne()`
208203

209-
* - :php:`MongoCollection::parallelCollectionScan() <mongocollection.parallelcollectionscan>`
204+
* - ``MongoCollection::parallelCollectionScan()``
210205
- Not implemented.
211206

212-
* - :php:`MongoCollection::remove() <mongocollection.remove>`
207+
* - ``MongoCollection::remove()``
213208
- :phpmethod:`MongoDB\\Collection::deleteMany()` and
214209
:phpmethod:`MongoDB\\Collection::deleteOne()`
215210

216-
* - :php:`MongoCollection::save() <mongocollection.save>`
211+
* - ``MongoCollection::save()``
217212
- :phpmethod:`MongoDB\\Collection::insertOne()` or
218213
:phpmethod:`MongoDB\\Collection::replaceOne()` with the ``upsert``
219214
option.
220215

221-
* - :php:`MongoCollection::setReadPreference() <mongocollection.setreadpreference>`
216+
* - ``MongoCollection::setReadPreference()``
222217
- Not implemented. Use :phpmethod:`MongoDB\\Collection::withOptions()`.
223218

224-
* - :php:`MongoCollection::setSlaveOkay() <mongocollection.getslaveokay>`
219+
* - ``MongoCollection::setSlaveOkay()``
225220
- Not implemented.
226221

227-
* - :php:`MongoCollection::setWriteConcern() <mongocollection.setwriteconcern>`
222+
* - ``MongoCollection::setWriteConcern()``
228223
- Not implemented. Use :phpmethod:`MongoDB\\Collection::withOptions()`.
229224

230-
* - :php:`MongoCollection::update() <mongocollection.update>`
225+
* - ``MongoCollection::update()``
231226
- :phpmethod:`MongoDB\\Collection::replaceOne()`,
232227
:phpmethod:`MongoDB\\Collection::updateMany()`, and
233228
:phpmethod:`MongoDB\\Collection::updateOne()`.
234229

235-
* - :php:`MongoCollection::validate() <mongocollection.validate>`
230+
* - ``MongoCollection::validate()``
236231
- Not implemented.
237232

238233
Accessing IDs of Inserted Documents
239234
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
240235

241-
In the legacy driver, :php:`MongoCollection::insert() <mongocollection.insert>`,
242-
:php:`MongoCollection::batchInsert() <mongocollection.batchinsert>`, and
243-
:php:`MongoCollection::save() <mongocollection.save>` (when inserting) would
244-
modify their input argument by injecting an ``_id`` key with a generated
245-
ObjectId (i.e. :php:`MongoId <class.mongoid>` object). This behavior was a bit
246-
of a hack, as it did not rely on the argument being :php:`passed by reference
236+
In the legacy driver, ``MongoCollection::insert()``,
237+
``MongoCollection::batchInsert()``, and ``MongoCollection::save()`` (when
238+
inserting) would modify their input argument by injecting an ``_id`` key with a
239+
generated ObjectId (i.e. MongoId object). This behavior was a bit of a hack, as
240+
it did not rely on the argument being :php:`passed by reference
247241
<language.references.pass>`; instead, it directly modified memory through the
248242
extension API and could not be implemented in PHP userland. As such, it is no
249243
longer done in the new driver and library.
@@ -261,17 +255,16 @@ following methods on the write result objects:
261255
Bulk Write Operations
262256
~~~~~~~~~~~~~~~~~~~~~
263257

264-
The legacy driver's :php:`MongoWriteBatch <class.mongowritebatch>` classes have
265-
been replaced with a general-purpose
266-
:phpmethod:`MongoDB\\Collection::bulkWrite()` method. Whereas the legacy driver
267-
only allowed bulk operations of the same type, the new method allows operations
268-
to be mixed (e.g. inserts, updates, and deletes).
258+
The legacy driver's MongoWriteBatch classes have been replaced with a
259+
general-purpose :phpmethod:`MongoDB\\Collection::bulkWrite()` method. Whereas
260+
the legacy driver only allowed bulk operations of the same type, the new method
261+
allows operations to be mixed (e.g. inserts, updates, and deletes).
269262

270263
MongoCollection::save() Removed
271264
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
272265

273-
:php:`MongoCollection::save() <mongocollection.save>`, which was syntactic sugar
274-
for an insert or upsert operation, has been removed in favor of explicitly using
266+
``MongoCollection::save()``, which was syntactic sugar for an insert or upsert
267+
operation, has been removed in favor of explicitly using
275268
:phpmethod:`MongoDB\\Collection::insertOne` or
276269
:phpmethod:`MongoDB\\Collection::replaceOne` (with the ``upsert`` option).
277270

0 commit comments

Comments
 (0)