sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Document _id generation in MongoCollection insert/save methods

Browse source 
https://jira.mongodb.org/browse/PHP-383


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@329040 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Jeremy Mikola 2013-01-08 23:01:23 +00:00
parent 2a331a3820
commit 6f59b9c6a9
3 changed files with 94 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
reference/mongo/mongocollection/batchinsert.xml
View file

@ -26,8 +26,17 @@
</term>
<listitem>
<para>
An array of arrays.
An array of arrays or objects. If any objects are used, they may not have
protected or private properties.
</para>
<note>
<para>
If the documents to insert do not have an <literal>_id</literal> key or
property, a new <classname>MongoId</classname> instance will be created
and assigned to it. See <function>MongoCollection::insert</function> for
additional information on this behavior.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
@ -76,6 +85,11 @@
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoException</classname> if any inserted documents are
empty or if they contains zero-length keys. Attempting to insert an object
with protected and private properties will cause a zero-length key error.
</para>
&mongo.errors.exceptions.writeconcern;
</refsect1>

75
reference/mongo/mongocollection/insert.xml
View file

@ -4,14 +4,14 @@
<refentry xml:id="mongocollection.insert" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::insert</refname>
<refpurpose>Inserts an array into the collection</refpurpose>
<refpurpose>Inserts a document into the collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool|array</type><methodname>MongoCollection::insert</methodname>
<methodparam><type>array</type><parameter>a</parameter></methodparam>
<methodparam><type>array|object</type><parameter>a</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
</methodsynopsis>
<para>
@ -31,8 +31,17 @@
</term>
<listitem>
<para>
An array.
An array or object. If an object is used, it may not have protected or
private properties.
</para>
<note>
<para>
If the parameter does not have an <literal>_id</literal> key or
property, a new <classname>MongoId</classname> instance will be created
and assigned to it. This special behavior does not mean that the
parameter is passed by reference.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
@ -188,7 +197,9 @@
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoException</classname> if the inserted array is empty.
Throws <classname>MongoException</classname> if the inserted document is
empty or if it contains zero-length keys. Attempting to insert an object with
protected and private properties will cause a zero-length key error.
</para>
&mongo.errors.exceptions.writeconcern;
</refsect1>
@ -265,27 +276,54 @@
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::insert</function> _id example</title>
<title><function>MongoCollection::insert</function> <literal>_id</literal> example</title>
<para>
Inserting an object will add an _id field to it, unless it is passed by reference.
An <literal>_id</literal> field will be added to the inserted document if
not already present. Depending on how the parameter is passed, a generated
<literal>_id</literal> may or may not be available to calling code.
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');
$collection = $m->selectCollection('test', 'phpmanual');
$a = array('x' => 12);
// If an array literal is used, there is no way to access the generated _id
$collection->insert(array('x' => 1));
// The _id is available on an array passed by value
$a = array('x' => 2);
$collection->insert($a);
var_dump($a);
$b = array('x' => 12);
// The _id is not available on an array passed by reference
$b = array('x' => 3);
$ref = &$b;
$collection->insert($ref);
var_dump($ref);
// The _id is available if a wrapping function does not trigger copy-on-write
function insert_no_cow($collection, $document)
{
$collection->insert($document);
}
$c = array('x' => 4);
insert_no_cow($collection, $c);
var_dump($c);
// The _id is not available if a wrapping function triggers copy-on-write
function insert_cow($collection, $document)
{
$document['y'] = 1;
$collection->insert($document);
}
$d = array('x' => 5);
insert_cow($collection, $d);
var_dump($d);
?>
]]>
</programlisting>
@ -294,14 +332,25 @@ var_dump($ref);
<![CDATA[
array(2) {
["x"]=>
int(12)
int(2)
["_id"]=>
object(MongoId)#4 (0) {
}
}
array(12) {
array(1) {
["x"]=>
int(1)
int(3)
}
array(2) {
["x"]=>
int(4)
["_id"]=>
object(MongoId)#5 (0) {
}
}
array(1) {
["x"]=>
int(5)
}
]]>
</screen>

31
reference/mongo/mongocollection/save.xml
View file

@ -4,14 +4,14 @@
<refentry xml:id="mongocollection.save" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::save</refname>
<refpurpose>Saves an object to this collection</refpurpose>
<refpurpose>Saves a document to this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>mixed</type><methodname>MongoCollection::save</methodname>
<methodparam><type>array</type><parameter>a</parameter></methodparam>
<methodparam><type>array|object</type><parameter>a</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
</methodsynopsis>
<para>
@ -30,8 +30,17 @@
</term>
<listitem>
<para>
Array to save.
Array or object to save. If an object is used, it may not have protected
or private properties.
</para>
<note>
<para>
If the parameter does not have an <literal>_id</literal> key or
property, a new <classname>MongoId</classname> instance will be created
and assigned to it. See <function>MongoCollection::insert</function> for
additional information on this behavior.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
@ -65,6 +74,11 @@
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoException</classname> if the inserted document is
empty or if it contains zero-length keys. Attempting to insert an object with
protected and private properties will cause a zero-length key error.
</para>
&mongo.errors.exceptions.writeconcern;
</refsect1>
@ -155,17 +169,6 @@ array(2) {
</example>
</refsect1>
<refsect1 role="notes"><!-- {{{ -->
&reftitle.notes;
<note>
<para>
This method will create an <literal>_id</literal> field in the
<parameter>a</parameter> array with a pregenerated ID if the field didn't
exist already - unless the argument was a reference.
</para>
</note>
</refsect1><!-- }}} -->
</refentry>
<!-- Keep this comment at the end of the file
Local variables: