Skip to content

Commit 818e450

Browse files
jmikolajmikola
committed
Merge pull request mongodb#281 
2 parents 63a5d21 + 3828fbc commit 818e450

File tree

152 files changed

+3698
-1246
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

152 files changed

+3698
-1246
lines changed

‎CONTRIBUTING.md

Lines changed: 4 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -60,18 +60,10 @@ repository:
6060
repository.
6161
* Install [giza](https://pypi.python.org/pypi/giza/), as noted in the tools
6262
README.
63-
* Comment out the following `assets` entry in `config/build_conf.yaml`:
64-
```
65-
- branch: master
66-
path: build/php-library # this is where we'll put the source docs (from the driver repo)
67-
repository: https://github.com/mongodb/mongo-php-library.git
68-
```
69-
70-
* Create a symlink so that `build/php-library` points to your working copy of
71-
the [mongodb/mongo-php-library](https://github.com/mongodb/mongo-php-library)
72-
repository.
73-
* Build the documentation with `giza make html`. You can suppress informational
74-
log messages via the `--level warning` option.
63+
* Sync your working copy of the documentation to the `source/` directory with
64+
`rsync -a --delete /path/to/mongo-php-library/docs/ source/`.
65+
* Build the documentation with `giza make publish`. You can suppress
66+
informational log messages with the `--level warning` option.
7567
* Generated documentation may be found in the `build/master/html` directory.
7668

7769
## Releasing

‎docs/includes/apiargs-MongoDBClient-method-construct-driverOptions.yaml

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,99 @@ description: |
1717
interface: phpmethod
1818
operation: ~
1919
optional: true
20+
---
21+
arg_name: option
22+
name: allow_invalid_hostname
23+
type: boolean
24+
description: |
25+
Disables hostname validation if ``true``. Defaults to ``false``.
26+
27+
Allowing invalid hostnames may expose the driver to a `man-in-the-middle
28+
attack <https://en.wikipedia.org/wiki/Man-in-the-middle_attack>`_.
29+
interface: phpmethod
30+
operation: ~
31+
optional: true
32+
---
33+
arg_name: option
34+
name: ca_dir
35+
type: string
36+
description: |
37+
Path to a correctly hashed certificate directory. The system certificate store
38+
will be used by default.
39+
40+
Falls back to the deprecated ``capath`` SSL context option if not specified.
41+
interface: phpmethod
42+
operation: ~
43+
optional: true
44+
---
45+
arg_name: option
46+
name: ca_file
47+
type: string
48+
description: |
49+
Path to a certificate authority file. The system certificate store will be
50+
used by default.
51+
52+
Falls back to the deprecated ``cafile`` SSL context option if not specified.
53+
interface: phpmethod
54+
operation: ~
55+
optional: true
56+
---
57+
arg_name: option
58+
name: crl_file
59+
type: string
60+
description: |
61+
Path to a certificate revocation list file.
62+
interface: phpmethod
63+
operation: ~
64+
optional: true
65+
---
66+
arg_name: option
67+
name: pem_file
68+
type: string
69+
description: |
70+
Path to a PEM encoded certificate to use for client authentication.
71+
72+
Falls back to the deprecated ``local_cert`` SSL context option if not
73+
specified.
74+
interface: phpmethod
75+
operation: ~
76+
optional: true
77+
---
78+
arg_name: option
79+
name: pem_pwd
80+
type: string
81+
description: |
82+
Passphrase for the PEM encoded certificate (if applicable).
83+
84+
Falls back to the deprecated ``passphrase`` SSL context option if not
85+
specified.
86+
interface: phpmethod
87+
operation: ~
88+
optional: true
89+
---
90+
arg_name: option
91+
name: weak_cert_validation
92+
type: boolean
93+
description: |
94+
Disables certificate validation ``true``. Defaults to ``false``.
95+
96+
Falls back to the deprecated ``allow_self_signed`` SSL context option if not
97+
specified.
98+
interface: phpmethod
99+
operation: ~
100+
optional: true
101+
---
102+
arg_name: option
103+
name: context
104+
type: resource
105+
description: |
106+
:php:`SSL context options <manual/en/context.ssl.php>` to be used as fallbacks
107+
for other driver options (as specified). Note that the driver does not consult
108+
the default stream context.
109+
110+
This option is supported for backwards compatibility, but should be considered
111+
deprecated.
112+
interface: phpmethod
113+
operation: ~
114+
optional: true
20115
...

‎docs/includes/apiargs-MongoDBClient-method-construct-param.yaml

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,18 @@ name: $uri
33
type: string
44
description: |
55
The URI of the standalone, replica set, or sharded cluster to which to
6-
connect. Refer to the :manual:`MongoDB connection string reference
7-
</reference/connection-string>` for formatting.
6+
connect. Refer to :manual:`Connection String URI Format
7+
</reference/connection-string>` in the MongoDB manual for more information.
88
99
Defaults to ``"mongodb://127.0.0.1:27017"`` if unspecified.
10+
11+
Any special characters in the URI components need to be encoded according to
12+
`RFC 3986 <http://www.faqs.org/rfcs/rfc3986.html>`_. This is particularly
13+
relevant to the username and password, which can often include special
14+
characters such as ``@``, ``:``, or ``%``. When connecting via a Unix domain
15+
socket, the socket path may contain special characters such as slashes and
16+
must be encoded. The :php:`rawurlencode() <rawurlencode>` function may be used
17+
to encode constituent parts of the URI.
1018
interface: phpmethod
1119
operation: ~
1220
optional: true
@@ -17,7 +25,8 @@ type: array
1725
description: |
1826
Specifies additional URI options, such as authentication credentials or query
1927
string parameters. The options specified in ``$uriOptions`` take precedence
20-
over any analogous options present in the ``$uri`` string.
28+
over any analogous options present in the ``$uri`` string and do not need to
29+
be encoded according to `RFC 3986 <http://www.faqs.org/rfcs/rfc3986.html>`_.
2130
2231
Refer to the :php:`MongoDB\\Driver\\Manager::__construct()
2332
<mongodb-driver-manager.construct>` extension reference and :manual:`MongoDB

‎docs/includes/extracts-error.yaml

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
ref: error-driver-invalidargumentexception
2+
content: |
3+
:php:`MongoDB\\Driver\\Exception\\InvalidArgumentException
4+
<mongodb-driver-exception-invalidargumentexception>` for errors related to the
5+
parsing of parameters or options at the driver level.
6+
---
7+
ref: error-driver-runtimeexception
8+
content: |
9+
:php:`MongoDB\\Driver\\Exception\\RuntimeException
10+
<mongodb-driver-exception-runtimeexception>` for other errors at the driver
11+
level (e.g. connection errors).
12+
---
13+
ref: error-badmethodcallexception-write-result
14+
content: |
15+
:phpclass:`MongoDB\\Exception\\BadMethodCallException` if this method is
16+
called and the write operation used an unacknowledged :manual:`write concern
17+
</reference/write-concern>`.
18+
---
19+
ref: error-invalidargumentexception
20+
content: |
21+
:phpclass:`MongoDB\\Exception\\InvalidArgumentException` for errors related to
22+
the parsing of parameters or options.
23+
---
24+
ref: error-unexpectedvalueexception
25+
content: |
26+
:phpclass:`MongoDB\\Exception\\UnexpectedValueException` if the command
27+
response from the server was malformed.
28+
---
29+
ref: error-unsupportedexception
30+
content: |
31+
:phpclass:`MongoDB\\Exception\\UnsupportedException` if options are used and
32+
not supported by the selected server (e.g. ``collation``, ``writeConcern``).
33+
...

‎docs/index.txt

Lines changed: 23 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -4,28 +4,25 @@ MongoDB PHP Library
44

55
.. default-domain:: mongodb
66

7-
The |php-library| provides a high-level abstraction
8-
around the lower-level `PHP Driver <https://php.net/mongodb>`_, also
9-
known as the ``mongodb`` extension.
10-
11-
While the ``mongodb`` extension provides a limited API for executing
12-
commands, queries, and write operations, the |php-library|
13-
implements an API similar to that of the `legacy PHP driver
14-
<http://php.net/manual/en/book.mongo.php>`_. The library contains
15-
abstractions for client, database, and collection objects, and provides
16-
methods for CRUD operations and common commands such as index and
7+
The |php-library| provides a high-level abstraction around the lower-level
8+
`PHP Driver <https://php.net/mongodb>`_, also known as the ``mongodb``
9+
extension.
10+
11+
While the ``mongodb`` extension provides a limited API for executing commands,
12+
queries, and write operations, the |php-library| implements an API similar to
13+
that of the `legacy PHP driver <http://php.net/manual/en/book.mongo.php>`_. The
14+
library contains abstractions for client, database, and collection objects, and
15+
provides methods for CRUD operations and common commands such as index and
1716
collection management.
1817

19-
If you are developing a PHP application with MongoDB, you should consider
20-
using this library, or another high-level abstraction, instead of the
21-
extension alone.
18+
If you are developing a PHP application with MongoDB, you should consider using
19+
this library, or another high-level abstraction, instead of the extension alone.
2220

23-
For additional information about the MongoDB PHP Library and the
24-
``mongodb`` extension, see the `Architecture Overview
25-
<http://php.net/manual/en/mongodb.overview.php>`_ article in the
26-
extension documentation. `Derick Rethans <http://derickrethans.nl/>`_
27-
has also written a series of blog posts entitled *New MongoDB Drivers
28-
for PHP and HHVM*:
21+
For additional information about the MongoDB PHP Library and the ``mongodb``
22+
extension, see the `Architecture Overview
23+
<http://php.net/manual/en/mongodb.overview.php>`_ article in the extension
24+
documentation. `Derick Rethans <http://derickrethans.nl/>`_ has also written a
25+
series of blog posts entitled *New MongoDB Drivers for PHP and HHVM*:
2926

3027
- `Part One: History <https://derickrethans.nl/new-drivers.html>`_
3128

@@ -42,26 +39,23 @@ If you are a new MongoDB user, these links should help you become more familiar
4239
with MongoDB and introduce some of the concepts and terms you will encounter in
4340
this documentation:
4441

45-
- `Introduction to CRUD operations in MongoDB
46-
<http://docs.mongodb.org/manual/core/crud-introduction/>`_
42+
- :manual:`Introduction to CRUD operations in MongoDB </core/crud>`
4743

48-
- `What is a MongoDB document?
49-
<http://docs.mongodb.org/manual/core/document/>`_
44+
- :manual:`What is a MongoDB document? </core/document>`
5045

51-
- `MongoDB's *dot notation* for accessing document properties
52-
<http://docs.mongodb.org/manual/core/document/#dot-notation>`_
46+
- :manual:`Dot notation for accessing document properties
47+
</core/document/#dot-notation>`
5348

54-
- `ObjectId: MongoDB's document identifier
55-
<http://docs.mongodb.org/manual/reference/object-id/>`_
49+
- :manual:`ObjectId: MongoDB's document identifier </reference/object-id/>`
5650

5751
.. class:: hidden
5852

5953
.. toctree::
6054
:titlesonly:
61-
55+
6256
Installation </tutorial/install-php-library>
6357
/tutorial
6458
/upgrade
6559
/reference
6660

67-
.. /getting-started
61+
.. /getting-started

‎docs/reference.txt

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,12 @@ Reference
66

77
.. toctree::
88
:titlesonly:
9-
9+
1010
/reference/bson
1111
/reference/class/MongoDBClient
1212
/reference/class/MongoDBDatabase
1313
/reference/class/MongoDBCollection
1414
/reference/class/MongoDBGridFSBucket
15+
/reference/write-result-classes
16+
/reference/enumeration-classes
17+
/reference/exception-classes

0 commit comments

Comments
 (0)