update v1.0.7.9 R.C.

This is a Release Candidate. We are still testing.

vendor/zendframework/zend-json/doc/book/zend.json.objects.md

@@ -0,0 +1,101 @@
+# Advanced Usage
+
+## JSON Objects
+
+When encoding *PHP* objects as *JSON*, all public properties of that object will be encoded in a
+*JSON* object.
+
+*JSON* does not allow object references, so care should be taken not to encode objects with
+recursive references. If you have issues with recursion, `Zend\Json\Json::encode()` and
+`Zend\Json\Encoder::encode()` allow an optional second parameter to check for recursion; if an
+object is serialized twice, an exception will be thrown.
+
+Decoding *JSON* objects poses an additional difficulty, however, since JavaScript objects correspond
+most closely to *PHP*'s associative array. Some suggest that a class identifier should be passed,
+and an object instance of that class should be created and populated with the key/value pairs of the
+*JSON* object; others feel this could pose a substantial security risk.
+
+By default, `Zend\Json\Json` will decode *JSON* objects as `stdClass` objects. However, if you
+desire an associative array returned, you can specify this:
+
+```php
+// Decode JSON objects as PHP array
+$phpNative = Zend\Json\Json::decode($encodedValue, Zend\Json\Json::TYPE_ARRAY);
+```
+
+Any objects thus decoded are returned as associative arrays with keys and values corresponding to
+the key/value pairs in the *JSON* notation.
+
+The recommendation of Zend Framework is that the individual developer should decide how to decode
+*JSON* objects. If an object of a specified type should be created, it can be created in the
+developer code and populated with the values decoded using `Zend\Json`.
+
+## Encoding PHP objects
+
+If you are encoding *PHP* objects by default the encoding mechanism can only access public
+properties of these objects. When a method `toJson()` is implemented on an object to encode,
+`Zend\Json\Json` calls this method and expects the object to return a *JSON* representation of its
+internal state.
+
+`Zend\Json\Json` can encode PHP objects recursively but does not do so by default. This can be
+enabled by passing `true` as a second argument to `Zend\Json\Json::encode()`.
+
+```php
+// Encode PHP object recursively
+$jsonObject = Zend\Json\Json::encode($data, true);
+```
+
+When doing recursive encoding of objects, as JSON does not support cycles, an
+`Zend\Json\Exception\RecursionException` will be thrown. If you wish, you can silence these
+exceptions by passing the `silenceCyclicalExceptions` option:
+
+```php
+$jsonObject = Zend\Json\Json::encode(
+    $data,
+    true,
+    array('silenceCyclicalExceptions' => true)
+);
+```
+
+## Internal Encoder/Decoder
+
+`Zend\Json` has two different modes depending if ext/json is enabled in your *PHP* installation or
+not. If ext/json is installed by default `json_encode()` and `json_decode()` functions are used for
+encoding and decoding *JSON*. If ext/json is not installed a Zend Framework implementation in *PHP*
+code is used for en-/decoding. This is considerably slower than using the *PHP* extension, but
+behaves exactly the same.
+
+Still sometimes you might want to use the internal encoder/decoder even if you have ext/json
+installed. You can achieve this by calling:
+
+```php
+Zend\Json\Json::$useBuiltinEncoderDecoder = true;
+```
+
+## JSON Expressions
+
+JavaScript makes heavy use of anonymous function callbacks, which can be saved within *JSON* object
+variables. Still they only work if not returned inside double quotes, which `Zend\Json` naturally
+does. With the Expression support for `Zend\Json` support you can encode *JSON* objects with valid
+JavaScript callbacks. This works for both `json_encode()` or the internal encoder.
+
+A JavaScript callback is represented using the `Zend\Json\Expr` object. It implements the value
+object pattern and is immutable. You can set the JavaScript expression as the first constructor
+argument. By default `Zend\Json\Json::encode` does not encode JavaScript callbacks, you have to pass
+the option `enableJsonExprFinder` and set it to `TRUE` into the `encode` function. If enabled the
+expression support works for all nested expressions in large object structures. A usage example
+would look like:
+
+```php
+$data = array(
+    'onClick' => new Zend\Json\Expr('function() {'
+              . 'alert("I am a valid JavaScript callback '
+              . 'created by Zend\Json"); }'),
+    'other' => 'no expression',
+);
+$jsonObjectWithExpression = Zend\Json\Json::encode(
+    $data,
+    false,
+    array('enableJsonExprFinder' => true)
+);
+```