mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
Document MongoDB\BSON\TypeWrapper interface
https://jira.mongodb.org/browse/PHPC-640 This only adds API documentation for the actual interface. Additional documentation will needed to be added to the persistence documentation. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@342837 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Jeremy Mikola
parent
70f942e5b5
commit
52c747e77a
5 changed files with 401 additions and 0 deletions
|
|
@ -18,6 +18,7 @@
|
|||
&reference.mongodb.bson.utcdatetime;
|
||||
|
||||
&reference.mongodb.bson.type;
|
||||
&reference.mongodb.bson.typewrapper;
|
||||
&reference.mongodb.bson.persistable;
|
||||
&reference.mongodb.bson.serializable;
|
||||
&reference.mongodb.bson.unserializable;
|
||||
|
|
|
|||
70
reference/mongodb/bson/typewrapper.xml
Normal file
70
reference/mongodb/bson/typewrapper.xml
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision: 338057 $ -->
|
||||
|
||||
<phpdoc:classref xml:id="class.mongodb-bson-typewrapper" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
|
||||
<title>The MongoDB\BSON\TypeWrapper interface</title>
|
||||
<titleabbrev>MongoDB\BSON\TypeWrapper</titleabbrev>
|
||||
|
||||
<partintro>
|
||||
|
||||
<!-- {{{ MongoDB\BSON\TypeWrapper intro -->
|
||||
<section xml:id="mongodb-bson-typewrapper.intro">
|
||||
&reftitle.intro;
|
||||
<para>
|
||||
Classes that implement this interface may be specified in a
|
||||
<link linkend="mongodb.persistence.typemaps">type map</link> for
|
||||
wrapping BSON type classes (e.g.
|
||||
<classname>MongoDB\BSON\UTCDateTime</classname>).
|
||||
</para>
|
||||
</section>
|
||||
<!-- }}} -->
|
||||
|
||||
<section xml:id="mongodb-bson-typewrapper.synopsis">
|
||||
&reftitle.interfacesynopsis;
|
||||
|
||||
<!-- {{{ Synopsis -->
|
||||
<classsynopsis>
|
||||
<ooclass><classname>MongoDB\BSON\TypeWrapper</classname></ooclass>
|
||||
|
||||
<!-- {{{ Class synopsis -->
|
||||
<classsynopsisinfo>
|
||||
<ooclass>
|
||||
<classname>MongoDB\BSON\TypeWrapper</classname>
|
||||
</ooclass>
|
||||
</classsynopsisinfo>
|
||||
<!-- }}} -->
|
||||
|
||||
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
|
||||
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongodb-bson-typewrapper')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" />
|
||||
</classsynopsis>
|
||||
<!-- }}} -->
|
||||
|
||||
</section>
|
||||
|
||||
</partintro>
|
||||
|
||||
&reference.mongodb.bson.entities.typewrapper;
|
||||
|
||||
</phpdoc:classref>
|
||||
|
||||
<!-- 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
|
||||
-->
|
||||
167
reference/mongodb/bson/typewrapper/createfrombsontype.xml
Normal file
167
reference/mongodb/bson/typewrapper/createfrombsontype.xml
Normal file
|
|
@ -0,0 +1,167 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision: 338656 $ -->
|
||||
|
||||
<refentry xml:id="mongodb-bson-typewrapper.createfrombsontype" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<refnamediv>
|
||||
<refname>MongoDB\BSON\TypeWrapper::createFromBSONType</refname>
|
||||
<refpurpose>Converts the BSON type to a PHP value</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 role="description">
|
||||
&reftitle.description;
|
||||
<methodsynopsis>
|
||||
<modifier>abstract</modifier> <modifier>public</modifier> <modifier>static</modifier> <type>mixed</type><methodname>MongoDB\BSON\TypeWrapper::createFromBSONType</methodname>
|
||||
<methodparam><type>MongoDB\BSON\Type</type><parameter>type</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
Called during unserialization of a BSON type for which this wrapper is
|
||||
assigned. The <interfacename>MongoDB\BSON\Type</interfacename> object will be
|
||||
passed to this method, which should then return a PHP value to take the place
|
||||
of the <interfacename>MongoDB\BSON\Type</interfacename> object in the
|
||||
document.
|
||||
</para>
|
||||
<para>
|
||||
This method typically acts as a factory method for the class implementing
|
||||
<interfacename>MongoDB\BSON\TypeWrapper</interfacename>. As such, it may
|
||||
return a new instance of itself constructed from the
|
||||
<parameter>type</parameter> parameter.
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
Unless the implementing class is designed to wrap all BSON types, it is good
|
||||
practice to first check that the <parameter>type</parameter> parameter is an
|
||||
&instanceof; the expected BSON type and throw an exception otherwise. This
|
||||
will allow the application to more easily detect an error in the type map
|
||||
configuration (e.g. assigning a BinaryWrapper class to wrap ObjectID types).
|
||||
</para>
|
||||
</note>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="parameters">
|
||||
&reftitle.parameters;
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><parameter>type</parameter> (<interfacename>MongoDB\BSON\Type</interfacename>)</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The BSON object to be wrapped or converted.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>
|
||||
The return value from this method will take the place of the
|
||||
<parameter>type</parameter> parameter in the document.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="examples">
|
||||
&reftitle.examples;
|
||||
<example>
|
||||
<title><function>MongoDB\BSON\TypeWrapper::createFromBSONType</function> used to wrap a UTCDateTime</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
|
||||
class LocalDateTime implements MongoDB\BSON\TypeWrapper, MongoDB\BSON\UTCDateTimeInterface
|
||||
{
|
||||
private $localDateTime;
|
||||
|
||||
public function __construct(DateTime $dateTime)
|
||||
{
|
||||
$this->localDateTime = clone $dateTime;
|
||||
$this->localDateTime->setTimezone(new DateTimeZone(date_default_timezone_get()));
|
||||
}
|
||||
|
||||
public static function createFromBSONType(MongoDB\BSON\Type $type)
|
||||
{
|
||||
if ( ! $type instanceof MongoDB\BSON\UTCDateTime) {
|
||||
throw new InvalidArgumentException('Cannot create MyUTCDateTime from ' . get_class($type));
|
||||
}
|
||||
|
||||
return new self($type->toDateTime());
|
||||
}
|
||||
|
||||
public function toBSONType()
|
||||
{
|
||||
return new MongoDB\BSON\UTCDateTime($this->localDateTime);
|
||||
}
|
||||
|
||||
public function toDateTime()
|
||||
{
|
||||
return clone $this->localDateTime;
|
||||
}
|
||||
|
||||
public function __toString()
|
||||
{
|
||||
return (string) $this->toBSONType();
|
||||
}
|
||||
}
|
||||
|
||||
$bson = MongoDB\BSON\fromJSON('{ "date": { "$date": "2015-10-28T00:00:00Z" }}');
|
||||
$document = MongoDB\BSON\toPHP($bson, ['types' => ['UTCDateTime' => 'LocalDateTime']]);
|
||||
var_dump($document);
|
||||
|
||||
$bson = MongoDB\BSON\fromPHP($document);
|
||||
echo MongoDB\BSON\toRelaxedExtendedJSON($bson), "\n";
|
||||
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs.similar;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
object(stdClass)#1 (1) {
|
||||
["date"]=>
|
||||
object(LocalDateTime)#2 (1) {
|
||||
["localDateTime":"LocalDateTime":private]=>
|
||||
object(DateTime)#4 (3) {
|
||||
["date"]=>
|
||||
string(26) "2015-10-27 20:00:00.000000"
|
||||
["timezone_type"]=>
|
||||
int(3)
|
||||
["timezone"]=>
|
||||
string(16) "America/New_York"
|
||||
}
|
||||
}
|
||||
}
|
||||
{ "date" : { "$date" : "2015-10-28T00:00:00Z" } }
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="seealso">
|
||||
&reftitle.seealso;
|
||||
<simplelist>
|
||||
<member><function>MongoDB\BSON\TypeWrapper::toBSONType</function></member>
|
||||
<member><xref linkend="mongodb.persistence"/></member>
|
||||
</simplelist>
|
||||
</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
|
||||
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
|
||||
-->
|
||||
159
reference/mongodb/bson/typewrapper/tobsontype.xml
Normal file
159
reference/mongodb/bson/typewrapper/tobsontype.xml
Normal file
|
|
@ -0,0 +1,159 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision: 338656 $ -->
|
||||
|
||||
<refentry xml:id="mongodb-bson-typewrapper.tobsontype" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<refnamediv>
|
||||
<refname>MongoDB\BSON\TypeWrapper::toBSONType</refname>
|
||||
<refpurpose>Converts the BSON type to a PHP value</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 role="description">
|
||||
&reftitle.description;
|
||||
<methodsynopsis>
|
||||
<modifier>abstract</modifier> <modifier>public</modifier> <type>mixed</type><methodname>MongoDB\BSON\TypeWrapper::toBSONType</methodname>
|
||||
<void />
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
Called during serialization of the object to BSON. The method may return any
|
||||
PHP value, which will be converted to a BSON.
|
||||
</para>
|
||||
<para>
|
||||
If the class implementing
|
||||
<interfacename>MongoDB\BSON\TypeWrapper</interfacename> wraps a
|
||||
<interfacename>MongoDB\BSON\Type</interfacename> object, this method should
|
||||
likely return the wrapped object.
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
If this method returns a
|
||||
<interfacename>MongoDB\BSON\Serializable</interfacename> or another
|
||||
<interfacename>MongoDB\BSON\TypeWrapper</interfacename> instance, the return
|
||||
value will be converted accordingly (e.g.
|
||||
<methodname>MongoDB\BSON\Serializable::bsonSerialize</methodname> or
|
||||
<methodname>MongoDB\BSON\TypeWrapper::toBSONType</methodname> will be called
|
||||
on the returned object). An exception will be thrown during BSON
|
||||
serialization if the driver detects recursion (e.g. this method returns its
|
||||
own instance).
|
||||
</para>
|
||||
</note>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="parameters">
|
||||
&reftitle.parameters;
|
||||
&no.function.parameters;
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>
|
||||
A PHP value to be serialized to BSON in place of the
|
||||
<interfacename>MongoDB\BSON\TypeWrapper</interfacename> object.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="examples">
|
||||
&reftitle.examples;
|
||||
<example>
|
||||
<title><function>MongoDB\BSON\TypeWrapper::toBSONType</function> used to wrap a UTCDateTime</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
|
||||
class LocalDateTime implements MongoDB\BSON\TypeWrapper, MongoDB\BSON\UTCDateTimeInterface
|
||||
{
|
||||
private $localDateTime;
|
||||
|
||||
public function __construct(DateTime $dateTime)
|
||||
{
|
||||
$this->localDateTime = clone $dateTime;
|
||||
$this->localDateTime->setTimezone(new DateTimeZone(date_default_timezone_get()));
|
||||
}
|
||||
|
||||
public static function createFromBSONType(MongoDB\BSON\Type $type)
|
||||
{
|
||||
if ( ! $type instanceof MongoDB\BSON\UTCDateTime) {
|
||||
throw new InvalidArgumentException('Cannot create MyUTCDateTime from ' . get_class($type));
|
||||
}
|
||||
|
||||
return new self($type->toDateTime());
|
||||
}
|
||||
|
||||
public function toBSONType()
|
||||
{
|
||||
return new MongoDB\BSON\UTCDateTime($this->localDateTime);
|
||||
}
|
||||
|
||||
public function toDateTime()
|
||||
{
|
||||
return clone $this->localDateTime;
|
||||
}
|
||||
|
||||
public function __toString()
|
||||
{
|
||||
return (string) $this->toBSONType();
|
||||
}
|
||||
}
|
||||
|
||||
$bson = MongoDB\BSON\fromJSON('{ "date": { "$date": "2015-10-28T00:00:00Z" }}');
|
||||
$document = MongoDB\BSON\toPHP($bson, ['types' => ['UTCDateTime' => 'LocalDateTime']]);
|
||||
var_dump($document);
|
||||
|
||||
$bson = MongoDB\BSON\fromPHP($document);
|
||||
echo MongoDB\BSON\toRelaxedExtendedJSON($bson), "\n";
|
||||
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs.similar;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
object(stdClass)#1 (1) {
|
||||
["date"]=>
|
||||
object(LocalDateTime)#2 (1) {
|
||||
["localDateTime":"LocalDateTime":private]=>
|
||||
object(DateTime)#4 (3) {
|
||||
["date"]=>
|
||||
string(26) "2015-10-27 20:00:00.000000"
|
||||
["timezone_type"]=>
|
||||
int(3)
|
||||
["timezone"]=>
|
||||
string(16) "America/New_York"
|
||||
}
|
||||
}
|
||||
}
|
||||
{ "date" : { "$date" : "2015-10-28T00:00:00Z" } }
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 role="seealso">
|
||||
&reftitle.seealso;
|
||||
<simplelist>
|
||||
<member><function>MongoDB\BSON\TypeWrapper::createFromBSONType</function></member>
|
||||
<member><xref linkend="mongodb.persistence"/></member>
|
||||
</simplelist>
|
||||
</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
|
||||
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
|
||||
-->
|
||||
|
|
@ -131,6 +131,10 @@
|
|||
|
||||
<function name='mongodb\bson\type' from='mongodb >=1.0.0'/>
|
||||
|
||||
<function name='mongodb\bson\typewrapper' from='mongodb >=1.3.0'/>
|
||||
<function name='mongodb\bson\typewrapper::createfrombsontype' from='mongodb >=1.3.0'/>
|
||||
<function name='mongodb\bson\typewrapper::tobsontype' from='mongodb >=1.3.0'/>
|
||||
|
||||
<function name='mongodb\bson\unserializable' from='mongodb >=1.0.0'/>
|
||||
<function name='mongodb\bson\unserializable::bsonunserialize' from='mongodb >=1.0.0'/>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue