Skip to content

Commit 3c84b02

Browse files
jmikolaGirgias
jmikola
and
Girgias
authored
PackedArray::fromJSON() and toJSON methods (#3806)
https://jira.mongodb.org/browse/PHPC-2350 * Remove trailing commas from Document toJSON examples * Add returnvalues sections for Document and PackedArray from/to methods * Clarify errors for Document and PackedArray fromJSON() methods --------- Co-authored-by: Gina Peter Banyard <[email protected]>
1 parent 0581484 commit 3c84b02

File tree

10 files changed

+382
-3
lines changed

10 files changed

+382
-3
lines changed

‎reference/mongodb/bson/document/frombson.xml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,13 @@
2929
</variablelist>
3030
</refsect1>
3131

32+
<refsect1 role="returnvalues">
33+
&reftitle.returnvalues;
34+
<para>
35+
Returns a new <classname>MongoDB\BSON\Document</classname> instance.
36+
</para>
37+
</refsect1>
38+
3239
<refsect1 role="errors">
3340
&reftitle.errors;
3441
<simplelist>

‎reference/mongodb/bson/document/fromjson.xml

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,11 +34,23 @@
3434
</variablelist>
3535
</refsect1>
3636

37+
<refsect1 role="returnvalues">
38+
&reftitle.returnvalues;
39+
<para>
40+
Returns a new <classname>MongoDB\BSON\Document</classname> instance.
41+
</para>
42+
</refsect1>
43+
3744
<refsect1 role="errors">
3845
&reftitle.errors;
3946
<simplelist>
4047
&mongodb.throws.argumentparsing;
41-
<member>Throws <classname>MongoDB\Driver\Exception\UnexpectedValueException</classname> if <parameter>json</parameter> is not a valid document.</member>
48+
<member>
49+
Throws
50+
<classname>MongoDB\Driver\Exception\UnexpectedValueException</classname> if
51+
the JSON value cannot be converted to a BSON document (e.g. due to a syntax
52+
error).
53+
</member>
4254
</simplelist>
4355
</refsect1>
4456

‎reference/mongodb/bson/document/fromphp.xml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,13 @@
3131
</variablelist>
3232
</refsect1>
3333

34+
<refsect1 role="returnvalues">
35+
&reftitle.returnvalues;
36+
<para>
37+
Returns a new <classname>MongoDB\BSON\Document</classname> instance.
38+
</para>
39+
</refsect1>
40+
3441
<refsect1 role="errors">
3542
&reftitle.errors;
3643
<simplelist>

‎reference/mongodb/bson/document/tocanonicalextendedjson.xml

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,15 @@
2828
&no.function.parameters;
2929
</refsect1>
3030

31+
<refsect1 role="returnvalues">
32+
&reftitle.returnvalues;
33+
<para>
34+
Returns a string containing the
35+
<link xlink:href="&url.mongodb.specs.extendedjson;#canonical-extended-json-example">Canonical Extended JSON</link>
36+
representation of the BSON document.
37+
</para>
38+
</refsect1>
39+
3140
<refsect1 role="examples">
3241
&reftitle.examples;
3342
<example>
@@ -42,7 +51,7 @@ $documents = [
4251
[ 'string' => 'foo' ],
4352
[ 'int32' => 123 ],
4453
[ 'int64' => 4294967295 ],
45-
[ 'double' => 1.0, ],
54+
[ 'double' => 1.0 ],
4655
[ 'nan' => NAN ],
4756
[ 'pos_inf' => INF ],
4857
[ 'neg_inf' => -INF ],

‎reference/mongodb/bson/document/torelaxedextendedjson.xml

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,15 @@
2727
&no.function.parameters;
2828
</refsect1>
2929

30+
<refsect1 role="returnvalues">
31+
&reftitle.returnvalues;
32+
<para>
33+
Returns a string containing the
34+
<link xlink:href="&url.mongodb.specs.extendedjson;#relaxed-extended-json-example">Relaxed Extended JSON</link>
35+
representation of the BSON document.
36+
</para>
37+
</refsect1>
38+
3039
<refsect1 role="examples">
3140
&reftitle.examples;
3241
<example>
@@ -41,7 +50,7 @@ $documents = [
4150
[ 'string' => 'foo' ],
4251
[ 'int32' => 123 ],
4352
[ 'int64' => 4294967295 ],
44-
[ 'double' => 1.0, ],
53+
[ 'double' => 1.0 ],
4554
[ 'nan' => NAN ],
4655
[ 'pos_inf' => INF ],
4756
[ 'neg_inf' => -INF ],

‎reference/mongodb/bson/packedarray/fromjson.xml

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
<refentry xml:id="mongodb-bson-packedarray.fromjson" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4+
<refnamediv>
5+
<refname>MongoDB\BSON\PackedArray::fromJSON</refname>
6+
<refpurpose>Construct a new BSON array instance from a JSON string</refpurpose>
7+
</refnamediv>
8+
9+
<refsect1 role="description">
10+
&reftitle.description;
11+
<methodsynopsis>
12+
<modifier>final</modifier> <modifier>static</modifier> <modifier>public</modifier> <type>MongoDB\BSON\PackedArray</type><methodname>MongoDB\BSON\PackedArray::fromJSON</methodname>
13+
<methodparam><type>string</type><parameter>json</parameter></methodparam>
14+
</methodsynopsis>
15+
<para>
16+
Converts an
17+
<link xlink:href="&url.mongodb.docs.extendedjson;">extended JSON</link>
18+
string to its BSON representation.
19+
</para>
20+
</refsect1>
21+
22+
<refsect1 role="parameters">
23+
&reftitle.parameters;
24+
<variablelist>
25+
<varlistentry>
26+
<term><parameter>json</parameter> (<type>string</type>)</term>
27+
<listitem>
28+
<para>
29+
JSON value to be converted.
30+
</para>
31+
</listitem>
32+
</varlistentry>
33+
</variablelist>
34+
</refsect1>
35+
36+
<refsect1 role="returnvalues">
37+
&reftitle.returnvalues;
38+
<para>
39+
Returns a new <classname>MongoDB\BSON\PackedArray</classname> instance.
40+
</para>
41+
</refsect1>
42+
43+
<refsect1 role="errors">
44+
&reftitle.errors;
45+
<simplelist>
46+
&mongodb.throws.argumentparsing;
47+
<member>
48+
Throws
49+
<classname>MongoDB\Driver\Exception\UnexpectedValueException</classname> if
50+
the JSON value cannot be converted to a BSON array (e.g. due to a syntax
51+
error).
52+
</member>
53+
</simplelist>
54+
</refsect1>
55+
56+
<refsect1 role="examples">
57+
&reftitle.examples;
58+
<example>
59+
<title><methodname>MongoDB\BSON\PackedArray::fromJSON</methodname> example</title>
60+
<programlisting role="php">
61+
<![CDATA[
62+
<?php
63+
64+
$json = '[ "foo", { "$numberInt" : "123" }, { "$numberLong" : "4294967295" }, { "$oid" : "56315a7c6118fd1b920270b1" } ]';
65+
$packedArray = MongoDB\BSON\PackedArray::fromJSON($json);
66+
var_dump($packedArray);
67+
68+
?>
69+
]]>
70+
</programlisting>
71+
&example.outputs;
72+
<screen>
73+
<![CDATA[
74+
object(MongoDB\BSON\PackedArray)#1 (2) {
75+
["data"]=>
76+
string(68) "MQAAAAIwAAQAAABmb28AEDEAewAAABIyAP////8AAAAABzMAVjFafGEY/RuSAnCxAA=="
77+
["value"]=>
78+
array(4) {
79+
[0]=>
80+
string(3) "foo"
81+
[1]=>
82+
int(123)
83+
[2]=>
84+
int(4294967295)
85+
[3]=>
86+
object(MongoDB\BSON\ObjectId)#2 (1) {
87+
["oid"]=>
88+
string(24) "56315a7c6118fd1b920270b1"
89+
}
90+
}
91+
}
92+
]]>
93+
</screen>
94+
</example>
95+
</refsect1>
96+
97+
<refsect1 role="seealso">
98+
&reftitle.seealso;
99+
<simplelist>
100+
<member><methodname>MongoDB\BSON\PackedArray::fromPHP</methodname></member>
101+
<member><link xlink:href="&url.mongodb.docs.extendedjson;">MongoDB Extended JSON</link></member>
102+
<member><link xlink:href="&url.mongodb.docs.bson;">BSON Types</link></member>
103+
</simplelist>
104+
</refsect1>
105+
106+
</refentry>
107+
<!-- Keep this comment at the end of the file
108+
Local variables:
109+
mode: sgml
110+
sgml-omittag:t
111+
sgml-shorttag:t
112+
sgml-minimize-attributes:nil
113+
sgml-always-quote-attributes:t
114+
sgml-indent-step:1
115+
sgml-indent-data:t
116+
indent-tabs-mode:nil
117+
sgml-parent-document:nil
118+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
119+
sgml-exposed-tags:nil
120+
sgml-local-catalogs:nil
121+
sgml-local-ecat-files:nil
122+
End:
123+
vim600: syn=xml fen fdm=syntax fdl=2 si
124+
vim: et tw=78 syn=sgml
125+
vi: ts=1 sw=1
126+
-->

‎reference/mongodb/bson/packedarray/fromphp.xml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,13 @@
3030
</variablelist>
3131
</refsect1>
3232

33+
<refsect1 role="returnvalues">
34+
&reftitle.returnvalues;
35+
<para>
36+
Returns a new <classname>MongoDB\BSON\PackedArray</classname> instance.
37+
</para>
38+
</refsect1>
39+
3340
<refsect1 role="errors">
3441
&reftitle.errors;
3542
<simplelist>

‎reference/mongodb/bson/packedarray/tocanonicalextendedjson.xml

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
<refentry xml:id="mongodb-bson-packedarray.tocanonicalextendedjson" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4+
<refnamediv>
5+
<refname>MongoDB\BSON\PackedArray::toCanonicalExtendedJSON</refname>
6+
<refpurpose>Returns the Canonical Extended JSON representation of the BSON array</refpurpose>
7+
</refnamediv>
8+
9+
<refsect1 role="description">
10+
&reftitle.description;
11+
<methodsynopsis>
12+
<modifier>final</modifier> <modifier>public</modifier> <type>string</type><methodname>MongoDB\BSON\PackedArray::toCanonicalExtendedJSON</methodname>
13+
<void/>
14+
</methodsynopsis>
15+
<para>
16+
Converts the BSON array to its
17+
<link xlink:href="&url.mongodb.specs.extendedjson;#canonical-extended-json-example">Canonical Extended JSON</link>
18+
representation. The canonical format prefers type fidelity at the expense of
19+
concise output and is most suited for producing output that can be converted
20+
back to BSON without any loss of type information (e.g. numeric types will
21+
remain differentiated).
22+
</para>
23+
</refsect1>
24+
25+
<refsect1 role="parameters">
26+
&reftitle.parameters;
27+
&no.function.parameters;
28+
</refsect1>
29+
30+
<refsect1 role="returnvalues">
31+
&reftitle.returnvalues;
32+
<para>
33+
Returns a string containing the
34+
<link xlink:href="&url.mongodb.specs.extendedjson;#canonical-extended-json-example">Canonical Extended JSON</link>
35+
representation of the BSON array.
36+
</para>
37+
</refsect1>
38+
39+
<refsect1 role="examples">
40+
&reftitle.examples;
41+
<example>
42+
<title><methodname>MongoDB\BSON\PackedArray::toCanonicalExtendedJSON</methodname> example</title>
43+
<programlisting role="php">
44+
<![CDATA[
45+
<?php
46+
47+
$array = [
48+
'foo',
49+
123,
50+
4294967295,
51+
new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1'),
52+
];
53+
54+
$packedArray = MongoDB\BSON\PackedArray::fromPHP($array);
55+
echo $packedArray->toCanonicalExtendedJSON(), "\n";
56+
57+
?>
58+
]]>
59+
</programlisting>
60+
&example.outputs;
61+
<screen>
62+
<![CDATA[
63+
[ "foo", { "$numberInt" : "123" }, { "$numberLong" : "4294967295" }, { "$oid" : "56315a7c6118fd1b920270b1" } ]
64+
]]>
65+
</screen>
66+
</example>
67+
</refsect1>
68+
69+
<refsect1 role="seealso">
70+
&reftitle.seealso;
71+
<simplelist>
72+
<member><methodname>MongoDB\BSON\PackedArray::fromJSON</methodname></member>
73+
<member><methodname>MongoDB\BSON\PackedArray::toRelaxedExtendedJSON</methodname></member>
74+
<member><function>MongoDB\BSON\toCanonicalExtendedJSON</function></member>
75+
<member><link xlink:href="&url.mongodb.specs.extendedjson;">Extended JSON Specification</link></member>
76+
<member><link xlink:href="&url.mongodb.docs.bson;">BSON Types</link></member>
77+
</simplelist>
78+
</refsect1>
79+
80+
</refentry>
81+
<!-- Keep this comment at the end of the file
82+
Local variables:
83+
mode: sgml
84+
sgml-omittag:t
85+
sgml-shorttag:t
86+
sgml-minimize-attributes:nil
87+
sgml-always-quote-attributes:t
88+
sgml-indent-step:1
89+
sgml-indent-data:t
90+
indent-tabs-mode:nil
91+
sgml-parent-document:nil
92+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
93+
sgml-exposed-tags:nil
94+
sgml-local-catalogs:nil
95+
sgml-local-ecat-files:nil
96+
End:
97+
vim600: syn=xml fen fdm=syntax fdl=2 si
98+
vim: et tw=78 syn=sgml
99+
vi: ts=1 sw=1
100+
-->

0 commit comments

Comments
 (0)