Using a Reviver Function with JSON.parse

Earlier we demonstrated and described the use of JavaScript's JSON.parse method. On this page we continue the discussion by showing how a reviver function can be used with JSON.parse.

The JSON.parse method provides an optional second argument: a reviver function that can be used to screen or modify the values being parsed. The reviver function will be invoked in turn on each of the primitive property values in the JSON data being parsed. It has two arguments: name (property name or array index) and value. A name-value pair can be deleted from the result by returning undefined, or the value can be modified based on your algorithm, or the value can be returned unchanged.

A Simple Demonstration

We demonstrate with a simple associative PHP array:

<?php
$book = array(
    "title" => "JavaScript: The Definitive Guide",
    "author" => "David Flanagan",
    "edition" => 6
);
?>

We include a simple reviver function as the second argument in our invocation of JSON.parse:

<script type="text/javascript">
var book = JSON.parse('<?php echo json_encode($book) ?>', function(name, value) {
        // screen (e.g., based on name or typeof value)
        if (name === 'edition') {
            return undefined;
        }
        // otherwise return value
        return value; 
    });

console.log(book); 
// Object { title="JavaScript: The Definitive Guide", author="David Flanagan"}
</script>

For this example, we check whether the name passed is edition. If so, we return undefined to remove that name-value pair from the parsed result. Otherwise, we return the value unchanged.

We use the console.log method to verify that the edition property has been removed from the book object. The result is shown in code comments.

Reviver Function Example Two

This example will use a more complex $BOOKS array:

<?php
$BOOKS = array(
    array(
        "title" => "JavaScript: The Definitive Guide",
        "author" => "David Flanagan",
        "publisher" => "O'Reilly Media",
        "pub_date" => "May 13, 2011",
        "edition" => 6,
         // string with line break
        "comments" => "If you are looking for comprehensive and authoritative
            information, this is the book for you!"
        
    ),
    array(
        "title" => "High Performance JavaScript",
        "author" => "Nicholas C. Zakas",
        "publisher" => "O'Reilly Media",
        "pub_date" => "Mar 30, 2010",
        "edition" => 1,
        "comments" => "A slim but very useful book."
    )
);

// invoke json_encode here so we can clean up the string
// include JSON_HEX_APOS option (for apostrophe in O'Reilly)
$json_books = json_encode($BOOKS, JSON_HEX_APOS);

// replace \\n which would cause errors in JavaScript
$json_books = str_replace("\\n", " ", $json_books);

// to view resulting string
echo $json_books;
?>

We invoke json_encode on the array, creating a string in PHP so we can do a little cleanup, removing characters which would otherwise cause errors in JavaScript. We use the json_encode function's JSON_HEX_APOS option to convert apostrophes to their hexadecimal equivalent,[1] and we use the str_replace function to convert escaped new-line characters to spaces.

Here is our second reviver function example (reviver2) which demonstrates how to remove a name-value pair from the resulting JSON object, how to turn a date string into a Date object, and how to modify string values returned:

<script type="text/javascript">
// example reviver function
function reviver2(nm, val) {
    if ( nm === 'edition' ) {
        return undefined; // to omit from results
    } else if ( nm === 'pub_date' ) {
        return new Date(val); // restore date object
    } else if ( typeof val === 'string' ) {
        // restore ' (undo JSON_HEX_APOS)
        val = val.replace(/\u0027/g, "'");
        return val.replace(/\s+/g, ' '); // remove extra spaces
    } else {
        return val; // return unchanged
    }
}

// parse the php/json string created above ($json_books)
// passing reviver function defined above as 2nd argument 
var books = JSON.parse( '<?php echo $json_books ?>', reviver2 );

// view/verify results
console.log(books);
console.log( books[0]['comments'] );
// If you are looking for comprehensive and authoritative information, this is the book for you!
console.log( books[0]['publisher'] ); // O'Reilly Media
console.log( books[0]['pub_date'] ); // Date {Fri May 13 2011 00:00:00 GMT-0700 (PDT)}
console.log( typeof books[0]['pub_date'] ); // object
</script>

We pass our example reviver function as the second argument to JSON.parse and verify the results using console.log.

Back to top


  1. The PHP documentation for json_encode provides a list of options available. ^