JSON Wrapper

Overview

The Json class in Flight provides a simple, consistent way to encode and decode JSON data in your application. It wraps PHP's native JSON functions with better error handling and some helpful defaults, making it easier and safer to work with JSON.

Understanding

Working with JSON is super common in modern PHP apps, especially when building APIs or handling AJAX requests. The Json class centralizes all your JSON encoding and decoding, so you don't have to worry about weird edge cases or cryptic errors from PHP's built-in functions.

Key features:

  • Consistent error handling (throws exceptions on failure)
  • Default options for encoding/decoding (like unescaped slashes)
  • Utility methods for pretty printing and validation

Basic Usage

Encoding Data to JSON

To convert PHP data to a JSON string, use Json::encode():

use flight\util\Json;

$data = [
  'framework' => 'Flight',
  'version' => 3,
  'features' => ['routing', 'views', 'extending']
];

$json = Json::encode($data);
echo $json;
// Output: {"framework":"Flight","version":3,"features":["routing","views","extending"]}

If encoding fails, you'll get an exception with a helpful error message.

Pretty Printing

Want your JSON to be human-readable? Use prettyPrint():

echo Json::prettyPrint($data);
/*
{
  "framework": "Flight",
  "version": 3,
  "features": [
    "routing",
    "views",
    "extending"
  ]
}
*/

Decoding JSON Strings

To convert a JSON string back to PHP data, use Json::decode():

$json = '{"framework":"Flight","version":3}';
$data = Json::decode($json);
echo $data->framework; // Output: Flight

If you want an associative array instead of an object, pass true as the second argument:

$data = Json::decode($json, true);
echo $data['framework']; // Output: Flight

If decoding fails, you'll get an exception with a clear error message.

Validating JSON

Check if a string is valid JSON:

if (Json::isValid($json)) {
  // It's valid!
} else {
  // Not valid JSON
}

Getting the Last Error

If you want to check the last JSON error message (from native PHP functions):

$error = Json::getLastError();
if ($error !== '') {
  echo "Last JSON error: $error";
}

Advanced Usage

You can customize encoding and decoding options if you need more control (see PHP's json_encode options):

// Encode with HEX_TAG option
$json = Json::encode($data, JSON_HEX_TAG);

// Decode with custom depth
$data = Json::decode($json, false, 1024);

See Also

  • Collections - For working with structured data that can be easily converted to JSON.
  • Configuration - How to configure your Flight app.
  • Extending - How to add your own utilities or override core classes.

Troubleshooting

  • If encoding or decoding fails, an exception is thrown—wrap your calls in try/catch if you want to handle errors gracefully.
  • If you get unexpected results, check your data for circular references or non-UTF8 characters.
  • Use Json::isValid() to check if a string is valid JSON before decoding.

Changelog

  • v3.16.0 - Added JSON wrapper utility class.