From c718200b2753a2182682aa7fd00e093cd33e3d74 Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Sun, 24 Jan 2016 05:09:52 +0000 Subject: [PATCH] Update configure and tutorial docs for ext-mongodb and library https://jira.mongodb.org/browse/PHPC-468 git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@338537 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mongodb/configure.xml | 188 ++++++++++++++++++++--- reference/mongodb/tutorial.xml | 16 +- reference/mongodb/tutorial/hhvm.xml | 104 +++---------- reference/mongodb/tutorial/library.xml | 203 +++++++++++++------------ reference/mongodb/tutorial/php.xml | 37 ----- 5 files changed, 290 insertions(+), 258 deletions(-) delete mode 100644 reference/mongodb/tutorial/php.xml diff --git a/reference/mongodb/configure.xml b/reference/mongodb/configure.xml index 7498d1e136..8f2b77631e 100644 --- a/reference/mongodb/configure.xml +++ b/reference/mongodb/configure.xml @@ -4,11 +4,17 @@
&reftitle.install; -
- PHP +
+ Installing the MongoDB PHP Driver with PECL - Run: + &pecl.info; + &url.pecl.package;mongodb + + + + Linux, Unix, and OS X users may run the following command to install the + driver: - Add the following line to your php.ini file: + Add the following line to your &php.ini; file: +
+ +
+ Installing the MongoDB PHP Driver on OSX with Homebrew - Windows users should include php_mongodb.dll into &php.ini; + If you are using Homebrew, the + PHP tap includes formulae for installing the driver on various PHP versions. + + + + php54-mongodb + php55-mongodb + php56-mongodb + php70-mongodb + + + + For example, you might install the driver for PHP 7.0 using the following + command: + + + + +
+ +
+ Installing the MongoDB PHP Driver on Windows + + + Precompiled binaries for each release are available from + PECL for a variety of + combinations of versions, thread safety, and VC libraries. Extract the + archive and put php_mongo.dll in your PHP extension + directory ("ext" by default). + + + + Add the following line to your &php.ini; file: + + + + +
+ +
+ Manually Installing the MongoDB PHP Driver + + + For driver developers and people interested in the latest bugfixes, you can + compile the driver from the latest source code on + Github. Run the following + commands to clone and build the project: + + + + + + + The last step will report where mongodb.so has been + installed, similar to: + + + + + + + Ensure that the extension_dir option + in &php.ini; points to the directory where mongodb.so + was installed. You can query the option by running: + + /usr/lib/php/extensions/debug-non-zts-20151012 => + /usr/lib/php/extensions/debug-non-zts-20151012 +]]> + + + + + If the directories differ, either change + extension_dir in &php.ini; or + manually move mongodb.so to the correct directory. + + + + Add the following line to your &php.ini; file: + + +
- HHVM + Manually Installing the MongoDB HHVM Driver - HHVM users should download the latest from - S3 - for the time being. + At the time of this writing, HHVM does not have a package manager for + extensions. Download the latest driver from + GitHub. Alternatively, + you may clone the repository to build the latest source code: + + + - Once downloaded, execute the following steps: - + Generate the configure files for the bundled libraries. For this + this to work, you need to have the automake, + autoconf, and libtool packages installed (e.g. + through apt-get). + + + - Add the following line to your php.ini file (usually found in /etc/hhvm): + Build and install the driver by running: + + + + + + + + If the hphpize command is not available, you will need to + either compile HHVM from source or install the hhvm-dev package + (e.g. through apt-get). + + + + + The last step will report where mongodb.so has been + installed, similar to: + + + + + + + Add the following line to your &php.ini; file (usually found in "/etc/hhvm"): In this section you will find several tutorials on how to use the MongoDB driver for PHP and HHVM. Because the drivers work exactly the same, they - share common usage tutorials, but have a separate installation section. - - - In order to work through them all, pick either or section and then continue by - following the link at the bottom of each of these sections. + share common usage tutorials, but have a separate installation sections. - - Installing the driver - - &reference.mongodb.tutorial.hhvm; - &reference.mongodb.tutorial.php; - - + &reference.mongodb.tutorial.hhvm; &reference.mongodb.tutorial.library; diff --git a/reference/mongodb/tutorial/hhvm.xml b/reference/mongodb/tutorial/hhvm.xml index 79b7ebaac1..183ee50c1c 100644 --- a/reference/mongodb/tutorial/hhvm.xml +++ b/reference/mongodb/tutorial/hhvm.xml @@ -1,8 +1,8 @@ -
- Installation with HHVM + + Getting Started with HHVM In this section you will learn how to set-up NGINX with HHVM and MongoDB. @@ -11,13 +11,13 @@ - In this tutorial, we will be using a Debian system, with NGINX installed - through apt-get and HHVM installed from - source into /usr/local/hhvm/3.9.1 - (with the binary located at /usr/local/hhvm/3.9.1/bin/hhvm). + In this tutorial, we will be using a Debian system with NGINX installed + through apt-get and HHVM installed from source or pre-built + packages into /usr/local/hhvm/3.9.1 (with the binary located at + /usr/local/hhvm/3.9.1/bin/hhvm). -
+
NGINX @@ -41,7 +41,7 @@
-
+
HHVM @@ -49,8 +49,8 @@ we've installed HHVM from source to faciliate patch development and ensure that debug symbols are available. That said, the folks at Facebook also provide pre-built packages, which is probably what you - to use in production and development. You can find installation instructions - for these packages on the + will want to use in production and development. You can find installation + instructions for these packages on the HHVM Wiki. @@ -94,7 +94,7 @@ sudo -u www-data -s /usr/local/hhvm/3.9.1/bin/hhvm \
-
+
Making NGINX talk to HHVM @@ -105,7 +105,7 @@ sudo -u www-data -s /usr/local/hhvm/3.9.1/bin/hhvm \ location / { … } section: - +
-
+
MongoDB Driver for HHVM The MongoDB driver is the part that links up the PHP in HHVM with the database server. To install and register the driver with HHVM, you need to - take the following steps: - - - - Download the latest driver from - GitHub (at the time - of this writing, HHVM does not have a package manager for extensions). In - the examples below, we will use "x.y.z" as a version placeholder. - - - - - Unpack the archive: tar -xvzf hhvm-mongodb-x.y.z.tgz - - - - - Change to the newly created directory: cd hhvm-mongodb-x.y.z - - - - - Generate the configure files for the bundled libraries. For - this to work, you need to have the automake, - autoconf, and libtool packages installed - (through apt-get). - - - - - - - - - Generate the Makefile: hphpize && cmake . - - - - - Build the driver: make -j 5 - - - - - Install the driver: sudo make install. This last step will - report where the binary file mongodb.so has been installed. - It should show somthing similar to: Installing: - /usr/local/hhvm/3.9.1/lib/hhvm/extensions/20150212/mongodb.so - - - + follow the steps in . - Now that the driver is installed, you need to enable it in HHVM. Add the - following lines to /etc/hhvm/php.ini, swapping out the directory - in this example for the path shown after running make install: - - - - - - - - After you have done this, HHVM will need to be restarted. If you have HHVM - running in the shell from earlier, stop it with Ctrl-C and restart it again - as above: + After you have installed and enabled the extension, HHVM will need to be + restarted. If you have HHVM running in the shell from earlier, stop it with + Ctrl-C and restart it again as above: @@ -277,7 +211,7 @@ var_dump(phpversion("mongodb")); This should output something similar to: - + @@ -292,7 +226,7 @@ string(5) "x.y.z"
-
+ - Using the library + Using the PHP Library (PHPLIB) - After the initial set-up, we continue explaining how to get started with the - MongoDB driver and library for HHVM to write our first project. + After the initial driver set-up, we will continue explaining how to get + started with the MongoDB driver and corresponding userland library to write + our first project. -
- PHP Library (PHPLIB) +
+ Installing the PHP Library with Composer - - The last thing we still need to install to get started on the application - itself, is the PHP library. + + The last thing we still need to install to get started on the application + itself, is the PHP library. + + + + The library needs to be installed with + Composer, a package manager + for PHP. Instructions for installing Composer on various platforms may be + found on its website. - The library needs to be installed with Composer. In your project directory - (/var/www/html/my-first-project) type: - + Install the library by running: -curl -sS https://getcomposer.org/installer -o installer.php -hhvm installer.php -rm installer.php - - - - - This downloads and installs Composer. Wherever it says "Use it: php - composer.phar", it of course means hhvm composer.phar. - - - -With Composer installed, we can now install the library: - - -hhvm composer.phar require mongodb/mongodb - - - - -It outputs something akin to: - - -Using version ^0.2.0 for mongodb/mongodb -./composer.json has been created -Loading composer repositories with package information -Updating dependencies (including require-dev) - - Installing mongodb/mongodb (0.2.0) - Downloading: 100% - -Writing lock file -Generating autoload files - - - - - And it has created several files (composer.json, - composer.lock) as well as the vendor directory - that contains the library. - -
- -
- Using the Library - - - Composer manages your dependencies, and will provide you with a loader that - you include with the following at the start of your script: - - - With this done, you can now use any of the functionality as described in - the documentation. +It will output something akin to: + + + + - If you are familiar with the old driver, it should look too much out of - place. The only big difference is that the + Composer will create several files: composer.json, + composer.lock, and a vendor directory that will + contain the library and any other dependencies your project might require. + +
+ +
+ Using the PHP Library + + + In addition to managing your dependencies, Composer will also provide you + with an autoloader (for those dependencies' classes). Ensure that it is + included at the start of your script or in your application's bootstrap + code: + + + + + + + With this done, you can now use any of the functionality as described in the + library documentation + and its API. + + + + If you have previously used the old driver (i.e. mongo + extension), the library's API should look familiar. It contains a + Client + class for connecting to MongoDB, and Database - class is only used for Database specific operations. The - CRUD operations on the + class for database-level operations (e.g. commands, collection management) + and a Collection - class are also renamed for clarity, and to be in accordance with a new - language-agnostic + class for collection-level operations (e.g. + CRUD methods, index management). + Various Collection methods have been renamed for clarity, and to be in + accordance with a new language-agnostic specification. @@ -100,60 +101,60 @@ Generating autoload files As an example, this is how you insert a document into the beers collection of the demo database: - demo->beers; - $result = $collection->insertOne( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] ); +$result = $collection->insertOne( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] ); - echo "Inserted with Object ID '{$result->getInsertedId()}'"; - ?> +echo "Inserted with Object ID '{$result->getInsertedId()}'"; +?> ]]> - Instead of the original document being modified to add the newly generated - _id field, this is now part of the result that comes back - from the insertOne method. + Instead of injecting the generated _id field into the input + document (as was done in the old driver), it is now made available through + the result object returned by the insertOne method. After insertion, you can of course also query the data that you have just - inserted. For that, you use the find method which returns a - cursor that you can iterate over: - + inserted. For that, you use the find method, which returns an + iterable cursor: demo->beers; - $result = $collection->find( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] ); +$result = $collection->find( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] ); - foreach ($result as $entry) - { - echo $entry->_id, ': ', $entry->name, "\n"; - } - ?> +foreach ($result as $entry) { + echo $entry['_id'], ': ', $entry['name'], "\n"; +} +?> ]]> - You might have noticed that instead of accessing the _id and - name fields is no longer done through an array access - operator. Instead, they are now properties of a stdClass - object. You can find more information on how serialisation and - deserialisation between PHP variables and the BSON stored in MongoDB in - the specification. + While it may not be apparent in the examples, BSON documents and arrays are + unserialized as type classes in the library by default. These classes ensure + that values preserve their type when being serialized back into BSON, which + avoids a caveat in the old driver where arrays might turn into documents, + and vice versa. Additionally, the classes extend + ArrayObject for enhanced usability. You can find more + information on how serialization and deserialization between PHP variables + and BSON is handled by the driver and library by reading the + specification.
diff --git a/reference/mongodb/tutorial/php.xml b/reference/mongodb/tutorial/php.xml deleted file mode 100644 index 37a2ca11e1..0000000000 --- a/reference/mongodb/tutorial/php.xml +++ /dev/null @@ -1,37 +0,0 @@ - - - -
- Installation with PHP - - - -
- Further reading - - - Continue this tutorial by jumping to - -
-
-