documentation/manual/en/module_specs/Zend_Json-Objects.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.json.advanced">
   4     <title>Advanced Usage of Zend_Json</title>
   5
   6     <sect2 id="zend.json.advanced.objects1">
   7         <title>JSON Objects</title>
   8
   9         <para>
  10             When encoding <acronym>PHP</acronym> objects as <acronym>JSON</acronym>, all public
  11             properties of that object will be encoded in a <acronym>JSON</acronym> object.
  12         </para>
  13
  14         <para>
  15             <acronym>JSON</acronym> does not allow object references, so care should be taken not to
  16             encode objects with recursive references. If you have issues with
  17             recursion, <methodname>Zend_Json::encode()</methodname> and
  18             <methodname>Zend_Json_Encoder::encode()</methodname> allow an optional second
  19             parameter to check for recursion; if an object is serialized twice, an
  20             exception will be thrown.
  21         </para>
  22
  23         <para>
  24             Decoding <acronym>JSON</acronym> objects poses an additional difficulty, however, since
  25             Javascript objects correspond most closely to <acronym>PHP</acronym>'s associative
  26             array. Some suggest that a class identifier should be passed, and an object
  27             instance of that class should be created and populated with the
  28             key/value pairs of the <acronym>JSON</acronym> object; others feel this could pose a
  29             substantial security risk.
  30         </para>
  31
  32         <para>
  33             By default, <classname>Zend_Json</classname> will decode <acronym>JSON</acronym> objects
  34             as associative arrays. However, if you desire an object returned, you can specify this:
  35         </para>
  36
  37         <programlisting language="php"><![CDATA[
  38 // Decode JSON objects as PHP objects
  39 $phpNative = Zend_Json::decode($encodedValue, Zend_Json::TYPE_OBJECT);
  40 ]]></programlisting>
  41
  42         <para>
  43             Any objects thus decoded are returned as <code>StdClass</code> objects
  44             with properties corresponding to the key/value pairs in the <acronym>JSON</acronym>
  45             notation.
  46         </para>
  47
  48         <para>
  49             The recommendation of Zend Framework is that the individual
  50             developer should decide how to decode <acronym>JSON</acronym> objects. If an object of a
  51             specified type should be created, it can be created in the developer
  52             code and populated with the values decoded using <classname>Zend_Json</classname>.
  53         </para>
  54     </sect2>
  55
  56     <sect2 id="zend.json.advanced.objects2">
  57         <title>Encoding PHP objects</title>
  58
  59         <para>
  60             If you are encoding <acronym>PHP</acronym> objects by default the encoding mechanism
  61             can only access public properties of these objects. When a method
  62             <methodname>toJson()</methodname> is implemented on an object to encode,
  63             <classname>Zend_Json</classname> calls this method and expects the object to return a
  64             <acronym>JSON</acronym> representation of its internal state.
  65         </para>
  66     </sect2>
  67
  68     <sect2 id="zend.json.advanced.internal">
  69         <title>Internal Encoder/Decoder</title>
  70
  71         <para>
  72             <classname>Zend_Json</classname> has two different modes depending if ext/json is
  73             enabled in your <acronym>PHP</acronym> installation or not. If ext/json is installed by
  74             default <methodname>json_encode()</methodname> and
  75             <methodname>json_decode()</methodname> functions are used for encoding and decoding
  76             <acronym>JSON</acronym>. If ext/json is not installed a Zend Framework implementation in
  77             <acronym>PHP</acronym> code is used for en-/decoding. This is considerably slower than
  78             using the <acronym>PHP</acronym> extension, but behaves exactly the same.
  79         </para>
  80
  81         <para>
  82             Still sometimes you might want to use the internal encoder/decoder even
  83             if you have ext/json installed. You can achieve this by calling:
  84         </para>
  85
  86         <programlisting language="php"><![CDATA[
  87 Zend_Json::$useBuiltinEncoderDecoder = true:
  88 ]]></programlisting>
  89     </sect2>
  90
  91     <sect2 id="zend.json.advanced.expr">
  92         <title>JSON Expressions</title>
  93
  94         <para>
  95             Javascript makes heavy use of anonymnous function callbacks, which can be saved
  96             within <acronym>JSON</acronym> object variables. Still they only work if not
  97             returned inside double qoutes, which <classname>Zend_Json</classname> naturally does.
  98             With the Expression support for <classname>Zend_Json</classname> support you can encode
  99             <acronym>JSON</acronym> objects with valid javascript callbacks. This works for both
 100             <methodname>json_encode()</methodname> or the internal encoder.
 101         </para>
 102
 103         <para>
 104             A javascript callback is represented using the <classname>Zend_Json_Expr</classname>
 105             object. It implements the value object pattern and is immutable. You can set the
 106             javascript expression as the first constructor argument. By default
 107             <classname>Zend_Json::encode</classname> does not encode javascript callbacks, you have
 108             to pass the option <code>'enableJsonExprFinder' = true</code> into the
 109             <code>encode</code> function. If enabled the expression support works for all nested
 110             expressions in large object structures. A usage example would look like:
 111         </para>
 112
 113         <programlisting language="php"><![CDATA[
 114 $data = array(
 115     'onClick' => new Zend_Json_Expr('function() {'
 116               . 'alert("I am a valid javascript callback '
 117               . 'created by Zend_Json"); }'),
 118     'other' => 'no expression',
 119 );
 120 $jsonObjectWithExpression = Zend_Json::encode(
 121     $data,
 122     false,
 123     array('enableJsonExprFinder' => true)
 124 );
 125 ]]></programlisting>
 126     </sect2>
 127 </sect1>
 128 <!--
 129 vim:se ts=4 sw=4 et:
 130 -->