Documentation · ViewHelper reference

XSD schema file | vhs 2.1.4

Format / Json / EncodeViewHelper

JSON Encoding ViewHelper

Returns a string containing the JSON representation of the argument. The argument may be any of the following types:

  • arrays, associative and traditional
  • DomainObjects
  • arrays containing DomainObjects
  • ObjectStorage containing DomainObjects
  • standard types (string, integer, boolean, float, NULL)
  • DateTime including ones found as property values on DomainObjects

Recursion protection is enabled for DomainObjects with the option to add a special marker (any variable type above also supported here) which is inserted where an object which would cause recursion would be placed.

Be specially careful when you JSON encode DomainObjects which have recursive relations to itself using either 1:n or m:n - in this case the one member of the converted relation will be whichever value you specified as "recursionMarker" - or the default value, NULL. When using the output of such conversion in JavaScript please make sure you check the type before assuming that every member of a converted 1:n or m:n recursive relation is in fact a JavaScript. Not doing so may result in fatal JavaScript errors in the client browser.

  • Tag usage example

    <v:format.json.encode value="[mixed]" useTraversableKeys="1" preventRecursion="1" recursionMarker="[mixed]" dateTimeFormat="NULL">
    	<!-- tag content - may be ignored! -->
  • Inline usage example

    {v:format.json.encode(value: [mixed], useTraversableKeys: 1, preventRecursion: 1, recursionMarker: [mixed], dateTimeFormat: 'NULL')}


Argument Description Type

A date() format for converting DateTime values to JSON-compatible values. NULL means JS UNIXTIME (time()*1000)


If FALSE, allows recursion to occur which could potentially be fatal to the output unless managed


Any value - string, integer, boolean, object or NULL - inserted instead of recursive instances of objects


If TRUE, preserves keys from Traversables converted to arrays. Not recommended for ObjectStorages!


Array or Traversable

Required attribute

Revision history

commit c0e023b7fb66afd124e163f76ed6b438f2a26cb4
Author: Bjoern Fromme <*****>
Date:   Thu Jan 17 18:11:29 2013 +0100

    [FEATURE] Add JSON de-/encode ViewHelpers

commit d87e3fc7176561a83b29db9c052bfb87dc5474dd
Author: Claus Due <*****>
Date:   Thu Jan 17 23:06:35 2013 +0100

    [TASK] Whitespace fix, Format / Json / Encode ViewHelper

commit 57a014382682c2b2eba8a859966b27be99a5a825
Author: Claus Due <*****>
Date:   Thu Jan 17 23:06:57 2013 +0100

    [FEATURE] Support Traversable in Format / Json / Encode ViewHelper

commit d07dba17753b28304882ff5c41eec31a077db4c9
Author: Claus Due <*****>
Date:   Thu Jan 17 23:11:05 2013 +0100

    [DOC] Description of argument "value" on Format / Json / Encode ViewHelper

commit d0ca970f4cfad16a5e88b360de75e9d94bacfb24
Author: Claus Due <*****>
Date:   Thu Jan 17 23:14:52 2013 +0100

    [FEATURE] Add "useTraversableKeys" attribute on Format / Json / Encode

commit a57aee5ad1b966580b387eafa8b1c4c30e834212
Author: Claus Due <*****>
Date:   Thu Jan 17 23:22:36 2013 +0100

    [DOC] A*****@throws annotation on Format / Json / Encode ViewHelper

commit 10b721c8463535ca50ee605eb74c52a23407f575
Author: Claus Due <*****>
Date:   Fri Jan 18 00:05:11 2013 +0100

    [FEATURE] Support for DomainObject and Traversable, Format / Json / Encode
    Also added is recursion support which also works on any instances of standard arrays containing DomainObjects - for example in the `{queryResult -> v:call('toArray') -> v:format.json.encode()}` use case.

commit bed70aad6db29d91d8273a23aff1f67d900076ac
Author: Claus Due <*****>
Date:   Fri Jan 18 00:05:52 2013 +0100

    [DOC] Elaborated class doc comment for Format / Json / Encode ViewHelper

commit 90b01a0d76272933abbbbe65c764de09e78c1f05
Author: Claus Due <*****>
Date:   Fri Jan 18 00:15:18 2013 +0100

    [FEATURE] DateTime support in Format / Json / Encode ViewHelper

commit 55ebfdc65f2ae8c783a402daad51e0e53313379e
Author: Claus Due <*****>
Date:   Fri Jan 18 00:26:04 2013 +0100

    [FEATURE] DateTime formatting in Format / Json / Encode ViewHelper

commit 2fd11485121733561e46f1504a758d0d065ca267
Author: Bjoern Fromme <*****>
Date:   Fri Jan 18 13:22:14 2013 +0100

    [BUGFIX] Fix recursion running into an endless loop

commit 4c5da85558937bf82a19da2e723e6388c6703875
Author: Bjoern Fromme <*****>
Date:   Fri Jan 18 15:51:18 2013 +0100

    [TASK] Add unit tests for JSON ViewHelper

commit db3cd7ddbffc430b6a108159cfc70dbe141e5410
Author: Claus Due <*****>
Date:   Fri Sep 13 03:08:34 2013 +0200

    [TASK] Improve test suite

commit da31bad1d9bb058c072ddb5591e8ed907a1ae8e1
Author: Claus Due <*****>
Date:   Tue Dec 31 23:08:37 2013 +0100

    [TASK] Happy new year!

commit f6652d336a9e7960d906df6230d32eb15793cee7
Author: Danilo Bürger <*****>
Date:   Fri Nov 1 23:12:27 2013 +0100

    [TASK] CGL compatibility for v:format.json.encode

commit d2e531da034976e6db1478eef5a8478595fd16fe
Author: Claus Due <*****>
Date:   Sun Jan 5 00:45:10 2014 +0100

    [TASK] Migrate to using namespace core class names

commit 52bd6e41ccfef3d8193b350153912a9716e6a087
Author: Benjamin Rau <*****>
Date:   Tue Apr 1 21:09:00 2014 +0200

    [TASK] CGL compliance

commit da7677bc74f14e9a9300e4ba4487e52c3cb97642
Author: Claus Due <*****>
Date:   Sun Apr 20 01:13:33 2014 +0200

    [TASK] Switch to namespaces

commit 4c3fcd838973e6203eeb7e36bd08df27b1769e3e
Author: Claus Due <*****>
Date:   Sat Jan 10 07:07:55 2015 +0100

    [TASK] Use more compatible JSON encode values
    Since increasing minimum required PHP version these can be used.

commit 8bb2fc5ee124ba19b0a0ab8e061c9a153fc4651f
Author: Xaver Maierhofer <*****>
Date:   Sun Jan 18 17:56:13 2015 +0100

    [TASK] Reference Copyright to file