<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision: 331063 $ -->
<refentry xml:id="mongodb.createcollection" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoDB::createCollection</refname>
  <refpurpose>Creates a collection</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>MongoCollection</type><methodname>MongoDB::createCollection</methodname>
   <methodparam><type>string</type><parameter>name</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
  </methodsynopsis>
  
  <para>
   This method is used to create capped collections and other collections 
   requiring special options.  It is identical to running:
   <programlisting role="php">
<![CDATA[
<?php

$collection = $db->command(array(
    "create" => $name,
    "capped" => $options["capped"],
    "size" => $options["size"],
    "max" => $options["max"],
    "autoIndexId" => $options["autoIndexId"],
));

?>
]]>
   </programlisting>
   See <function>MongoDB::command</function> for more information about database commands.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;

  <para>
   <variablelist>
    <varlistentry>
     <term>
      <parameter>name</parameter>
     </term>
     <listitem>
      <para>
       The name of the collection.
      </para>
     </listitem>
    </varlistentry>   

    <varlistentry>
     <term>
      <parameter>options</parameter>
     </term>
     <listitem>
      <para>
       An array containing options for the collections. Each option is its own
       element in the options array, with the option name listed below being
       the key of the element. The supported options depend on the MongoDB
       server version. At the moment, the following options are supported:
      </para>
      <para>
       <variablelist>
        <varlistentry>
         <term>
          <parameter>capped</parameter>
         </term>
         <listitem>
          <para>
           If the collection should be a fixed size.
          </para>
         </listitem>
        </varlistentry>   
        <varlistentry>
         <term>
          <parameter>size</parameter>
         </term>
         <listitem>
          <para>
           If the collection is fixed size, its size in bytes.
          </para>
         </listitem>
        </varlistentry>   
        <varlistentry>
         <term>
          <parameter>max</parameter>
         </term>
         <listitem>
          <para>
           If the collection is fixed size, the maximum number of elements to
           store in the collection.
          </para>
         </listitem>
        </varlistentry>   
        <varlistentry>
         <term>
          <parameter>autoIndexId</parameter>
         </term>
         <listitem>
          <para>
           If capped is &true; you can specify &false; to disable the
           automatic index created on the <literal>_id</literal> field.
           Before MongoDB 2.2, the default value for
           <literal>autoIndexId</literal> was &false;.
          </para>
         </listitem>
        </varlistentry>   
       </variablelist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns a collection object representing the new collection.
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><function>MongoDB::createCollection</function> capped collection example</title>
   <para>
    A capped collection is a special type of collection that has either a fixed
    or a fixed number of elements. Once the collection is "full," the oldest
    elements will be removed when new elements are added.  Capped collections
    can be very useful for applications like logging, where you may want to
    reserve a certain amount of space for logs and not worry about them
    getting too big.
   </para>
   <para>
    This example creates a very tiny log collection that will keep a maximum of
    10 documents.
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$log = $db->createCollection(
    "logger",
    array(
        'capped' => true,
        'size' => 10*1024,
        'max' => 10
    )
);

for ($i = 0; $i < 100; $i++) {
    $log->insert(array("level" => WARN, "msg" => "sample log message #$i", "ts" => new MongoDate()));
}

$msgs = $log->find();

foreach ($msgs as $msg) {
    echo $msg['msg']."\n";
}

?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
sample log message #90
sample log message #91
sample log message #92
sample log message #93
sample log message #94
sample log message #95
sample log message #96
sample log message #97
sample log message #98
sample log message #99
   </screen>
  </example>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>1.4.0</entry>
       <entry>
        <para>
         In versions before 1.4.0, the options were all arguments to the method. The
         function synopsis in those older versions is:
        </para>
        <para>
         <methodsynopsis>
          <modifier>public</modifier> <type>MongoCollection</type><methodname>MongoDB::createCollection</methodname>
          <methodparam><type>string</type><parameter>name</parameter></methodparam>
          <methodparam choice="opt"><type>bool</type><parameter>capped</parameter><initializer>&false;</initializer></methodparam>
          <methodparam choice="opt"><type>int</type><parameter>size</parameter><initializer>0</initializer></methodparam>
          <methodparam choice="opt"><type>int</type><parameter>max</parameter><initializer>0</initializer></methodparam>
         </methodsynopsis>
        </para>
        <para>
         The meaning of the options is the same as described under the
         <parameter>options</parameter> argument above.
        </para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->