alirezajavadi/jsonize

Standardize JSON API responses with a fluent, chainable interface for PHP applications.

1.8.1 2025-05-18 19:47 UTC

Requires (Dev)

• phpunit/phpunit: ^11.5

MIT

• Alireza Javadi

README

A fluent PHP library for building standardized JSON API responses.

Requirements

• PHP 8.1 or higher

Installation

composer require alirezajavadi/jsonize

Quick Start

JSONize provides two usage modes: Easy (static, zero-boilerplate) and Efficient (singleton, memory-safe for long-running processes).

Easy Mode

use JSONize\App\Easy\Response;

Response::message("User created")->status(201)->data(["id" => 42]);

Output:

{
    "success": true,
    "message": "User created",
    "data": {"id": 42},
    "status": [201, "Created"]
}

In Easy mode, the response is automatically sent when the object is destroyed. Call ->get() instead if you need the JSON string returned without echoing:

$json = Response::message("OK")->status(200)->get();

Efficient Mode

use JSONize\App\Efficient\Response;

$response = Response::getInstance();

$response->message("User created")->status(201)->data(["id" => 42])->get();

Efficient mode uses a singleton so you reuse the same instance. Always call ->get() to retrieve the JSON string.

API Reference

All methods are chainable and available in both modes.

message(string $message)

Sets the response message.

Response::message("Operation successful");

status(int $code, string $message = "")

Sets the HTTP status code. Optionally pass a custom status message to override the default.

Response::status(404);
Response::status(200, "Everything is fine");

data(mixed $data, string $key = "data")

Sets the response payload. The second argument changes the JSON key name.

Response::data(["id" => 1, "name" => "Item"]);
Response::data(["id" => 1, "name" => "Item"], "item");

With a custom key, the output uses that key instead of "data":

{
    "success": true,
    "item": {"id": 1, "name": "Item"},
    "status": [200, "OK"]
}

error(string $message, int $status = 500)

Shorthand for setting an error message and status code in one call.

Response::error("Something went wrong");
Response::error("Validation failed", 422);

headers(array $headers)

Merges custom HTTP headers into the response. CORS headers are included by default.

Response::message("OK")->headers(["X-Request-Id" => "abc-123"]);

hideStatus() / hideMessage() / hideData() / hideSuccess()

Remove specific fields from the JSON output.

Response::message("OK")->status(200)->hideStatus();

{
    "success": true,
    "message": "OK",
    "data": null
}

get()

Returns the JSON string and prevents automatic output (Easy mode). In Efficient mode, this is the only way to get the response.

$json = Response::message("OK")->get();

Full Examples

Success with data:

Response::message("Users retrieved")
    ->status(200)
    ->data(["users" => [["id" => 1, "name" => "Alice"]]]);

{
    "success": true,
    "message": "Users retrieved",
    "data": {"users": [{"id": 1, "name": "Alice"}]},
    "status": [200, "OK"]
}

Validation error:

Response::error("Validation failed", 422)
    ->data(["email" => "The email field is required."], "errors");

{
    "success": false,
    "message": "Validation failed",
    "errors": {"email": "The email field is required."},
    "status": [422, "Unprocessable Content"]
}

Minimal response:

Response::status(204)->hideMessage()->hideData();

{
    "success": true,
    "status": [204, "No Content"]
}

Supported HTTP Status Codes

All standard HTTP status codes (1xx through 5xx) are supported with their official reason phrases. Custom status messages can be provided via ->status($code, "Your message").

Testing

Tests run automatically via GitHub Actions on every push to main/develop and on pull requests, across PHP 8.1 through 8.4.

To run locally:

composer install
vendor/bin/phpunit

Contributing

Contributions are welcome. Please submit a pull request or open an issue for bugs and suggestions. Follow Conventional Commits for commit messages.

License

MIT — see LICENSE for details.

Author

Alireza Javadi