Merge pull request #7 from uxmansarwar/uxman_dev

feat: improve core functionality and enhance README with composer ins…

Author: uxmansarwar

.gitignore

@@ -24,3 +24,4 @@
 /app/Config/database.php
 /vendors/*
 
+/composer.lock

CHANGELOG.md

@@ -1,14 +1,28 @@
 # Changelog
 
-## [released]
-
+## [3.0.0] - 2025-03-11
 ### Added
-- Initial release of `uxmansarwar/response`.
-- Added result and error storage.
-- JSON, array, response support.
-- User input handling.
+- **PHPStan Compliant Developer Comments**: Added detailed PHPStan-compliant comments to improve code readability and maintainability.
+- **`collection()` Method**: Introduced a new method to centralize response data collection, reducing redundancy in `json()` and `array()`.
+- **Static Response Key Names**: Defined `$result_key_text`, `$error_key_text`, and `$input_key_text` as static class properties for better maintainability.
 
-## [1.0.0] - 2025-02-20
+### Changed
+- **Singleton Handling**: Improved `singleton()` method for better reusability instead of initializing in multiple places.
+- **Constructor Reset Behavior**: Adjusted constructor logic to ensure that each instantiation resets response states correctly.
+- **JSON Parsing Validation**: Enhanced JSON request body parsing by verifying `json_last_error()`.
+- **Better Result & Error Storage**: Updated result and error storage to always ensure correct structuring when using keys.
+
+### Fixed
+- **Incorrect Singleton Reinitialization**: Ensured `singleton()` and `init()` methods correctly maintain a single instance.
+- **Input Handling Edge Cases**: Addressed cases where JSON input merging could fail under certain request formats.
+- **Return Consistency**: Standardized method return values to always return `self` where applicable for method chaining.
+
+---
+
+## [2.0.1] - Previous Version
+### Initial Features
+- Implemented Singleton pattern.
+- Added methods for storing results (`result()`) and errors (`error()`).
+- Supported response output in both JSON (`json()`) and array (`array()`) formats.
+- Allowed toggling of user input inclusion in responses via `input()` method.
 
-### Added
-- First stable release.

README.md

@@ -1,117 +1,125 @@
-# Response
+# Response - PHP API Response Handler
 
-Response is a PHP class designed to manage API responses efficiently. It provides a singleton-based approach to storing and retrieving results, errors, and user input data in multiple formats (JSON, array). This class ensures proper handling of API responses while maintaining PHP 7+ compatibility.
+[![Packagist](https://img.shields.io/packagist/v/uxmansarwar/response)](https://packagist.org/packages/uxmansarwar/response)
+[![PHP Version](https://img.shields.io/badge/php-%3E%3D7.2-blue)](https://www.php.net/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-## Features
-- Singleton pattern ensures a single instance.
-- Store results and errors dynamically.
-- Capture user input from `$_GET`, `$_POST`, and JSON payloads.
-- Retrieve stored data in JSON, array, format.
-- Support for enabling/disabling user input inclusion in responses.
-- Works on PHP 7 and above.
+## Overview
+
+`Response` is a **lightweight PHP library** designed to streamline **API response handling**. It follows a **singleton-based pattern** to store and retrieve results, errors, and user input efficiently. The package is **PSR-4 compliant** and fully compatible with **PHP 7.2+ and PHP 8.2**.
+
+### **Key Features**
+- ✅ **Singleton pattern** to prevent redundant object creation.
+- ✅ **Structured response handling** for JSON and array outputs.
+- ✅ **Collect API results & errors dynamically**.
+- ✅ **Retrieve user input** from `$_GET`, `$_POST`, and JSON payloads.
+- ✅ **Flexible data retrieval** (JSON, array, collection format).
+- ✅ **Works with Laravel, Symfony, CodeIgniter, WordPress, and Core PHP**.
+
+---
 
 ## Installation
-Clone the repository into your project directory:
 
+### **Install via Composer**
+You can install this package using Composer:
 ```sh
-$ git clone https://github.com/yourusername/Response.git
+composer require uxmansarwar/response
 ```
 
-Include the `Response.php` file in your project:
-
+### **Manual Installation**
+Alternatively, clone this repository and include it in your project:
+```sh
+git clone https://github.com/uxmansarwar/Response.git
+```
+Then, include the autoloader:
 ```php
-require_once 'Response.php';
+require 'vendor/autoload.php';
 ```
 
-## Usage
-### Initializing the Response
-Since `Response` follows the singleton pattern, you do not instantiate it directly. Instead, use the `init()` method:
+---
+
+## **Usage Examples**
 
+### **1. Initializing the Response Handler**
 ```php
+use UxmanSarwar\Response;
+
 Response::init();
 ```
 
-### Storing Results
-You can store multiple results dynamically using the `result()` method:
-
+### **2. Storing Results**
 ```php
-Response::result("Operation successful");
+Response::result("User created successfully");
 Response::result(["id" => 1, "name" => "John Doe"]);
 ```
 
-### Storing Errors
-Similarly, errors can be stored using the `error()` method:
-
+### **3. Handling Errors**
 ```php
-Response::error("Invalid request");
-Response::error("Database connection failed");
+Response::error("Invalid API request");
+Response::error("Failed to connect to the database");
 ```
 
-### Retrieving Data
-You can retrieve the stored results and errors in different formats:
-
-#### JSON Format
+### **4. Retrieving Response Data**
+#### JSON Output:
 ```php
 echo Response::json();
 ```
-**Output:**
+**Example Output:**
 ```json
 {
     "result": [
-        "Operation successful",
+        "User created successfully",
         { "id": 1, "name": "John Doe" }
     ],
     "error": [
-        "Invalid request",
-        "Database connection failed"
+        "Invalid API request",
+        "Failed to connect to the database"
     ]
 }
 ```
 
-#### Array Format
+#### Array Output:
 ```php
-$response_array = Response::array();
+$response_array = Response::collection();
 print_r($response_array);
 ```
-**Output:**
+
+---
+
+## **Advanced Features**
+
+### **5. Grouping Responses with a Key**
 ```php
-Array (
-    [result] => Array (
-        [0] => Operation successful
-        [1] => Array ([id] => 1, [name] => John Doe)
-    )
-    [error] => Array (
-        [0] => Invalid request
-        [1] => Database connection failed
-    )
-)
+Response::key("user")->result(["id" => 2, "name" => "Jane Doe"]);
+echo Response::json();
 ```
 
-### Handling User Input
-User input (from `$_GET`, `$_POST`, or JSON requests) is captured automatically. You can include it in the response using:
-
+### **6. Include User Input in Response**
 ```php
 Response::input(true);
 echo Response::json();
 ```
 If a request is made with:
 ```sh
-GET /api.php?id=5&name=John
+GET /api.php?id=10&name=Alice
 ```
-The output will be:
+The output will include:
 ```json
-{
-    "result": [],
-    "error": [],
-    "input": {
-        "id": "5",
-        "name": "John"
-    }
+"input": {
+    "id": "10",
+    "name": "Alice"
 }
 ```
 
-### Example Use Case
-#### API Response Handling
+### **7. Custom Error & Result Keys**
+You can define custom keys for results and errors:
+```php
+Response::key("dns");
+```
+
+---
+
+## **Use Case Example: API Response Handling**
 ```php
 Response::init();
 
@@ -129,9 +137,22 @@ if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
 echo Response::json();
 ```
 
-### Contributing
-Feel free to fork this repository, make enhancements, and submit pull requests. Suggestions and issues are welcome!
+---
+
+## **Why Use This Package?**
+### ✅ **For Laravel & Symfony Developers**: Use it as a service-based response handler.
+### ✅ **For WordPress Developers**: Improve structured AJAX responses.
+### ✅ **For REST API Development**: Optimize API response handling with minimal effort.
+### ✅ **For Microservices**: Centralize error handling and response formatting.
+
+---
+
+## **Testing the Package**
+To install and run tests:
+```sh
+composer install
+vendor/bin/phpstan analyse src --level=max
+vendor/bin/pest
+```
 
-### License
-This project is licensed under the MIT License.
 

composer.json

@@ -1,11 +1,17 @@
 {
     "name": "uxmansarwar/response",
-    "description": "",
+    "description": "A lightweight PHP response handler for structured API responses.",
     "keywords": [
-        "response handler - collector"
+        "php",
+        "response",
+        "api",
+        "response handler",
+        "error handling",
+        "json response",
+        "response collector"
     ],
     "type": "library",
-    "license": "proprietary",
+    "license": "MIT",
     "authors": [
         {
             "name": "Uxman Sarwar",
@@ -15,6 +21,7 @@
     ],
     "config": {
         "sort-packages": true,
+        "prefer-stable": true,
         "allow-plugins": {
             "pestphp/pest-plugin": true
         }
@@ -30,7 +37,9 @@
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^3.35",
         "pestphp/pest": "^2.34",
-        "phpstan/phpstan": "^1.10"
+        "phpstan/phpstan": "^1.10",
+        "mockery/mockery": "^1.6",
+        "phpunit/phpunit": "^10.4"
     },
     "minimum-stability": "stable"
-}
+}

examples/example.php

@@ -4,20 +4,36 @@
 
 use UxmanSarwar\Response as res;
 
-res::init()->input(true);
-res::key('mysql')->result(['sql' => 'this is value related to upcoming sorting thing']);
-res::result('this is value 2');
 
-res::key('mysql-2')->result(['sql' => 'this is value related to upcoming sorting thing']);
-res::result('this is value 2');
-res::result('this is value 2');
-res::result('this is value 2');
+// ------------------------------------------------------v3.0.0
 
-res::key();
 
-res::error('MySql got error');
 
-echo res::json();
+
+
+
+
+// ------------------------------------------------------v3.0.0
+
+
+echo res::init();
+
+
+// ------------------------------------------------------
+// res::init()->input(true);
+// res::key('mysql')->result(['sql' => 'this is value related to upcoming sorting thing']);
+// res::result('this is value 2');
+
+// res::key('mysql-2')->result(['sql' => 'this is value related to upcoming sorting thing']);
+// res::result('this is value 2');
+// res::result('this is value 2');
+// res::result('this is value 2');
+
+// res::key();
+
+// res::error('MySql got error');
+
+// echo res::json();
 
 
 

phpstan.neon

@@ -0,0 +1,5 @@
+parameters:
+    level: max
+    paths:
+        - tests
+    bootstrapFiles: []