maatify/api-response

Slim-compatible JSON API response handler for validation, errors, and success messages.

1.0.2 2025-04-18 15:28 UTC

Requires

• php: >=8.2.0
• maatify/slim-logger: ^1.0
• psr/http-message: ^1.0

Requires (Dev)

• phpunit/phpunit: ^10
• slim/psr7: ^1.7

MIT

• Mohamed Abdulalim
• Ahmed Fawzy
• Mohaned Saeed Sami
• Ahmed Abdullah
• Elmokhtar Ahmed

• json
• api
• response
• maatify

README

Maatify API Response is a lightweight, PSR-7 compatible, Slim-friendly structured JSON response library for clean and consistent API responses. Built with production logging in mind via maatify/slim-logger. It is part of the modular Maatify.dev ecosystem.

🚀 Features

• ✅ PSR-7 compatible (ResponseInterface)
• ✅ Slim-ready (return Json::...)
• ✅ Structured error responses (missing, invalid, etc.)
• ✅ Success responses with metadata
• ✅ Automatic route+line trace: user:login::55
• ✅ Production-safe JSON POST logging via maatify/slim-logger
• ✅ Environment toggles for logging
• ✅ Optional JsonResponseEmitter for non-framework use

🛠 Installation

composer require maatify/api-response

Requires PHP 8.1+
Uses maatify/slim-logger under the hood for logging (installed automatically)

📦 Usage in Slim

use Maatify\ApiResponse\Json;

$app->post('/register', function ($request, $response) {
    return Json::missing($response, 'email');
});

💡 Usage in Pure PHP (no framework)

Use the built-in JsonResponseEmitter class to send PSR-7 responses directly in native PHP.

require 'vendor/autoload.php';

use Maatify\ApiResponse\Json;
use Maatify\ApiResponse\JsonResponseEmitter;
use Nyholm\Psr7\Response;

$response = new Response();

if (empty($_POST['email'])) {
    $response = Json::missing($response, 'email', 'Email is required', __LINE__);
}

JsonResponseEmitter::emit($response);

🔁 Output

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "success": false,
  "response": 1000,
  "var": "email",
  "description": "MISSING Email",
  "more_info": "Email is required",
  "error_details": "index::15"
}

✨ Example Slim Response

{
  "success": false,
  "response": 1000,
  "var": "email",
  "description": "MISSING Email",
  "more_info": "",
  "error_details": "register::34"
}

✅ Supported Methods

Method	Description
missing()	Field missing from input
incorrect()	Incorrect format or value
invalid()	Invalid input
notExist()	Value doesn't exist (e.g. user ID)
success()	Standard success output
dbError()	Internal DB/system error
tooManyAttempts()	Rate limit exceeded

📊 HTTP Status Code Reference

Method	Status
missing()	400
incorrect()	400
invalid()	400
notExist()	400
success()	200
dbError()	500
tooManyAttempts()	429

🔐 Secure Logging

Enable structured logging in production via maatify/slim-logger

1. Enable in your .env

JSON_POST_LOG=1

2. Sample Logged Output

{
  "response": {
    "success": false,
    "response": 1000
  },
  "posted_data": {
    "email": "[e-mail]",
    "password": "******"
  }
}

Log file: logs/api/response.log
Log level: Info

📂 Directory Structure

src/
├── CoreResponder.php        # Base logic + logger
├── BaseResponder.php        # Validation & error helpers
└── Json.php                 # Final static entrypoint class
└── JsonResponseEmitter.php  # Sends PSR-7 responses in native PHP

🧩 Extend It

Want custom codes or more logic?

• Extend BaseResponder or CoreResponder
• Override any method (e.g. add audit log or rate limiter)
• Customize logResponse() for deeper monitoring

🧪 Testing

✅ Run Tests

composer test

✅ Run One Test

composer test -- --filter testSuccessResponse

✅ CI (GitHub Actions)

Tested on PHP 8.2, 8.3, and 8.4 using run-tests.yml

🆚 Slim vs Pure PHP Comparison

Feature	Slim	Pure PHP
Routing	$app->post(...	Native index.php or custom
JSON Response	return Json::success(...)	$response = Json::success(...)
Headers/Status	Handled by Slim	You manually set headers + status
Logging	Via maatify/slim-logger	✅ Works the same

📄 License

MIT License © 2025 Maatify.dev

🙋‍♂️ Questions or Feedback?

• Open an issue on GitHub