Saturday, September 15, 2018

JsonX APIs

Note: This library is now part of WebFiori Framework. Updated API Docs can be found at https://programmingacademia.com/webfiori/docs/jsonx/.

This page contain APIs descriptions of the library JsonX, A library that can be used to create JSON strings in PHP. The library consist of two files only, JsonX.php and JsonI.php. The first file contains the class 'JsonX' which is the core component. The other file contains an interface which can be implemented by other classes to create a custom JSON strings.

Basic Usage Example

The next lines of code shows how to use the library in very simple way.

<?php
include 'JsonX.php';
include 'JsonI.php';

//create new instance of JsonX
$json = new JsonX();

//add attributes to JSON object.
$json->add('a-string', 'This is a string.');
$json->add('a-number', 44);
$json->add('a-boolean', FALSE);
$json->add('null-value', NULL);

//send Json object as response
header('content-type:application/json');
echo $json;

Class JsonX

Version: 1.2

Author: Ibrahim BinAlshikh

const TYPES

  • Type: Array
  • Description: An array of supported JOSN data types. The array has 7 values: 'integer', 'string', 'double', 'boolean', 'NULL' and 'object'.
  • Since: 1.0

const SPECIAL_CHARS

  • Type: Array
  • Description: An array which contains JSON special characters that can be a part of a string. The array has the following characters: \\, /, ", \t, \r, \n and \f.
  • Since: 1.0

const SPECIAL_CHARS_ESC

'
  • Type: Array
  • Description: An array which contains escaped JSON special characters that can be a part of a string.
  • Since: 1.0

public function add($key, $value, $options=array())

Adds a new value to include in the generated JSON string.

Parameters:

  • $key:
    • Type: string
    • Description: The name of the attribute that the given value will be stored in. Usually called the "name" of the "value".
  • $value:
    • Type: mixed
    • Description: The value of the key. It can be an integer, a double, a string, an array or an object. If NULL is given, the method will set the value at the given key to 'null'.
  • $options: [Optional]
    • Type: Array
    • Description: An associative array of options. Currently, the array has the following options:
      • string-as-boolean: A boolean value. If set to TRUE and the given string represents a boolean value (like 'yes' or 'no'), the string will be added as a boolean value. Default is FALSE.
      • array-as-object: A boolean value. If set to TRUE, the array will be added as an object. Default is FALSE.

Returns:

  • boolean: TRUE if the value is set. If the given value or key is invalid, the function will return FALSE.

Since: 1.1

public function addNumber($key, $value)

Adds a number to include in the generated JSON string.

Parameters:

  • $key:
    • Type: string
    • Description: The name of the attribute that the given value will be stored in. Usually called the "name" of the "value"
  • $value:
    • Type: integer | double
    • Description: The number which will be added. Note that if the given number is INF or NAN, The method will add them as a string.

Returns:

  • boolean: TRUE if the value is set. If the given value or key is invalid, the function will return FALSE.

Since: 1.0

public function addBoolean($key, $value)

Adds a boolean value (true or false) to include in the generated JSON string.

Parameters:

  • $key:
    • Type: string
    • Description: The name of the attribute that the given value will be stored in. Usually called the "name" of the "value"
  • $value: [Optional]
    • Type: boolean
    • Description: TRUE or FALSE. If not specified, The default will be TRUE.

Returns:

  • boolean: TRUE if the value is set. If the given value or key is invalid, the function will return FALSE.

Since: 1.0

public function addString($key, $value, $asBoolean)

Adds a string to include in the generated JSON string.

Parameters:

  • $key:
    • Type: string
    • Description: The name of the attribute that the given value will be stored in. Usually called the "name" of the "value"
  • $value:
    • Type: string
    • Description: The value of the string. Note that if the given string is one of the following and the parameter $asBoolean is set to TRUE, it will be converted into boolean (case insensitive).
      • yes => TRUE
      • no => FALSE
      • y => TRUE
      • n => FALSE
      • t => TRUE
      • f => FALSE
      • true => TRUE
      • false => FALSE
      • on => TRUE
      • off => FALSE
      • ok => TRUE
  • $asBoolean: [Optional]
    • Type: boolean
    • Description: If set to TRUE and the string represents a boolean value, then the string will be added as a boolean. Default is FALSE.

Returns:

  • boolean: TRUE if the value is set. If the given value or key is invalid, the function will return FALSE.

Since: 1.0

public function addArray($key, $value, $asObject)

Adds an array to include in the generated JSON string.

Parameters:

  • $key:
    • Type: string
    • Description: The name of the attribute that the given value will be stored in. Usually called the "name" of the "value"
  • $value:
    • Type: Array
    • Description: The array that will be added. If the given array is indexed array, all values will be added as single entity (e.g. [1, 2, 3]). If the array is associative, the values of the array will be added as objects.
  • $asObject: [Optional]
    • Type:
    • Description: If this parameter is set to TRUE, the array will be added as an object in JSON string. Default is FALSE.

Returns:

  • boolean: TRUE if the value is set. If the given value or key is invalid, the function will return FALSE.

Since: 1.0

public function addObject($key, $value)

Adds a PHP object to include in the generated JSON string.

Parameters:

  • $key:
    • Type: string
    • Description: The name of the attribute that the given value will be stored in. Usually called the "name" of the "value">
  • $value:
    • Type: JsonI | Object
    • Description: The parameter can be a PHP object or an object that implements the interface 'JsonI'. If the object does not implement the interface 'JsonI', then the function will try to extract object information based on its public functions and the generated JSON will be on the format {"prop-0":"something","prop-1":"something else","prop-n":"xxx"}.

Returns:

  • boolean: TRUE if the value is set. If the given value or key is invalid, the function will return FALSE.

Since: 1.0

public function get($key)

Returns a string that represents the value at the given key.

Parameters:

  • $key:
    • Type: string
    • Description: The name of the attribute that the value is stored in. Usually called the "name" of the "value"

Returns:

  • string | NULL: A string that represents the value at the given key. If the key does not exists, the function will return NULL.

Since: 1.2

public function hasKey($key)

Checks if a key is exist or not.

Parameters:

  • $key:
    • Type: string
    • Description: The name of the key. Usually called the "name".

Returns:

  • boolean: The function will return TRUE if the key exists. FALSE if not.

Since: 1.2

public static function escapeJSONSpecialChars($str)

Escape JSON special characters from a string.

Parameters:

  • $str:
    • Type: string
    • Description: A value of one of JSON object properties. If it is NULL,the method will return empty string.

Returns:

  • string: The same string with JSON special characters escaped.

    • Since: 1.0

Interface JsonI

Version: 1.0

Author: Ibrahim BinAlshikh

public function toJSON()

This function can be implemented by any class that will be added as an attribute to any JsonX instance.It is used to customize the generated JSON string.

Parameters:

  • NONE

Returns:

  • JsonX: An instance of JsonX

Since: 1.0


Posted by No comments:
Labels: , , , , ,
Subscribe to: Posts (Atom)