<?php
include_once $_SERVER['DOCUMENT_ROOT'] . '/include/shared-manual.inc';
$TOC = array();
$TOC_DEPRECATED = array();
$PARENTS = array();
include_once dirname(__FILE__) ."/toc/mongodb.tutorial.inc";
$setup = array (
  'home' => 
  array (
    0 => 'index.php',
    1 => 'PHP Manual',
  ),
  'head' => 
  array (
    0 => 'UTF-8',
    1 => 'tr',
  ),
  'this' => 
  array (
    0 => 'mongodb.tutorial.library.php',
    1 => 'Using the PHP Library for MongoDB (PHPLIB)',
  ),
  'up' => 
  array (
    0 => 'mongodb.tutorial.php',
    1 => 'Tutorials',
  ),
  'prev' => 
  array (
    0 => 'mongodb.tutorial.php',
    1 => 'Tutorials',
  ),
  'next' => 
  array (
    0 => 'mongodb.tutorial.apm.php',
    1 => 'Application Performance Monitoring (APM)',
  ),
  'alternatives' => 
  array (
  ),
  'source' => 
  array (
    'lang' => 'en',
    'path' => 'reference/mongodb/tutorial/library.xml',
  ),
  'history' => 
  array (
  ),
);
$setup["toc"] = $TOC;
$setup["toc_deprecated"] = $TOC_DEPRECATED;
$setup["parents"] = $PARENTS;
manual_setup($setup);

contributors($setup);

?>
<div id="mongodb.tutorial.library" class="section">
 <h2 class="title">Using the PHP Library for MongoDB (PHPLIB)</h2>

 <p class="para">
  After the initial extension set-up, we will continue explaining how to get
  started with the corresponding userland library to write our first project.
 </p>

 <div class="section">
  <h2 class="title">Installing the PHP Library with Composer</h2>

  <p class="para">
   The last thing we still need to install to get started on the application
   itself, is the PHP library.
  </p>

  <p class="para">
   The library needs to be installed with
   <a href="https://getcomposer.org/" class="link external">&raquo;&nbsp;Composer</a>, a package manager
   for PHP. Instructions for installing Composer on various platforms may be
   found on its website.
   </p>

   <p class="para">
    Install the library by running:
    <div class="example-contents">
<div class="shellcode"><pre class="shellcode">$ composer require mongodb/mongodb</pre>
</div>
    </div>

   </p>

   <p class="para">
It will output something akin to:

    <div class="example-contents">
<div class="textcode"><pre class="textcode">./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</pre>
</div>
    </div>

   </p>

   <p class="para">
    Composer will create several files: <code class="code">composer.json</code>,
    <code class="code">composer.lock</code>, and a <code class="code">vendor</code> directory that will
    contain the library and any other dependencies your project might require.
   </p>
  </div>

  <div class="section">
   <h2 class="title">Using the PHP Library</h2>

   <p class="para">
    In addition to managing your dependencies, Composer will also provide you
    with an autoloader (for those dependencies&#039; classes). Ensure that it is
    included at the start of your script or in your application&#039;s bootstrap
    code:
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000"><span style="color: #0000BB">&lt;?php<br /></span><span style="color: #FF8000">// This path should point to Composer's autoloader<br /></span><span style="color: #007700">require </span><span style="color: #DD0000">'vendor/autoload.php'</span><span style="color: #007700">;</span></span></code></div>
    </div>

   </p>

   <p class="para">
    With this done, you can now use any of the functionality as described in the
    <a href="https://www.mongodb.com/docs/php-library/current/" class="link external">&raquo;&nbsp;library documentation</a>.
   </p>

   <p class="para">
    If you have used MongoDB drivers in other languages, the library&#039;s API
    should look familiar. It contains a
    <a href="https://www.mongodb.com/docs/php-library/master/reference/class/MongoDBClient/" class="link external">&raquo;&nbsp;Client</a>
    class for connecting to MongoDB, a
    <a href="https://www.mongodb.com/docs/php-library/master/reference/class/MongoDBDatabase/" class="link external">&raquo;&nbsp;Database</a>
    class for database-level operations (e.g. commands, collection management),
    and a
    <a href="https://www.mongodb.com/docs/php-library/master/reference/class/MongoDBCollection" class="link external">&raquo;&nbsp;Collection</a>
    class for collection-level operations (e.g.
    <a href="https://en.wikipedia.org/wiki/Create,_read,_update_and_delete" class="link external">&raquo;&nbsp;CRUD</a> methods, index management).
   </p>

   <p class="para">
    As an example, this is how you insert a document into the
    <em>beers</em> collection of the <em>demo</em>
    database:
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000"><span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">require </span><span style="color: #DD0000">'vendor/autoload.php'</span><span style="color: #007700">; </span><span style="color: #FF8000">// include Composer's autoloader<br /><br /></span><span style="color: #0000BB">$client </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoDB\Client</span><span style="color: #007700">(</span><span style="color: #DD0000">"mongodb://localhost:27017"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$collection </span><span style="color: #007700">= </span><span style="color: #0000BB">$client</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">demo</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">beers</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$result </span><span style="color: #007700">= </span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insertOne</span><span style="color: #007700">( [ </span><span style="color: #DD0000">'name' </span><span style="color: #007700">=&gt; </span><span style="color: #DD0000">'Hinterland'</span><span style="color: #007700">, </span><span style="color: #DD0000">'brewery' </span><span style="color: #007700">=&gt; </span><span style="color: #DD0000">'BrewDog' </span><span style="color: #007700">] );<br /><br />echo </span><span style="color: #DD0000">"Inserted with Object ID '</span><span style="color: #007700">{</span><span style="color: #0000BB">$result</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">getInsertedId</span><span style="color: #007700">()}</span><span style="color: #DD0000">'"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?&gt;</span></span></code></div>
    </div>

   </p>

   <p class="para">
    Since the inserted document did not contain an <code class="code">_id</code> field, the
    extension will generate an <span class="classname"><a href="class.mongodb-bson-objectid.php" class="classname">MongoDB\BSON\ObjectId</a></span> for
    the server to use as the <code class="code">_id</code>. This value is also made available
    to the caller via the result object returned by the <code class="code">insertOne</code>
    method.
   </p>

   <p class="para">
    After insertion, you can query for the data that you have just inserted.
    For that, you use the <code class="code">find</code> method, which returns an iterable
    cursor:
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000"><span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">require </span><span style="color: #DD0000">'vendor/autoload.php'</span><span style="color: #007700">; </span><span style="color: #FF8000">// include Composer's autoloader<br /><br /></span><span style="color: #0000BB">$client </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoDB\Client</span><span style="color: #007700">(</span><span style="color: #DD0000">"mongodb://localhost:27017"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$collection </span><span style="color: #007700">= </span><span style="color: #0000BB">$client</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">demo</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">beers</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$result </span><span style="color: #007700">= </span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">find</span><span style="color: #007700">( [ </span><span style="color: #DD0000">'name' </span><span style="color: #007700">=&gt; </span><span style="color: #DD0000">'Hinterland'</span><span style="color: #007700">, </span><span style="color: #DD0000">'brewery' </span><span style="color: #007700">=&gt; </span><span style="color: #DD0000">'BrewDog' </span><span style="color: #007700">] );<br /><br />foreach (</span><span style="color: #0000BB">$result </span><span style="color: #007700">as </span><span style="color: #0000BB">$entry</span><span style="color: #007700">) {<br />    echo </span><span style="color: #0000BB">$entry</span><span style="color: #007700">[</span><span style="color: #DD0000">'_id'</span><span style="color: #007700">], </span><span style="color: #DD0000">': '</span><span style="color: #007700">, </span><span style="color: #0000BB">$entry</span><span style="color: #007700">[</span><span style="color: #DD0000">'name'</span><span style="color: #007700">], </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?&gt;</span></span></code></div>
    </div>

   </p>

   <p class="para">
    While it may not be apparent in the examples, BSON documents and arrays are
    unserialized as special classes in the library by default. These classes
    extend <span class="classname"><a href="class.arrayobject.php" class="classname">ArrayObject</a></span> for usability and implement the
    extension&#039;s <span class="interfacename"><a href="class.mongodb-bson-serializable.php" class="interfacename">MongoDB\BSON\Serializable</a></span> and
    <span class="interfacename"><a href="class.mongodb-bson-unserializable.php" class="interfacename">MongoDB\BSON\Unserializable</a></span> interfaces to
    ensure that values preserve their type when serialized back into BSON. This
    avoids a caveat in the legacy <code class="code">mongo</code> extension where arrays
    might turn into documents, and vice versa. See the
    <a href="mongodb.persistence.php" class="xref">Persisting Data</a> specification for more information on
    how values are converted between PHP and BSON.
   </p>
  </div>
</div><?php manual_footer($setup); ?>