<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ --> 

<refentry xml:id="function.mongodb.bson-tojson" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoDB\BSON\toJSON</refname>
  <refpurpose>Returns the Legacy Extended JSON representation of a BSON value</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <warning>
   <para>
    This function has been <emphasis>DEPRECATED</emphasis> as of extension
    version 1.20.0 and will be removed in 2.0. Applications should use
    <methodname>MongoDB\BSON\Document::toCanonicalExtendedJSON</methodname> or
    <methodname>MongoDB\BSON\Document::toRelaxedExtendedJSON</methodname>
    instead.
   </para>
  </warning>
 </refsynopsisdiv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>MongoDB\BSON\toJSON</methodname>
   <methodparam><type>string</type><parameter>bson</parameter></methodparam>
  </methodsynopsis>
  <para>
   Converts a BSON string to its
   <link xlink:href="&url.mongodb.docs.extendedjson;">Legacy Extended JSON</link>
   representation.
  </para>
  <note>
   <simpara>
    There exist several JSON formats for representing BSON. This function
    implements the "strict mode" defined in
    <link xlink:href="&url.mongodb.docs.extendedjson;">MongoDB Extended JSON</link>,
    which has been superseded by the canonical and relaxed formats defined in
    the
    <link xlink:href="&url.mongodb.specs.extendedjson;">Extended JSON Specification</link>
    and implemented by <function>MongoDB\BSON\toCanonicalExtendedJSON</function>
    and <function>MongoDB\BSON\toRelaxedExtendedJSON</function>, respectively.
   </simpara>
  </note>
  <warning>
   <simpara>
    <link xlink:href="&url.json;">JSON</link> does not support
    <link linkend="language.types.float.nan"><constant>NAN</constant></link> and
    <link linkend="function.is-infinite"><constant>INF</constant></link> and
    MongoDB&apos;s Legacy Extended JSON format does not define an alternative
    representation for these values
    (<link xlink:href="&url.mongodb.libbson;">libbson</link> will output
    <literal>nan</literal> and <literal>inf</literal> literals, which may not be
    parsed as valid JSON). If you are working with BSON that may contain
    non-finite numbers, please use
    <function>MongoDB\BSON\toCanonicalExtendedJSON</function> or
    <function>MongoDB\BSON\toRelaxedExtendedJSON</function>.
   </simpara>
  </warning>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>bson</parameter> (<type>string</type>)</term>
    <listitem>
     <para>
      BSON value to be converted.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   The converted JSON value.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simplelist>
   &mongodb.throws.bson.unexpected;
  </simplelist>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><function>MongoDB\BSON\toJSON</function> example</title>
   <programlisting role="php">
<![CDATA[
<?php

$documents = [
    [ 'null' => null ],
    [ 'boolean' => true ],
    [ 'string' => 'foo' ],
    [ 'int32' => 123 ],
    [ 'int64' => 4294967295 ],
    [ 'double' => 1.0, ],
    [ 'nan' => NAN ],
    [ 'pos_inf' => INF ],
    [ 'neg_inf' => -INF ],
    [ 'array' => [ 'foo', 'bar' ]],
    [ 'document' => [ 'foo' => 'bar' ]],
    [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
    [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
    [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
    [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
    [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
    [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
    [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
    [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
    [ 'minkey' => new MongoDB\BSON\MinKey ],
    [ 'maxkey' => new MongoDB\BSON\MaxKey ],
];

foreach ($documents as $document) {
    $bson = MongoDB\BSON\fromPHP($document);
    echo MongoDB\BSON\toJSON($bson), "\n";
}

?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
{ "null" : null }
{ "boolean" : true }
{ "string" : "foo" }
{ "int32" : 123 }
{ "int64" : 4294967295 }
{ "double" : 1.0 }
{ "nan" : nan }
{ "pos_inf" : inf }
{ "neg_inf" : -inf }
{ "array" : [ "foo", "bar" ] }
{ "document" : { "foo" : "bar" } }
{ "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
{ "dec128" : { "$numberDecimal" : "1234.5678" } }
{ "binary" : { "$binary" : "Zm9v", "$type" : "00" } }
{ "date" : { "$date" : 1445990400000 } }
{ "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
{ "regex" : { "$regex" : "pattern", "$options" : "i" } }
{ "code" : { "$code" : "function() { return 1; }" } }
{ "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
{ "minkey" : { "$minKey" : 1 } }
{ "maxkey" : { "$maxKey" : 1 } }
]]>
   </screen>
  </example>
 </refsect1>


 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>MongoDB\BSON\fromJSON</function></member>
   <member><function>MongoDB\BSON\toCanonicalExtendedJSON</function></member>
   <member><function>MongoDB\BSON\toRelaxedExtendedJSON</function></member>
   <member><link xlink:href="&url.mongodb.docs.extendedjson;">MongoDB Extended JSON</link></member>
   <member><link xlink:href="&url.mongodb.docs.bson;">MongoDB BSON</link></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
-->