Merge pull request #7 from GeeH/hotfix/added-docs

Added base documentation

doc/book/zend.json.basics.md

@@ -0,0 +1,29 @@
+# Basic Usage
+
+Usage of `Zend\Json` involves using the two public static methods available:
+`Zend\Json\Json::encode()` and `Zend\Json\Json::decode()`.
+
+```php
+// Retrieve a value:
+$phpNative = Zend\Json\Json::decode($encodedValue);
+
+// Encode it to return to the client:
+$json = Zend\Json\Json::encode($phpNative);
+```
+
+## Pretty-printing JSON
+
+Sometimes, it may be hard to explore *JSON* data generated by `Zend\Json\Json::encode()`, since it
+has no spacing or indentation. In order to make it easier, `Zend\Json\Json` allows you to
+pretty-print *JSON* data in the human-readable format with `Zend\Json\Json::prettyPrint()`.
+
+```php
+// Encode it to return to the client:
+$json = Zend\Json\Json::encode($phpNative);
+if ($debug) {
+    echo Zend\Json\Json::prettyPrint($json, array("indent" => " "));
+}
+```
+
+Second optional argument of `Zend\Json\Json::prettyPrint()` is an option array. Option `indent`
+allows to set indentation string - by default it's a single tab character.

doc/book/zend.json.introduction.md

@@ -0,0 +1,16 @@
+# Introduction
+
+`Zend\Json` provides convenience methods for serializing native *PHP* to *JSON* and decoding *JSON*
+to native *PHP*. For more information on *JSON*, [visit the JSON project
+site](http://www.json.org/).
+
+*JSON*, JavaScript Object Notation, can be used for data interchange between JavaScript and other
+languages. Since *JSON* can be directly evaluated by JavaScript, it is a more efficient and
+lightweight format than *XML* for exchanging data with JavaScript clients.
+
+In addition, `Zend\Json` provides a useful way to convert any arbitrary *XML* formatted string into
+a *JSON* formatted string. This built-in feature will enable *PHP* developers to transform the
+enterprise data encoded in *XML* format into *JSON* format before sending it to browser-based Ajax
+client applications. It provides an easy way to do dynamic data conversion on the server-side code
+thereby avoiding unnecessary *XML* parsing in the browser-side applications. It offers a nice
+utility function that results in easier application-specific data processing techniques.

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)
+);
+```