Prepared documentation for publication

- Renamed files
- Edited all files
- Added migration guide
- Removed bookdown artifacts
- Added mkdocs configuration
- Added documentation build automation

.travis.yml

@@ -10,6 +10,16 @@ branches:
 cache:
   directories:
     - $HOME/.composer/cache
+    - $HOME/.local
+    - zf-mkdoc-theme
+
+env:
+  global:
+    - SITE_URL=https://zendframework.github.io/zend-json
+    - GH_USER_NAME="Matthew Weier O'Phinney"
+    - GH_USER_EMAIL=matthew@weierophinney.net
+    - GH_REF=github.com/zendframework/zend-json.git
+    - secure: "XP/GRTnJ2XM5C4sNDxhMcKpA9g8g8st8VKm9aev01QOQiQYtc8kgpV3L+eb7+juxHD3C6DKjfHliMnmT51PYBzSDi5JTiiECThljSlnOtfaeYQJftys5f94cHt2jFH4JzbbhIGgkMXbpNNCs+/nbL1P8DFju7GfzQM2iDwJJT7RfMlrv3pafRhfADfScIFqH4qEIHXQV0pnclPPsnAmE29PKsKwkt61nxS8j7n6ylFcuZ5e8JbOD92FL2HVVdeiQMPmX0T3ac6HZReS6qsxMvdSas/1+LyFmVSTAhRQnncNtZKOT8QiemPIwaaf/9PQooDMMWPJCn65LaiQ8YKNAes5O7YIyYddQbK0ulyFvfxDrMGW8GuEFj2xVVWQZ1o70+XK19znzCvkv1bCeicrpVxcsq35N7pYZk1HyyJ4ZTkBhNyIPHgKUqomT6uPrXlOLBov5mWcvdgqsa6PGVNlkWpp5Q426lLrHJIV9NS27ZqKq6/tFn3bhkUclknS/U5v/AD7PgaN+lJbFLyKnPeFCIyVqfqiXeKXNC8kez4rDJybvp/oimZzXrNATEyHTnrC3yNo3hJpAX3THES4uC8yVHqBJdCJCIiDt0zkiC9Z/tGXZZsE6Bop4sOtq+bCTpOYNlibfipxXchX/ccGd/4dQoceVGx7i0ETAojPgPd78mtk="
 
 matrix:
   fast_finish: true
@@ -20,6 +30,8 @@ matrix:
     - php: 5.6
       env:
         - EXECUTE_TEST_COVERALLS=true
+        - DEPLOY_DOCS="$(if [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then echo -n 'true' ; else echo -n 'false' ; fi)"
+        - PATH="$HOME/.local/bin:$PATH"
     - php: 7
     - php: hhvm 
   allow_failures:
@@ -41,6 +53,10 @@ script:
   - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then composer test-coverage ; fi
   - if [[ $EXECUTE_TEST_COVERALLS != 'true' ]]; then composer test ; fi
   - if [[ $EXECUTE_CS_CHECK == 'true' ]]; then composer cs-check ; fi
+  - if [[ $DEPLOY_DOCS == "true" && "$TRAVIS_TEST_RESULT" == "0" ]]; then wget -O theme-installer.sh "https://raw.githubusercontent.com/zendframework/zf-mkdoc-theme/master/theme-installer.sh" ; chmod 755 theme-installer.sh ; ./theme-installer.sh ; fi
+
+after_success:
+  - if [[ $DEPLOY_DOCS == "true" ]]; then echo "Preparing to build and deploy documentation" ; ./zf-mkdoc-theme/deploy.sh ; echo "Completed deploying documentation" ; fi
 
 after_script:
   - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then composer upload-coverage ; fi

doc/book/advanced.md

@@ -0,0 +1,113 @@
+# 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()` each allow an
+optional second parameter to check for recursion; if an object is serialized
+twice, an exception will be thrown.
+
+Decoding JSON objects poses 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 request it using
+the second argument to `decode()`:
+
+```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, the default 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 the 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, a
+`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,
+    ['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, zend-json will use the
+`json_encode()` and `json_decode()` functions 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.
+
+Sometimes you might want to use the zend-json 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. They only work if not returned inside double
+quotes, which zend-json implements by default. With the Expression support for
+zend-json, you can encode JSON objects with valid JavaScript callbacks.
+This works when either `json_encode()` or the internal encoder is used.
+
+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` when calling the
+`encode()` method. If enabled, the expression support works for all nested
+expressions in large object structures.
+
+As an example:
+
+```php
+$data = [
+    '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,
+    ['enableJsonExprFinder' => true]
+);
+```

doc/book/basics.md

@@ -0,0 +1,41 @@
+# Basic Usage
+
+Usage of zend-json involves using two public static methods:
+`Zend\Json\Json::encode()` and `Zend\Json\Json::decode()`.
+
+```php
+// Decode a JSON value to PHP:
+$phpNative = Zend\Json\Json::decode($encodedValue);
+
+// Encode a PHP value to JSON:
+$json = Zend\Json\Json::encode($phpNative);
+```
+
+> ## ext/json
+>
+> By default, the above two calls will proxy to the `json_decode()` and
+> `json_encode()` functions of `ext/json`, which is bundled in default
+> installations of PHP. Using zend-json, however, ensures that the functionality
+> works regardless of whether or not the extension is available. Additionally,
+> the component provides some features not found in `ext/json`, such as
+> encoding native JSON expressions, communicating class inheritance, and
+> customizations around pretty printing.
+
+## 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' => ' '));
+}
+```
+
+The second, optional, argument to `Zend\Json\Json::prettyPrint()` is an option
+array. Option `indent` allows providing an indentation string; by default, it
+uses four spaces.

doc/book/index.html

@@ -0,0 +1,10 @@
+<div class="container">
+  <div class="jumbotron">
+    <h1>zend-json</h1>
+
+    <p>De/Serialize JSON in PHP, including JavaScript expressions.</p>
+
+    <pre><code class="language-bash">$ composer require zendframework/zend-json</code></pre>
+  </div>
+</div>
+

doc/book/index.md

@@ -0,0 +1 @@
+../../README.md

doc/book/intro.md

@@ -0,0 +1,10 @@
+# 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.

doc/book/migration/v2-to-v3.md

@@ -0,0 +1,31 @@
+# Migrating from v2 to v3
+
+Version 3 is the first significant departure in the zend-json API. In
+particular, it features the removal of two features to new packages.
+
+## zend-json-server
+
+The `Zend\Json\Server` subcomponent was extracted to a new component,
+[zend-json-server](https://zendframework.github.io/zend-json-server). Install it
+using:
+
+```bash
+$ composer install zendframework/zend-json-server
+```
+
+All classes and functionality remain the same as in previous versions of
+zend-json.
+
+## XML to JSON support
+
+v2 releases of zend-json provided `Zend\Json\Json::fromXml()`, which could be
+used to convert an XML document to JSON. This functionality has been extracted
+to a new component, [zend-xml2json](https://zendframework.github.io/zend-xml2json).
+Install it using:
+
+```bash
+$ composer install zendframework/zend-xml2json
+```
+
+In order to use the functionality, you will need to modify your calls from
+`Zend\Json\Json::fromXml()` to instead use `Zend\Xml2Json\Xml2Json::fromXml()`.