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.
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 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.
Install the library by running:
$ composer require "mongodb/mongodb=^1.0.0"
It will output something akin to:
./composer.json has been created
Loading composer repositories with package information
Updating dependencies (including require-dev)
- Installing mongodb/mongodb (1.0.0)
Downloading: 100%
Writing lock file
Generating autoload files
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:
<?php
// This path should point to Composer's autoloader
require 'vendor/autoload.php';
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 for database-level operations (e.g. commands, collection management)
and a
» Collection
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.
As an example, this is how you insert a document into the
beers collection of the demo
database:
<?php
require 'vendor/autoload.php'; // include Composer goodies
$client = new MongoDB\Client("mongodb://localhost:27017");
$collection = $client->demo->beers;
$result = $collection->insertOne( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );
echo "Inserted with Object ID '{$result->getInsertedId()}'";
?>
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 an
iterable cursor:
<?php
require 'vendor/autoload.php'; // include Composer goodies
$client = new MongoDB\Client("mongodb://localhost:27017");
$collection = $client->demo->beers;
$result = $collection->find( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );
foreach ($result as $entry) {
echo $entry['_id'], ': ', $entry['name'], "\n";
}
?>
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
Persisting Data specification.