nickjbedford/json-response

Defines a uniform JSON response structure for PHP 7.4+ applications.

0.1.3 2023-08-25 03:08 UTC

Requires

• php: >=7.4
• ext-json: *

Requires (Dev)

• phpunit/phpunit: *

MIT

• Nick Bedford

• json
• rest
• api

README

The JsonResponse library for PHP defines a simple and uniform structure for JSON API responses, from success status to error information and data payloads.

All keys are guaranteed to exist, even if they are null. This ensures clients of an API do not have to waste time and code checking if standard properties exist before checking their values.

Success Responses

To create a success response, use either the \YetAnother\JsonResponse::success() method or the json_success() function.

Example

$response = json_success();

$json = $response->toJSON();
$json = strval($response); // This calls $response->toJSON()

// Create a response with a payload
$personResponse = json_success([
    'id' => 123,
    'name' => 'John Citizen',
    'dob' => '1985-01-01'
]);

The basic response structure for a successful request without any data payload is as follows:

{
    "success": true,
    "error": null,
    "data": null
}

Field	Type	Description
success	boolean	true for a successful response, otherwise false for an error response.
error	object or null	null for successful responses, otherwise a JsonResponseError object.
data	mixed or null	An optional data payload containing any type of data including null. This will depend on the API request.

Error Responses

To create a failure response, use either the \YetAnother\JsonResponse::failure() method or the json_success() function.

Example

$response = json_failure("Person not found.", "E_NOTFOUND");

$json = $response->toJSON();

The basic response structure for a failed request is as follows:

{
    "success": true,
    "error": {
        "message": "Some error message...",
        "code": null,
        "data": null
    },
    "data": null
}

Field	Type	Description
error.message	string	An error message for the client to display to the user.
error.code	string or null	An optional error code for the client to use in handling the error. This will depend on the API request.
error.data	mixed or null	Optional information about the error. This may contain debugging information about exceptions thrown by the server if provided.

Exception Error Responses

To create a failure response based on an exception, use either the \YetAnother\JsonResponse::exception() method or the json_exception() function.

Example

$exception = new Exception("Database connection was lost.", "E_DBCONN");

$response = json_exception($exception, true); // true to include debugging information

$json = $response->toJSON();

The response will contain the following data including the exception debug data:

{
    "success": false,
    "error": {
        "message": "Database connection was lost.",
        "code": "E_DBCONN",
        "data": {
            "class": "Exception",
            "file": "/home/user/documents/my-project/example.php",
            "line": 34,
            "trace": "<stack trace...>"
        }
    }
}

If debugging data is included in the exception response, the error.data property will be structured as follows:

Field	Type	Description
error.data.class	string	The PHP class name of the exception throw.
error.data.file	string	The name of the PHP script where the exception occurred.
error.data.file	int	The line number in the PHP script where the exception occurred.
error.data.trace	string	The stack trace formatted as a string.

Record Sets

To create a standardised response for record set responses with paging information, use the \YetAnother\JsonResponse::recordSet() method or json_records() function.

Example

$records = [ 10, 20, 30, 40, 50 ];

$response = json_records($records, 2, 5, 30, 'Integer');

$json = $response->toJSON();

The response will contain the following data:

{
    "success": true,
    "error": null,
    "data": {
        "records": [ 10, 20, 30, 40, 50 ],
        "page": 2,
        "pageLength": 5,
        "total": 30,
        "nextPage": 3,
        "previousPage": 1,
        "recordType": "Integer"
    }
}

Field	Type	Description
data.records	array	An array containing the page's records.
data.page	int	The zero-based page index for the current record set.
data.pageLength	int	The length of each page in the query.
data.total	int	The total number of records in the query.
data.nextPage	int or null	The next page's index if there are more records, otherwise null.
data.previousPage	int or null	The previous page's index if the current page index is non-zero, otherwise null.
data.recordType	string or null	An optionally provided name of the type of records in the record set. This is defined by the API using the library.