From 52c747e77ad1ea9e8820de4bd5707855cc87a2fc Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Fri, 11 Aug 2017 00:12:52 +0000 Subject: [PATCH] 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 --- reference/mongodb/bson.xml | 1 + reference/mongodb/bson/typewrapper.xml | 70 ++++++++ .../bson/typewrapper/createfrombsontype.xml | 167 ++++++++++++++++++ .../mongodb/bson/typewrapper/tobsontype.xml | 159 +++++++++++++++++ reference/mongodb/versions.xml | 4 + 5 files changed, 401 insertions(+) create mode 100644 reference/mongodb/bson/typewrapper.xml create mode 100644 reference/mongodb/bson/typewrapper/createfrombsontype.xml create mode 100644 reference/mongodb/bson/typewrapper/tobsontype.xml diff --git a/reference/mongodb/bson.xml b/reference/mongodb/bson.xml index 23c11c9029..1238049377 100644 --- a/reference/mongodb/bson.xml +++ b/reference/mongodb/bson.xml @@ -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; diff --git a/reference/mongodb/bson/typewrapper.xml b/reference/mongodb/bson/typewrapper.xml new file mode 100644 index 0000000000..2ba8286ecb --- /dev/null +++ b/reference/mongodb/bson/typewrapper.xml @@ -0,0 +1,70 @@ + + + + + + The MongoDB\BSON\TypeWrapper interface + MongoDB\BSON\TypeWrapper + + + + +
+ &reftitle.intro; + + Classes that implement this interface may be specified in a + type map for + wrapping BSON type classes (e.g. + MongoDB\BSON\UTCDateTime). + +
+ + +
+ &reftitle.interfacesynopsis; + + + + MongoDB\BSON\TypeWrapper + + + + + MongoDB\BSON\TypeWrapper + + + + + &Methods; + + + + +
+ + + + &reference.mongodb.bson.entities.typewrapper; + + + + diff --git a/reference/mongodb/bson/typewrapper/createfrombsontype.xml b/reference/mongodb/bson/typewrapper/createfrombsontype.xml new file mode 100644 index 0000000000..3a703120c7 --- /dev/null +++ b/reference/mongodb/bson/typewrapper/createfrombsontype.xml @@ -0,0 +1,167 @@ + + + + + + MongoDB\BSON\TypeWrapper::createFromBSONType + Converts the BSON type to a PHP value + + + + &reftitle.description; + + abstract public static mixedMongoDB\BSON\TypeWrapper::createFromBSONType + MongoDB\BSON\Typetype + + + Called during unserialization of a BSON type for which this wrapper is + assigned. The MongoDB\BSON\Type object will be + passed to this method, which should then return a PHP value to take the place + of the MongoDB\BSON\Type object in the + document. + + + This method typically acts as a factory method for the class implementing + MongoDB\BSON\TypeWrapper. As such, it may + return a new instance of itself constructed from the + type parameter. + + + + Unless the implementing class is designed to wrap all BSON types, it is good + practice to first check that the type 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). + + + + + + &reftitle.parameters; + + + type (MongoDB\BSON\Type) + + + The BSON object to be wrapped or converted. + + + + + + + + &reftitle.returnvalues; + + The return value from this method will take the place of the + type parameter in the document. + + + + + &reftitle.examples; + + <function>MongoDB\BSON\TypeWrapper::createFromBSONType</function> used to wrap a UTCDateTime + +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"; + +?> +]]> + + &example.outputs.similar; + + + 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" } } +]]> + + + + + + &reftitle.seealso; + + MongoDB\BSON\TypeWrapper::toBSONType + + + + + + + diff --git a/reference/mongodb/bson/typewrapper/tobsontype.xml b/reference/mongodb/bson/typewrapper/tobsontype.xml new file mode 100644 index 0000000000..8542e9a22e --- /dev/null +++ b/reference/mongodb/bson/typewrapper/tobsontype.xml @@ -0,0 +1,159 @@ + + + + + + MongoDB\BSON\TypeWrapper::toBSONType + Converts the BSON type to a PHP value + + + + &reftitle.description; + + abstract public mixedMongoDB\BSON\TypeWrapper::toBSONType + + + + Called during serialization of the object to BSON. The method may return any + PHP value, which will be converted to a BSON. + + + If the class implementing + MongoDB\BSON\TypeWrapper wraps a + MongoDB\BSON\Type object, this method should + likely return the wrapped object. + + + + If this method returns a + MongoDB\BSON\Serializable or another + MongoDB\BSON\TypeWrapper instance, the return + value will be converted accordingly (e.g. + MongoDB\BSON\Serializable::bsonSerialize or + MongoDB\BSON\TypeWrapper::toBSONType 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). + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + A PHP value to be serialized to BSON in place of the + MongoDB\BSON\TypeWrapper object. + + + + + &reftitle.examples; + + <function>MongoDB\BSON\TypeWrapper::toBSONType</function> used to wrap a UTCDateTime + +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"; + +?> +]]> + + &example.outputs.similar; + + + 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" } } +]]> + + + + + + &reftitle.seealso; + + MongoDB\BSON\TypeWrapper::createFromBSONType + + + + + + + diff --git a/reference/mongodb/versions.xml b/reference/mongodb/versions.xml index 01559dca2f..d59397fe1a 100644 --- a/reference/mongodb/versions.xml +++ b/reference/mongodb/versions.xml @@ -131,6 +131,10 @@ + + + +