[prev in list] [next in list] [prev in thread] [next in thread]
List: php-doc-cvs
Subject: [DOC-CVS] =?utf-8?q?svn:_/phpdoc/_doc-base/trunk/entities/global.ent_doc-base/trunk/scripts/gen-phpd
From: Derick_Rethans <derick () php ! net>
Date: 2015-11-16 12:29:43
Message-ID: svn-derick-1447676983-338133-646319158 () svn ! php ! net
[Download RAW message or body]
derick Mon, 16 Nov 2015 12:29:43 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=338133
Log:
Added architecture overview article.
Changed paths:
U phpdoc/doc-base/trunk/entities/global.ent
U phpdoc/doc-base/trunk/scripts/gen-phpdoc-tz-list.php
U phpdoc/en/trunk/language-snippets.ent
A + phpdoc/en/trunk/reference/mongodb/architecture.xml
(from phpdoc/en/trunk/reference/mongodb/persistence.xml:r338132)
A phpdoc/en/trunk/reference/mongodb/images/
A phpdoc/en/trunk/reference/mongodb/images/driver_arch.png
D phpdoc/en/trunk/reference/mongodb/persistence.xml
U phpdoc/en/trunk/reference/mongodb/set.xml
["svn-diffs-338133.txt" (text/x-diff)]
Modified: phpdoc/doc-base/trunk/entities/global.ent
===================================================================
--- phpdoc/doc-base/trunk/entities/global.ent 2015-11-16 06:00:10 UTC (rev 338132)
+++ phpdoc/doc-base/trunk/entities/global.ent 2015-11-16 12:29:43 UTC (rev 338133)
@@ -306,6 +306,10 @@
<!ENTITY url.mongodb.library.apidocs \
"http://mongodb.github.io/mongo-php-library/api"> <!ENTITY url.mongodb.libmongoc \
"http://github.com/mongodb/mongo-c-driver"> <!ENTITY url.mongodb.glossary \
"https://docs.mongodb.org/manual/reference/glossary/"> +<!ENTITY url.mongodb.doctrine \
"https://github.com/doctrine/mongodb"> +<!ENTITY url.mongodb.doctrine-odm \
"https://github.com/doctrine/mongodb-odm"> +<!ENTITY url.mongodb.drivers \
"http://docs.mongodb.org/ecosystem/drivers/"> +<!ENTITY url.mongodb.specs \
"https://github.com/mongodb/specifications"> <!ENTITY url.mongodb.crud \
"https://github.com/mongodb/specifications/blob/master/source/crud/crud.rst"> \
<!ENTITY url.mongodb.serverselection \
"https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst">
<!ENTITY url.mongodb.sdam \
"https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst">
@@ -365,12 +369,18 @@
<!ENTITY url.mongodb.docs.operator.meta.snapshot \
"http://docs.mongodb.org/manual/reference/operator/meta/snapshot/"> <!ENTITY \
url.mongodb.examples.zipcode "http://media.mongodb.org/zips.json"> <!ENTITY \
url.mongodb.github "http://github.com/mongodb/mongo-php-driver-legacy"> +<!ENTITY \
url.mongodb.github.phpc "http://github.com/mongodb/mongo-php-driver"> +<!ENTITY \
url.mongodb.github.phplib "http://github.com/mongodb/mongo-php-library"> +<!ENTITY \
url.mongodb.github.hhvm "http://github.com/mongodb/mongo-hhvm-driver"> <!ENTITY \
url.mongodb.gridfs.fileupload "http://www.lightcubesolutions.com/blog/?p=209"> \
<!ENTITY url.mongodb.gridfs.metadata "http://www.lightcubesolutions.com/blog/?p=228"> \
<!ENTITY url.mongodb.injection \
"http://www.idontplaydarts.com/2010/07/mongodb-is-vulnerable-to-sql-injection-in-php-at-least/">
<!ENTITY url.mongodb.install.osx.homebrew \
"http://justinhileman.info/article/reinstalling-php-on-mac-os-x/"> <!ENTITY \
url.mongodb.install.ubuntu.9.10.video "http://www.vimeo.com/8005503"> <!ENTITY \
url.mongodb.jira "http://jira.mongodb.org/browse/PHP"> +<!ENTITY \
url.mongodb.jira.phpc "http://jira.mongodb.org/browse/PHPC"> +<!ENTITY \
url.mongodb.jira.phplib "http://jira.mongodb.org/browse/PHPLIB"> +<!ENTITY \
url.mongodb.jira.hhvm "http://jira.mongodb.org/browse/HHVM"> <!ENTITY \
url.mongodb.mailinglist "http://groups.google.com/group/mongodb-user/"> <!ENTITY \
url.mongodb.osx "http://technosophos.com/content/os-x-installing-mongodb-and-php-mongo-driver">
<!ENTITY url.mongodb.php "http://www.mongodb.org/display/DOCS/PHP+Language+Center">
Modified: phpdoc/doc-base/trunk/scripts/gen-phpdoc-tz-list.php
===================================================================
--- phpdoc/doc-base/trunk/scripts/gen-phpdoc-tz-list.php 2015-11-16 06:00:10 UTC (rev \
338132)
+++ phpdoc/doc-base/trunk/scripts/gen-phpdoc-tz-list.php 2015-11-16 12:29:43 UTC (rev \
338133) @@ -1,4 +1,5 @@
<?php
+ $columns = 4;
$groupedList = array();
$aliasList = array(
'Brazil' => 'Others',
@@ -46,7 +47,7 @@
}
foreach ($groupedList as $group => $zones) {
- $m = count($zones) > 4 ? 5 : count($zones); ?>
+ $m = count($zones) > ($columns-1) ? $columns : count($zones); ?>
<sect1 xml:id="timezones.<?php echo strtolower($group); ?>">
<title><?php echo '&date.timezone.' . strtolower($group) . ';'; ?></title>
Modified: phpdoc/en/trunk/language-snippets.ent
===================================================================
--- phpdoc/en/trunk/language-snippets.ent 2015-11-16 06:00:10 UTC (rev 338132)
+++ phpdoc/en/trunk/language-snippets.ent 2015-11-16 12:29:43 UTC (rev 338133)
@@ -1887,6 +1887,12 @@
<!ENTITY mongo.context.server ' <varlistentry xmlns="http://docbook.org/ns/docbook"> \
<term> <parameter>server</parameter> </term> <listitem> <para> An array containing \
the basic information about the server that was picked. <informaltable> <tgroup \
cols="2"> <thead> <row> <entry>key</entry> <entry>value</entry> </row> </thead> \
<tbody> <row> <entry>hash</entry> <entry>server hash, example: \
<literal>localhost:27017;-;X;56052</literal></entry> </row> <row> <entry>type</entry> \
<entry>Node type (primary/secondary/mongos/arbiter): <literal>2</literal></entry> \
</row> <row> <entry>max_bson_size</entry> <entry>The maximum BSON Size over the wire \
this node accepts: <literal>16777216</literal></entry> </row> <row> \
<entry>max_message_size</entry> <entry>The maximum Message Size over the wire this \
node accepts: <literal>48000000</literal></entry> </row> <row> \
<entry>request_id</entry> <entry>The request identifier for this message: \
<literal>42</literal></entry> </row> </tbody> </tgroup> </informaltable> </para> \
</listitem> </varlistentry>'> <!ENTITY mongo.context.writeoptions '<varlistentry \
xmlns="http://docbook.org/ns/docbook"> <term> <parameter>writeOptions</parameter> \
</term> <listitem> <para> <informaltable> <tgroup cols="2"> <thead> <row> \
<entry>key</entry> <entry>value</entry> </row> </thead> <tbody> <row> \
<entry>ordered</entry> <entry>boolean, if the operation (in case of batch operation) \
must be executed sequentually (ordered=true)</entry> </row> <row> \
<entry>writeConcern</entry> <entry>An array of writeConcern options (see \
below)</entry> </row> </tbody> </tgroup> </informaltable> <table> <title>writeConcern \
array values</title> <tgroup cols="2"> <thead> <row> <entry>key</entry> \
<entry>value</entry> </row> </thead> <tbody> <row> <entry>fsync</entry> \
<entry>boolean, force flushing to disk before returning</entry> </row> <row> \
<entry>j</entry> <entry>boolean, force journal write before returning</entry> </row> \
<row> <entry>wtimeout</entry> <entry>integer, milliseconds, maximum time the primary \
is allowed to wait to verify replication</entry> </row> <row> <entry>w</entry> \
<entry>integer=server count, or string=replication-tag</entry> </row> </tbody> \
</tgroup> </table> </para> </listitem> </varlistentry>'> <!ENTITY \
mongo.context.protocoloptions ' <varlistentry xmlns="http://docbook.org/ns/docbook"> \
<term> <parameter>protocolOptions</parameter> </term> <listitem> <para> \
<informaltable> <tgroup cols="2"> <thead> <row> <entry>key</entry> \
<entry>value</entry> </row> </thead> <tbody> <row> <entry>message_length</entry> \
<entry>The total size (in bytes) of the encoded message being sent over the \
wire</entry> </row> <row> <entry>request_id</entry> <entry>The request identifier for \
this message: <literal>42</literal></entry> </row> <row> <entry>namespace</entry> \
<entry>The MongoDB namespace used for the protocol message \
<literal>dbname.collectionname</literal></entry> </row> </tbody> </tgroup> \
</informaltable> </para> </listitem> </varlistentry>'> +<!ENTITY \
mongo.alternative.note '<para +xmlns="http://docbook.org/ns/docbook">This extension \
is deprecated. +Instead, the <link linkend="set.mongodb">MongoDB</link> extension \
should be used. +See also <link linkend="mongodb.architecture">Driver \
Architecture</link>. +Alternatives to this function include:</para>'>
+
<!-- mongodb -->
<!ENTITY mongodb.parameter.namespace '
<varlistentry xmlns="http://docbook.org/ns/docbook">
@@ -2005,7 +2011,7 @@
</para>
</note>
'>
-
+
<!-- Radius -->
<!ENTITY radius.request.required '<note \
xmlns="http://docbook.org/ns/docbook"><para>A request must be created via \
<function>radius_create_request</function> before this function can be \
called.</para></note>'>
Copied: phpdoc/en/trunk/reference/mongodb/architecture.xml (from rev 338132, \
phpdoc/en/trunk/reference/mongodb/persistence.xml) \
===================================================================
--- phpdoc/en/trunk/reference/mongodb/architecture.xml (rev \
0)
+++ phpdoc/en/trunk/reference/mongodb/architecture.xml 2015-11-16 12:29:43 UTC (rev \
338133) @@ -0,0 +1,752 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 337115 $ -->
+
+<book xml:id="mongodb.architecture" xmlns="http://docbook.org/ns/docbook" \
xmlns:xlink="http://www.w3.org/1999/xlink"> + <titleabbrev>Driver Architecture and \
Internals</titleabbrev> + <title>Explains the driver architecure, and special \
features</title> +
+ <article xml:id="mongodb.overview">
+ <titleabbrev>Architecture</titleabbrev>
+ <title>Architecture Overview</title>
+
+ <para>
+ This section explains how all the different parts of the driver fit
+ together. From the different language runtimes, through the extensions and
+ to the PHP libraries on top. This new architecture has replaced the old
+ <link linkend="book.mongo">mongo</link> extension. We refer to the new one
+ as the <emphasis>mongodb</emphasis> extension.
+ </para>
+ <para>
+ <mediaobject>
+ <alt>Architecture Diagram</alt>
+ <imageobject>
+ <imagedata fileref="en/reference/mongodb/images/driver_arch.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>
+ At the top of this stack sits a pure
+ <link xlink:href="&url.mongodb.library;">PHP library</link>, which we will
+ distribute as a Composer package. This library will provide an API similar
+ to what users have come to expect from the old mongo driver (e.g. CRUD methods,
+ database and collection objects, command helpers) and we expect it to be a
+ common dependency for most applications built with MongoDB. This library
+ will also implement common
+ <link xlink:href="&url.mongodb.specs;">specifications</link>, in the
+ interest of improving API consistency across all of the
+ <link xlink:href="&url.mongodb.drivers;">drivers</link> maintained by
+ MongoDB (and hopefully some community drivers, too).
+ </para>
+ <para>
+ Sitting below that library we have the lower level drivers—one per platform.
+ These extensions will effectively form the glue between PHP and HHVM and our
+ system libraries (<link xlink:href="&url.mongodb.libmongoc;">libmongoc</link> and
+ <link xlink:href="&url.mongodb.libbson;">libbson</link>). These extensions
+ will expose an identical public API for the most essential and
+ performance-sensitive functionality:
+
+ <simplelist>
+ <member>Connection management</member>
+ <member>BSON encoding and decoding</member>
+ <member>Object document serialization (to support ODM libraries)</member>
+ <member>Executing commands and write operations</member>
+ <member>Handling queries and cursors</member>
+ </simplelist>
+ </para>
+
+ <para>
+ By decoupling the driver internals and a high-level API into extensions and
+ PHP libraries, respectively, we hope to reduce our maintainence burden and
+ allow for faster iteration on new features. As a welcome side effect, this
+ also makes it easier for anyone to contribute to the driver. Additionally,
+ an identical public API for these extensions will make it that much easier
+ to port an application across PHP runtimes, whether the application uses
+ the low-level driver directly or a higher-level PHP library.
+ </para>
+ <para>
+ <link xlink:href="&url.mongodb.docs.gridfs;">GridFS</link> is a great example
+ of why we chose this direction.
+ Although we implemented GridFS in C for our old mongo driver, it is actually
+ quite a high-level specification. Its API is just an abstraction for
+ accessing two collections: files (i.e. metadata) and chunks (i.e. blocks of
+ data). Likewise, all of the syntactic sugar found in the old mongo driver,
+ such as processing uploaded files or exposing GridFS files as PHP streams,
+ can be implemented in pure PHP. Provided we have performant methods for
+ reading from and writing to GridFS' collections – and thanks to our low
+ level extensions, we will – shifting this API to PHP is win-win.
+ </para>
+ <para>
+ Earlier I mentioned that we expect the PHP library to be a common
+ dependency for <emphasis>most</emphasis> applications, but not
+ <emphasis>all</emphasis>. Some users may prefer to stick to the no-frills
+ API offered by the extensions, or create their own high-level abstraction
+ (akin to <link xlink:href="&url.mongodb.doctrine;">Doctrine MongoDB</link> for
+ the old mongo driver). Future libraries could include a PHP library geared
+ for MongoDB administration, which provides an API for various user
+ management and ops commands. The next major version of
+ <link xlink:href="&url.mongodb.doctrine-odm;">Doctrine MongoDB ODM</link> will
+ likely also sit directly atop the extensions.
+ </para>
+ <para>
+ While we will continue to maintain and support the old mongo driver and its
+ users for the foreseeable future, we invite everyone to use the
+ next-generation driver and consider it for any new projects going forward.
+ You can find all of the essential components across GitHub and JIRA:
+
+ <table>
+ <title>Driver Source Code and JIRA Locations</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Project</entry>
+ <entry>GitHub</entry>
+ <entry>JIRA</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>PHP Library</entry>
+ <entry><link \
xlink:href="&url.mongodb.github.phplib;">mongodb/mongo-php-library</link></entry> + \
<entry><link xlink:href="&url.mongodb.jira.phplib;">PHPLIB</link></entry> + \
</row> + <row>
+ <entry>PHP 5 and PHP 7 Driver (phongo)</entry>
+ <entry><link \
xlink:href="&url.mongodb.github.phpc;">mongodb/mongo-php-driver</link></entry> + \
<entry><link xlink:href="&url.mongodb.jira.phpc;">PHPC</link></entry> + </row>
+ <row>
+ <entry>HHVM Driver (hippo)</entry>
+ <entry><link \
xlink:href="&url.mongodb.github.hhvm;">mongodb/mongo-hhvm-driver</link></entry> + \
<entry><link xlink:href="&url.mongodb.jira.hhvm;">HHVM</link></entry> + </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ <para>
+ The existing <link xlink:href="&url.mongodb.jira;">PHP</link> project in JIRA
+ will remain open for reporting bugs against the old mongo driver, but we
+ would ask that you use the new projects above for anything pertaining to
+ our next-generation drivers.
+ </para>
+ </article>
+
+ <article xml:id="mongodb.persistence">
+ <titleabbrev>Persisting Data</titleabbrev>
+ <title>Serialisation and deserialisation of PHP variables into MongoDB</title>
+
+ <para>
+ This document discusses the methods how compound structures (documents,
+ arrays, objects) are persisted through the drivers. And how they are brought
+ back into PHP land.
+ </para>
+
+ <section>
+ <title>Serialisation to BSON</title>
+
+ <section>
+ <title>Arrays</title>
+
+ <para>
+ If an array is a <emphasis>packed array</emphasis> — i.e. the keys start
+ at 0 and are sequential without gaps: <emphasis>BSON array</emphasis>.
+ </para>
+
+ <para>
+ If the array is not packed — i.e. having associative (string) keys, the
+ keys don't start at 0, or when there are gaps:: <emphasis>BSON
+ object</emphasis>
+ </para>
+
+ <para>
+ A top-level (root) document, <emphasis>always</emphasis> serializes as a
+ BSON document.
+ </para>
+
+ <section>
+ <title>Examples</title>
+
+ <para>
+ These serialize as a BSON array:
+ </para>
+
+ <programlisting>
+[ 8, 5, 2, 3 ] => [ 8, 5, 2, 3 ]
+[ 0 => 4, 1 => 9 ] => [ 4, 9 ]
+ </programlisting>
+
+ <para>
+ These serialize as a BSON document:
+ </para>
+
+ <programlisting>
+[ 0 => 1, 2 => 8, 3 => 12 ] => { "0" : 1, "2" : 8, "3" : 12 }
+[ "foo" => 42 ] => { "foo" : 42 }
+[ 1 => 9, 0 => 10 ] => { "1" : 9, "0" : 10 }
+ </programlisting>
+
+ <para>
+ Note that the five examples are <emphasis>extracts</emphasis> of a full
+ document, and represent only <emphasis>one</emphasis> value inside a
+ document.
+ </para>
+
+ </section>
+ </section>
+
+ <section>
+ <title>Objects</title>
+
+ <para>
+ If an object is of the <classname>stdClass</classname> class, serialize
+ as a <emphasis>BSON document</emphasis>.
+ </para>
+
+ <para>
+ If an object is a supported class that implements
+ <classname>MongoDB\BSON\Type</classname>, then use the BSON
+ serialization logic for that specific type.
+ <classname>MongoDB\BSON\Type</classname> instances (excluding
+ <classname>MongoDB\BSON\Serializable</classname> may only be serialized
+ as a document field value. Attempting to serialize such an object as a
+ root document will throw a
+ <classname>MongoDB\Driver\Exception\UnexpectedValueException</classname>
+ </para>
+
+ <para>
+ If an object is of an unknown class implementing the
+ <classname>MongoDB\BSON\Type</classname> interface, then throw a
+ <classname>MongoDB\Driver\Exception\UnexpectedValueException</classname>
+ </para>
+
+ <para>
+ If an object is of any other class, without implementing any special
+ interface, serialize as a <emphasis>BSON document</emphasis>. Keep only
+ <emphasis>public</emphasis> properties, and ignore
+ <emphasis>protected</emphasis> and <emphasis>private</emphasis>
+ properties.
+ </para>
+
+ <para>
+ If an object is of a class that implements the
+ <classname>MongoDB\BSON\Serializable</classname> interface, call
+ <methodname>bsonSerialize</methodname> and use the returned array or
+ <classname>stdClass</classname> to serialize as a BSON document or
+ array. The BSON type will be determined by the following:
+ </para>
+
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>Root documents must be serialized as a BSON
+ document.
+ </para>
+ </listitem>
+ <listitem>
+ <para><classname>MongoDB\BSON\Persistable</classname> objects must be
+ serialized as a BSON document.
+ </para>
+ </listitem>
+ <listitem>
+ <para>If <methodname>bsonSerialize</methodname> returns a packed
+ array, serialize as a BSON array.
+ </para>
+ </listitem>
+ <listitem>
+ <para>If <methodname>bsonSerialize</methodname> returns a non-packed
+ array or <classname>stdClass</classname>, serialize as a BSON
+ document.
+ </para>
+ </listitem>
+ <listitem>
+ <para>If <methodname>bsonSerialize</methodname> did not return an
+ array or <classname>stdClass</classname>, throw an
+ <classname>MongoDB\Driver\Exception\UnexpectedValueException</classname>
+ exception.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ If an object is of a class that implements the
+ <classname>MongoDB\BSON\Persistable</classname> interface (which implies
+ <classname>MongoDB\BSON\Serializable</classname> obtain the properties
+ in a similar way as in the previous paragraphs, but
+ <emphasis>also</emphasis> add an additional property
+ <property>__pclass</property> as a Binary value, with subtype
+ <literal>0x80</literal> and data bearing the fully qualified class name
+ of the object that is being serialized.
+ </para>
+
+ <para>
+ The <property>__pclass</property> property is added to the array or
+ object returned by <methodname>bsonSerialize</methodname>, which means
+ it will overwrite any <property>__pclass</property> key/property in the
+ <methodname>bsonSerialize</methodname> return value. If you want to
+ avoid this behaviour and set your own <property>__pclass</property>
+ value, you must <emphasis>not</emphasis> implement
+ <classname>MongoDB\BSON\Persistable</classname> and should instead
+ implement <classname>MongoDB\BSON\Serializable</classname> directly.
+ </para>
+
+ <section>
+ <title>Examples</title>
+
+ <programlisting>
+stdClass {
+ public $foo = 42;
+} => { "foo" : 42 }
+
+MyClass {
+ public $foo = 42;
+ protected $prot = "wine";
+ private $fpr = "cheese";
+} => { "foo" : 42 }
+
+AnotherClass1 implements MongoDB\BSON\Serializable {
+ public $foo = 42;
+ protected $prot = "wine";
+ private $fpr = "cheese";
+ function bsonSerialize() {
+ return [ 'foo' => $this->foo, 'prot' => $this->prot ];
+ }
+} => { "foo" : 42, "prot" : "wine" }
+
+AnotherClass2 implements MongoDB\BSON\Serializable {
+ public $foo = 42;
+ function bsonSerialize() {
+ return $this;
+ }
+} => MongoDB\Driver\Exception\UnexpectedValueException("bsonSerialize() did not \
return an array or stdClass") +
+AnotherClass3 implements MongoDB\BSON\Serializable {
+ private $elements = [ 'foo', 'bar' ];
+ function bsonSerialize() {
+ return $this->elements;
+ }
+} => { "0" : "foo", "1" : "bar" }
+
+ContainerClass implements MongoDB\BSON\Serializable {
+ public $things = AnotherClass4 implements MongoDB\BSON\Serializable {
+ private $elements = [ 0 => 'foo', 2 => 'bar' ];
+ function bsonSerialize() {
+ return $this->elements;
+ }
+ }
+ function bsonSerialize() {
+ return [ 'things' => $this->things ];
+ }
+} => { "things" : { "0" : "foo", "2" : "bar" } }
+
+ContainerClass implements MongoDB\BSON\Serializable {
+ public $things = AnotherClass5 implements MongoDB\BSON\Serializable {
+ private $elements = [ 0 => 'foo', 2 => 'bar' ];
+ function bsonSerialize() {
+ return array_values($this->elements);
+ }
+ }
+ function bsonSerialize() {
+ return [ 'things' => $this->things ];
+ }
+} => { "things" : [ "foo", "bar" ] }
+
+ContainerClass implements MongoDB\BSON\Serializable {
+ public $things = AnotherClass6 implements MongoDB\BSON\Serializable {
+ private $elements = [ 'foo', 'bar' ];
+ function bsonSerialize() {
+ return (object) $this->elements;
+ }
+ }
+ function bsonSerialize() {
+ return [ 'things' => $this->things ];
+ }
+} => { "things" : { "0" : "foo", "1" : "bar" } }
+
+UpperClass implements MongoDB\BSON\Persistable {
+ public $foo = 42;
+ protected $prot = "wine";
+ private $fpr = "cheese";
+ function bsonSerialize() {
+ return [ 'foo' => $this->foo, 'prot' => $this->prot ];
+ }
+} => { "foo" : 42, "prot" : "wine", "__pclass" : { "$type" : "80", "$binary" : \
"VXBwZXJDbGFzcw==" } } + </programlisting>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Deserialization from BSON</title>
+
+ <para>
+ For compound types, there are three data types:
+ </para>
+
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>root</term>
+ <listitem>
+ <para>
+ refers to the top-level BSON document <emphasis>only</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>document</term>
+ <listitem>
+ <para>
+ refers to embedded BSON documents <emphasis>only</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>array</term>
+ <listitem>
+ <para>
+ refers to a BSON array
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ Each of those three data types can be mapped against different PHP types.
+ The possible mapping values are:
+ </para>
+
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>not set</emphasis> or <type>NULL</type> (the is the
+ default)</term>
+ <listitem>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ A BSON array will be deserialized as a PHP <type>array</type>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A BSON document (root or embedded) without a
+ <property>__pclass</property> property
+ <footnote xml:id="mongodb.pclass">
+ <para>
+ A __pclass property is only deemed to exist if
+ there exists a property with that name, and it is a Binary value,
+ and the sub-type of the Binary value is 0x80. If any of these three
+ conditions is not met, the __pclass property does not exist and
+ should be treated as any other normal property.
+ </para>
+ </footnote>
+ becomes a PHP <classname>stdClass</classname> object, with each
+ BSON document key set as a public <classname>stdClass</classname>
+ property.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A BSON document (root or embedded) with a
+ <property>__pclass</property> property <footnoteref \
linkend="mongodb.pclass"/> becomes a PHP object of + the class name as \
defined by the <property>__pclass</property> + property.
+ </para>
+ <para>
+ If the named class implements the
+ <classname>MongoDB\BSON\Persistable</classname> interface, then the
+ properties of the BSON document, including the
+ <property>__pclass</property> property, are sent as an associative
+ array to the <methodname>bsonUnserialize</methodname> function to
+ initialise the object's properties.
+ </para>
+ <para>
+ If the named class does not exist or does not implement the
+ <classname>MongoDB\BSON\Persistable</classname> interface,
+ <classname>stdClass</classname> will be used and each BSON document
+ key (including <property>__pclass</property>) will be set as a
+ public <classname>stdClass</classname> property.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>"array"</literal></term>
+ <listitem>
+ <para>
+ Turns a BSON array or BSON document into a PHP array. There will be no
+ special treatment of a <property>__pclass</property> property <footnoteref \
linkend="mongodb.pclass"/>, + but it may be set as an element in the returned \
array if it was + present in the BSON document.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>"object"</literal> or <literal>"stdClass"</literal></term>
+ <listitem>
+ <para>
+ Turns a BSON array or BSON document into a
+ <classname>stdClass</classname> object. There will be no special
+ treatment of a <property>__pclass</property> property <footnoteref \
linkend="mongodb.pclass"/>, but it may + be set as a public property in the \
returned object if it was present + in the BSON document.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>any other string</term>
+ <listitem>
+ <para>
+ Defines the class name that the BSON array or BSON object should be
+ deserialized as. For BSON objects that include
+ <property>__pclass</property> properties, that class will take
+ priority.
+ </para>
+
+ <para>
+ If the named class does not exist, is not concrete (i.e. it is
+ abstract or an interface), or does not implement
+ <classname>MongoDB\BSON\Unserializable</classname> then an
+ <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname>
+ exception is thrown.
+ </para>
+
+ <para>
+ If the BSON object has a <property>__pclass</property> property and
+ that class exists and implements
+ <classname>MongoDB\BSON\Persistable</classname> it will supersede the
+ class provided in the type map.
+ </para>
+
+ <para>
+ The properties of the BSON document, <emphasis>including</emphasis>
+ the <property>__pclass</property> property if it exists, will be sent
+ as an associative array to the
+ <methodname>bsonUnserialize</methodname> function to initialise the
+ object's properties.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <section xml:id="mongodb.persistence.typemaps">
+ <title>TypeMaps</title>
+
+ <para>
+ TypeMaps can be set through the
+ <methodname>MongoDB\Driver\Cursor::setTypeMap</methodname> method on a
+ <classname>MongoDB\Driver\Cursor</classname> object, or the
+ <literal>$typeMap</literal> argument of
+ <function>MongoDB\BSON\toPHP</function>. Each of the three
+ classes (<emphasis>root</emphasis>, <emphasis>document</emphasis> and
+ <emphasis>array</emphasis>) can be individually set.
+ </para>
+
+ <para>
+ If the value in the map is <type>NULL</type>, it means the same as the
+ <emphasis>default</emphasis> value for that item.
+ </para>
+ </section>
+
+ <section>
+ <title>Examples</title>
+
+ <para>
+ These examples use the following classes:
+ </para>
+
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>MyClass</term>
+ <listitem>
+ <para>
+ which does <emphasis>not</emphasis> implement any interface
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>YourClass</term>
+ <listitem>
+ <para>
+ which implements <classname>MongoDB\BSON\Unserializable</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>OurClass</term>
+ <listitem>
+ <para>
+ which implements <classname>MongoDB\BSON\Persistable</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TheirClass</term>
+ <listitem>
+ <para>
+ which extends OurClass
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ The <methodname>bsonUnserialize</methodname> method of YourClass,
+ OurClass, TheirClass iterate over the array and set the properties
+ without modifications. It <emphasis>also</emphasis> sets the
+ <literal>$unserialized</literal> property to <literal>true</literal>:
+
+ <programlisting>
+function bsonUnserialize( array $map )
+{
+ foreach ( $map as $k => $value )
+ {
+ $this->$k = $value;
+ }
+ $this->unserialized = true;
+}
+ </programlisting>
+ </para>
+
+ <para>
+ <programlisting>
+/* typemap: [] (all defaults) */
+{ "foo": "yes", "bar" : false }
+ -> stdClass { $foo => 'yes', $bar => false }
+
+{ "foo": "no", "array" : [ 5, 6 ] }
+ -> stdClass { $foo => 'no', $array => [ 5, 6 ] }
+
+{ "foo": "no", "obj" : { "embedded" : 3.14 } }
+ -> stdClass { $foo => 'no', $obj => stdClass { $embedded => 3.14 } }
+
+{ "foo": "yes", "__pclass": "MyClass" }
+ -> stdClass { $foo => 'yes', $__pclass => 'MyClass' }
+
+{ "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "MyClass" } }
+ -> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'MyClass') }
+
+{ "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "YourClass") }
+ -> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass') }
+
+{ "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "OurClass") }
+ -> OurClass { $foo => 'yes', $__pclass => Binary(0x80, 'OurClass'), $unserialized \
=> true } +
+{ "foo": "yes", "__pclass": { "$type" : "44", "$binary" : "YourClass") }
+ -> stdClass { $foo => 'yes', $__pclass => Binary(0x44, 'YourClass') }
+ </programlisting>
+ </para>
+
+ <para>
+ <programlisting>
+/* typemap: [ "root" => "MissingClass" ] */
+{ "foo": "yes" }
+ -> MongoDB\Driver\Exception\InvalidArgumentException("MissingClass does not \
exist") +
+/* typemap: [ "root" => "MyClass" ] */
+{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
+ -> MongoDB\Driver\Exception\InvalidArgumentException("MyClass does not implement \
Unserializable interface") +
+/* typemap: [ "root" => "MongoDB\BSON\Unserializable" ] */
+{ "foo": "yes" }
+ -> MongoDB\Driver\Exception\InvalidArgumentException("Unserializable is not a \
concrete class") +
+/* typemap: [ "root" => "YourClass" ] */
+{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": \
"MongoDB\BSON\Unserializable" } } + -> YourClass { $foo => "yes", $__pclass => \
Binary(0x80, "MongoDB\BSON\Unserializable"), $unserialized => true } +
+/* typemap: [ "root" => "YourClass" ] */
+{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
+ -> YourClass { $foo => "yes", $__pclass => Binary(0x80, "MyClass"), $unserialized \
=> true } +
+/* typemap: [ "root" => "YourClass" ] */
+{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
+ -> OurClass { $foo => "yes", $__pclass => Binary(0x80, "OurClass"), $unserialized \
=> true } +
+/* typemap: [ "root" => "YourClass" ] */
+{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
+ -> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), \
$unserialized => true } +
+/* typemap: [ "root" => "OurClass" ] */
+{ foo: "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
+ -> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), \
$unserialized => true } + </programlisting>
+ </para>
+
+ <para>
+ <programlisting>
+/* typemap: [ 'root' => 'YourClass' ] */
+{ foo: "yes", "__pclass" : { "$type": "80", "$binary": "YourClass" } }
+ -> YourClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass'), \
$unserialized => true } + </programlisting>
+ </para>
+
+ <para>
+ <programlisting>
+/* typemap: [ 'root' => 'array', 'document' => 'array' ] */
+{ "foo": "yes", "bar" : false }
+ -> [ "foo" => "yes", "bar" => false ]
+
+{ "foo": "no", "array" : [ 5, 6 ] }
+ -> [ "foo" => "no", "array" => [ 5, 6 ] ]
+
+{ "foo": "no", "obj" : { "embedded" : 3.14 } }
+ -> [ "foo" => "no", "obj" => [ "embedded => 3.14 ] ]
+
+{ "foo": "yes", "__pclass": "MyClass" }
+ -> [ "foo" => "yes", "__pclass" => "MyClass" ]
+
+{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
+ -> [ "foo" => "yes", "__pclass" => Binary(0x80, "MyClass") ]
+
+{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
+ -> [ "foo" => "yes", "__pclass" => Binary(0x80, "OurClass") ]
+ </programlisting>
+ </para>
+
+ <para>
+ <programlisting>
+/* typemap: [ 'root' => 'object', 'document' => 'object' ] */
+{ "foo": "yes", "__pclass": { "$type": "80", "$binary": "MyClass" } }
+ -> stdClass { $foo => "yes", "__pclass" => Binary(0x80, "MyClass") }
+ </programlisting>
+ </para>
+
+ </section>
+ </section>
+
+ </article>
+</book>
+
+<!-- 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
+indent-tabs-mode:nil
+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
+-->
Added: phpdoc/en/trunk/reference/mongodb/images/driver_arch.png
===================================================================
(Binary files differ)
Property changes on: phpdoc/en/trunk/reference/mongodb/images/driver_arch.png
___________________________________________________________________
Added: svn:mime-type
+ application/octet-stream
Deleted: phpdoc/en/trunk/reference/mongodb/persistence.xml
===================================================================
--- phpdoc/en/trunk/reference/mongodb/persistence.xml 2015-11-16 06:00:10 UTC (rev \
338132)
+++ phpdoc/en/trunk/reference/mongodb/persistence.xml 2015-11-16 12:29:43 UTC (rev \
338133) @@ -1,625 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 337115 $ -->
-
-<book xml:id="mongodb.persistence" xmlns="http://docbook.org/ns/docbook" \
xmlns:xlink="http://www.w3.org/1999/xlink">
- <titleabbrev>Persisting Data</titleabbrev>
- <title>Serialisation and deserialisation of PHP variables into MongoDB</title>
-
- <article xml:id="mongodb.persistence.article">
- <titleabbrev>Persisting Data</titleabbrev>
- <title>Serialisation and deserialisation of PHP variables into MongoDB</title>
-
- <para>
- This document discusses the methods how compound structures (documents,
- arrays, objects) are persisted through the drivers. And how they are brought
- back into PHP land.
- </para>
-
- <section>
- <title>Serialisation to BSON</title>
-
- <section>
- <title>Arrays</title>
-
- <para>
- If an array is a <emphasis>packed array</emphasis> — i.e. the keys start
- at 0 and are sequential without gaps: <emphasis>BSON array</emphasis>.
- </para>
-
- <para>
- If the array is not packed — i.e. having associative (string) keys, the
- keys don't start at 0, or when there are gaps:: <emphasis>BSON
- object</emphasis>
- </para>
-
- <para>
- A top-level (root) document, <emphasis>always</emphasis> serializes as a
- BSON document.
- </para>
-
- <section>
- <title>Examples</title>
-
- <para>
- These serialize as a BSON array:
- </para>
-
- <programlisting>
-[ 8, 5, 2, 3 ] => [ 8, 5, 2, 3 ]
-[ 0 => 4, 1 => 9 ] => [ 4, 9 ]
- </programlisting>
-
- <para>
- These serialize as a BSON document:
- </para>
-
- <programlisting>
-[ 0 => 1, 2 => 8, 3 => 12 ] => { "0" : 1, "2" : 8, "3" : 12 }
-[ "foo" => 42 ] => { "foo" : 42 }
-[ 1 => 9, 0 => 10 ] => { "1" : 9, "0" : 10 }
- </programlisting>
-
- <para>
- Note that the five examples are <emphasis>extracts</emphasis> of a full
- document, and represent only <emphasis>one</emphasis> value inside a
- document.
- </para>
-
- </section>
- </section>
-
- <section>
- <title>Objects</title>
-
- <para>
- If an object is of the <classname>stdClass</classname> class, serialize
- as a <emphasis>BSON document</emphasis>.
- </para>
-
- <para>
- If an object is a supported class that implements
- <classname>MongoDB\BSON\Type</classname>, then use the BSON
- serialization logic for that specific type.
- <classname>MongoDB\BSON\Type</classname> instances (excluding
- <classname>MongoDB\BSON\Serializable</classname> may only be serialized
- as a document field value. Attempting to serialize such an object as a
- root document will throw a
- <classname>MongoDB\Driver\Exception\UnexpectedValueException</classname>
- </para>
-
- <para>
- If an object is of an unknown class implementing the
- <classname>MongoDB\BSON\Type</classname> interface, then throw a
- <classname>MongoDB\Driver\Exception\UnexpectedValueException</classname>
- </para>
-
- <para>
- If an object is of any other class, without implementing any special
- interface, serialize as a <emphasis>BSON document</emphasis>. Keep only
- <emphasis>public</emphasis> properties, and ignore
- <emphasis>protected</emphasis> and <emphasis>private</emphasis>
- properties.
- </para>
-
- <para>
- If an object is of a class that implements the
- <classname>MongoDB\BSON\Serializable</classname> interface, call
- <methodname>bsonSerialize</methodname> and use the returned array or
- <classname>stdClass</classname> to serialize as a BSON document or
- array. The BSON type will be determined by the following:
- </para>
-
- <para>
- <orderedlist>
- <listitem>
- <para>Root documents must be serialized as a BSON
- document.
- </para>
- </listitem>
- <listitem>
- <para><classname>MongoDB\BSON\Persistable</classname> objects must be
- serialized as a BSON document.
- </para>
- </listitem>
- <listitem>
- <para>If <methodname>bsonSerialize</methodname> returns a packed
- array, serialize as a BSON array.
- </para>
- </listitem>
- <listitem>
- <para>If <methodname>bsonSerialize</methodname> returns a non-packed
- array or <classname>stdClass</classname>, serialize as a BSON
- document.
- </para>
- </listitem>
- <listitem>
- <para>If <methodname>bsonSerialize</methodname> did not return an
- array or <classname>stdClass</classname>, throw an
- <classname>MongoDB\Driver\Exception\UnexpectedValueException</classname>
- exception.
- </para>
- </listitem>
- </orderedlist>
- </para>
-
- <para>
- If an object is of a class that implements the
- <classname>MongoDB\BSON\Persistable</classname> interface (which implies
- <classname>MongoDB\BSON\Serializable</classname> obtain the properties
- in a similar way as in the previous paragraphs, but
- <emphasis>also</emphasis> add an additional property
- <property>__pclass</property> as a Binary value, with subtype
- <literal>0x80</literal> and data bearing the fully qualified class name
- of the object that is being serialized.
- </para>
-
- <para>
- The <property>__pclass</property> property is added to the array or
- object returned by <methodname>bsonSerialize</methodname>, which means
- it will overwrite any <property>__pclass</property> key/property in the
- <methodname>bsonSerialize</methodname> return value. If you want to
- avoid this behaviour and set your own <property>__pclass</property>
- value, you must <emphasis>not</emphasis> implement
- <classname>MongoDB\BSON\Persistable</classname> and should instead
- implement <classname>MongoDB\BSON\Serializable</classname> directly.
- </para>
-
- <section>
- <title>Examples</title>
-
- <programlisting>
-stdClass {
- public $foo = 42;
-} => { "foo" : 42 }
-
-MyClass {
- public $foo = 42;
- protected $prot = "wine";
- private $fpr = "cheese";
-} => { "foo" : 42 }
-
-AnotherClass1 implements MongoDB\BSON\Serializable {
- public $foo = 42;
- protected $prot = "wine";
- private $fpr = "cheese";
- function bsonSerialize() {
- return [ 'foo' => $this->foo, 'prot' => $this->prot ];
- }
-} => { "foo" : 42, "prot" : "wine" }
-
-AnotherClass2 implements MongoDB\BSON\Serializable {
- public $foo = 42;
- function bsonSerialize() {
- return $this;
- }
-} => MongoDB\Driver\Exception\UnexpectedValueException("bsonSerialize() did not \
return an array or stdClass")
-
-AnotherClass3 implements MongoDB\BSON\Serializable {
- private $elements = [ 'foo', 'bar' ];
- function bsonSerialize() {
- return $this->elements;
- }
-} => { "0" : "foo", "1" : "bar" }
-
-ContainerClass implements MongoDB\BSON\Serializable {
- public $things = AnotherClass4 implements MongoDB\BSON\Serializable {
- private $elements = [ 0 => 'foo', 2 => 'bar' ];
- function bsonSerialize() {
- return $this->elements;
- }
- }
- function bsonSerialize() {
- return [ 'things' => $this->things ];
- }
-} => { "things" : { "0" : "foo", "2" : "bar" } }
-
-ContainerClass implements MongoDB\BSON\Serializable {
- public $things = AnotherClass5 implements MongoDB\BSON\Serializable {
- private $elements = [ 0 => 'foo', 2 => 'bar' ];
- function bsonSerialize() {
- return array_values($this->elements);
- }
- }
- function bsonSerialize() {
- return [ 'things' => $this->things ];
- }
-} => { "things" : [ "foo", "bar" ] }
-
-ContainerClass implements MongoDB\BSON\Serializable {
- public $things = AnotherClass6 implements MongoDB\BSON\Serializable {
- private $elements = [ 'foo', 'bar' ];
- function bsonSerialize() {
- return (object) $this->elements;
- }
- }
- function bsonSerialize() {
- return [ 'things' => $this->things ];
- }
-} => { "things" : { "0" : "foo", "1" : "bar" } }
-
-UpperClass implements MongoDB\BSON\Persistable {
- public $foo = 42;
- protected $prot = "wine";
- private $fpr = "cheese";
- function bsonSerialize() {
- return [ 'foo' => $this->foo, 'prot' => $this->prot ];
- }
-} => { "foo" : 42, "prot" : "wine", "__pclass" : { "$type" : "80", "$binary" : \
"VXBwZXJDbGFzcw==" } }
- </programlisting>
- </section>
- </section>
- </section>
-
- <section>
- <title>Deserialization from BSON</title>
-
- <para>
- For compound types, there are three data types:
- </para>
-
- <para>
- <variablelist>
- <varlistentry>
- <term>root</term>
- <listitem>
- <para>
- refers to the top-level BSON document <emphasis>only</emphasis>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>document</term>
- <listitem>
- <para>
- refers to embedded BSON documents <emphasis>only</emphasis>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>array</term>
- <listitem>
- <para>
- refers to a BSON array
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- Each of those three data types can be mapped against different PHP types.
- The possible mapping values are:
- </para>
-
- <para>
- <variablelist>
- <varlistentry>
- <term><emphasis>not set</emphasis> or <type>NULL</type> (the is the
- default)</term>
- <listitem>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- A BSON array will be deserialized as a PHP <type>array</type>.
- </para>
- </listitem>
- <listitem>
- <para>
- A BSON document (root or embedded) without a
- <property>__pclass</property> property
- <footnote xml:id="mongodb.pclass">
- <para>
- A __pclass property is only deemed to exist if
- there exists a property with that name, and it is a Binary value,
- and the sub-type of the Binary value is 0x80. If any of these three
- conditions is not met, the __pclass property does not exist and
- should be treated as any other normal property.
- </para>
- </footnote>
- becomes a PHP <classname>stdClass</classname> object, with each
- BSON document key set as a public <classname>stdClass</classname>
- property.
- </para>
- </listitem>
- <listitem>
- <para>
- A BSON document (root or embedded) with a
- <property>__pclass</property> property <footnoteref \
linkend="mongodb.pclass"/> becomes a PHP object of
- the class name as defined by the <property>__pclass</property>
- property.
- </para>
- <para>
- If the named class implements the
- <classname>MongoDB\BSON\Persistable</classname> interface, then the
- properties of the BSON document, including the
- <property>__pclass</property> property, are sent as an associative
- array to the <methodname>bsonUnserialize</methodname> function to
- initialise the object's properties.
- </para>
- <para>
- If the named class does not exist or does not implement the
- <classname>MongoDB\BSON\Persistable</classname> interface,
- <classname>stdClass</classname> will be used and each BSON document
- key (including <property>__pclass</property>) will be set as a
- public <classname>stdClass</classname> property.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>"array"</literal></term>
- <listitem>
- <para>
- Turns a BSON array or BSON document into a PHP array. There will be no
- special treatment of a <property>__pclass</property> property <footnoteref \
linkend="mongodb.pclass"/>,
- but it may be set as an element in the returned array if it was
- present in the BSON document.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>"object"</literal> or <literal>"stdClass"</literal></term>
- <listitem>
- <para>
- Turns a BSON array or BSON document into a
- <classname>stdClass</classname> object. There will be no special
- treatment of a <property>__pclass</property> property <footnoteref \
linkend="mongodb.pclass"/>, but it may
- be set as a public property in the returned object if it was present
- in the BSON document.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>any other string</term>
- <listitem>
- <para>
- Defines the class name that the BSON array or BSON object should be
- deserialized as. For BSON objects that include
- <property>__pclass</property> properties, that class will take
- priority.
- </para>
-
- <para>
- If the named class does not exist, is not concrete (i.e. it is
- abstract or an interface), or does not implement
- <classname>MongoDB\BSON\Unserializable</classname> then an
- <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname>
- exception is thrown.
- </para>
-
- <para>
- If the BSON object has a <property>__pclass</property> property and
- that class exists and implements
- <classname>MongoDB\BSON\Persistable</classname> it will supersede the
- class provided in the type map.
- </para>
-
- <para>
- The properties of the BSON document, <emphasis>including</emphasis>
- the <property>__pclass</property> property if it exists, will be sent
- as an associative array to the
- <methodname>bsonUnserialize</methodname> function to initialise the
- object's properties.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <section xml:id="mongodb.persistence.typemaps">
- <title>TypeMaps</title>
-
- <para>
- TypeMaps can be set through the
- <methodname>MongoDB\Driver\Cursor::setTypeMap</methodname> method on a
- <classname>MongoDB\Driver\Cursor</classname> object, or the
- <literal>$typeMap</literal> argument of
- <function>MongoDB\BSON\toPHP</function>. Each of the three
- classes (<emphasis>root</emphasis>, <emphasis>document</emphasis> and
- <emphasis>array</emphasis>) can be individually set.
- </para>
-
- <para>
- If the value in the map is <type>NULL</type>, it means the same as the
- <emphasis>default</emphasis> value for that item.
- </para>
- </section>
-
- <section>
- <title>Examples</title>
-
- <para>
- These examples use the following classes:
- </para>
-
- <para>
- <variablelist>
- <varlistentry>
- <term>MyClass</term>
- <listitem>
- <para>
- which does <emphasis>not</emphasis> implement any interface
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>YourClass</term>
- <listitem>
- <para>
- which implements <classname>MongoDB\BSON\Unserializable</classname>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>OurClass</term>
- <listitem>
- <para>
- which implements <classname>MongoDB\BSON\Persistable</classname>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>TheirClass</term>
- <listitem>
- <para>
- which extends OurClass
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- The <methodname>bsonUnserialize</methodname> method of YourClass,
- OurClass, TheirClass iterate over the array and set the properties
- without modifications. It <emphasis>also</emphasis> sets the
- <literal>$unserialized</literal> property to <literal>true</literal>:
-
- <programlisting>
-function bsonUnserialize( array $map )
-{
- foreach ( $map as $k => $value )
- {
- $this->$k = $value;
- }
- $this->unserialized = true;
-}
- </programlisting>
- </para>
-
- <para>
- <programlisting>
-/* typemap: [] (all defaults) */
-{ "foo": "yes", "bar" : false }
- -> stdClass { $foo => 'yes', $bar => false }
-
-{ "foo": "no", "array" : [ 5, 6 ] }
- -> stdClass { $foo => 'no', $array => [ 5, 6 ] }
-
-{ "foo": "no", "obj" : { "embedded" : 3.14 } }
- -> stdClass { $foo => 'no', $obj => stdClass { $embedded => 3.14 } }
-
-{ "foo": "yes", "__pclass": "MyClass" }
- -> stdClass { $foo => 'yes', $__pclass => 'MyClass' }
-
-{ "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "MyClass" } }
- -> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'MyClass') }
-
-{ "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "YourClass") }
- -> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass') }
-
-{ "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "OurClass") }
- -> OurClass { $foo => 'yes', $__pclass => Binary(0x80, 'OurClass'), $unserialized \
=> true }
-
-{ "foo": "yes", "__pclass": { "$type" : "44", "$binary" : "YourClass") }
- -> stdClass { $foo => 'yes', $__pclass => Binary(0x44, 'YourClass') }
- </programlisting>
- </para>
-
- <para>
- <programlisting>
-/* typemap: [ "root" => "MissingClass" ] */
-{ "foo": "yes" }
- -> MongoDB\Driver\Exception\InvalidArgumentException("MissingClass does not \
exist")
-
-/* typemap: [ "root" => "MyClass" ] */
-{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
- -> MongoDB\Driver\Exception\InvalidArgumentException("MyClass does not implement \
Unserializable interface")
-
-/* typemap: [ "root" => "MongoDB\BSON\Unserializable" ] */
-{ "foo": "yes" }
- -> MongoDB\Driver\Exception\InvalidArgumentException("Unserializable is not a \
concrete class")
-
-/* typemap: [ "root" => "YourClass" ] */
-{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": \
"MongoDB\BSON\Unserializable" } }
- -> YourClass { $foo => "yes", $__pclass => Binary(0x80, \
"MongoDB\BSON\Unserializable"), $unserialized => true }
-
-/* typemap: [ "root" => "YourClass" ] */
-{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
- -> YourClass { $foo => "yes", $__pclass => Binary(0x80, "MyClass"), $unserialized \
=> true }
-
-/* typemap: [ "root" => "YourClass" ] */
-{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
- -> OurClass { $foo => "yes", $__pclass => Binary(0x80, "OurClass"), $unserialized \
=> true }
-
-/* typemap: [ "root" => "YourClass" ] */
-{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
- -> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), \
$unserialized => true }
-
-/* typemap: [ "root" => "OurClass" ] */
-{ foo: "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
- -> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), \
$unserialized => true }
- </programlisting>
- </para>
-
- <para>
- <programlisting>
-/* typemap: [ 'root' => 'YourClass' ] */
-{ foo: "yes", "__pclass" : { "$type": "80", "$binary": "YourClass" } }
- -> YourClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass'), \
$unserialized => true }
- </programlisting>
- </para>
-
- <para>
- <programlisting>
-/* typemap: [ 'root' => 'array', 'document' => 'array' ] */
-{ "foo": "yes", "bar" : false }
- -> [ "foo" => "yes", "bar" => false ]
-
-{ "foo": "no", "array" : [ 5, 6 ] }
- -> [ "foo" => "no", "array" => [ 5, 6 ] ]
-
-{ "foo": "no", "obj" : { "embedded" : 3.14 } }
- -> [ "foo" => "no", "obj" => [ "embedded => 3.14 ] ]
-
-{ "foo": "yes", "__pclass": "MyClass" }
- -> [ "foo" => "yes", "__pclass" => "MyClass" ]
-
-{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
- -> [ "foo" => "yes", "__pclass" => Binary(0x80, "MyClass") ]
-
-{ "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
- -> [ "foo" => "yes", "__pclass" => Binary(0x80, "OurClass") ]
- </programlisting>
- </para>
-
- <para>
- <programlisting>
-/* typemap: [ 'root' => 'object', 'document' => 'object' ] */
-{ "foo": "yes", "__pclass": { "$type": "80", "$binary": "MyClass" } }
- -> stdClass { $foo => "yes", "__pclass" => Binary(0x80, "MyClass") }
- </programlisting>
- </para>
-
- </section>
- </section>
-
- </article>
-</book>
-
-<!-- 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
-indent-tabs-mode:nil
-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
--->
Modified: phpdoc/en/trunk/reference/mongodb/set.xml
===================================================================
--- phpdoc/en/trunk/reference/mongodb/set.xml 2015-11-16 06:00:10 UTC (rev 338132)
+++ phpdoc/en/trunk/reference/mongodb/set.xml 2015-11-16 12:29:43 UTC (rev 338133)
@@ -35,7 +35,7 @@
&reference.mongodb.setup;
&reference.mongodb.tutorial;
- &reference.mongodb.persistence;
+ &reference.mongodb.architecture;
&reference.mongodb.mongodb;
&reference.mongodb.bson;
--
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic