Merge pull request #8 from uxmansarwar/uxman_dev

v4.0.0 init commit - i am just about to new release of this package.

Author: uxmansarwar

CHANGELOG.md

@@ -1,28 +1,120 @@
-# Changelog
+# 📦 CHANGELOG for uxmansarwar/response
 
-## [3.0.0] - 2025-03-11
-### Added
-- **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.
+This is the official changelog for the `uxmansarwar/response` Composer package.  
+This PHP package helps developers return structured API responses in a simple, clean, and fluent way.  
+Maintained by [Uxman Sarwar](https://github.com/uxmansarwar) — a professional full-stack PHP developer since 2013.
 
-### 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.
+> Install via Composer:  
+> `composer require uxmansarwar/response`
 
-### 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.
+---
+
+## 📌 Version 4.0.0 – Major Rewrite & Powerful Improvements (May 2025)
+
+This version is a **major upgrade** from `v3.x` to `v4.0.0`.  
+It is a complete rewrite with **new features**, **cleaner code**, and **more flexibility** for real-world APIs and production apps.
+
+### ✅ What's New
+
+- 🔁 **Total Refactor to Singleton-based Fluent Class**
+  - Keeps only one instance in memory. Cleaner, faster, and easier to use.
+
+- 🗂️ **New `index()` Method**
+  - Add secondary keys under each primary `key()`. Useful for nesting grouped data.
+
+- 🧠 **New `ttl()` Support**
+  - You can now attach a **TTL (time to live)** value in the response. Useful for cache-aware APIs or auto-expiring resources.
+
+- 🔍 **New `query()` Method**
+  - Attach queries(Like what this response about), filter info, or any debug context directly to the response.
+
+- 🧩 **Clearer Constants**
+  - All internal keys are now constants like `RESULT_KEY_TXT`, `ERROR_KEY_TXT`, `INPUT_KEY_TXT`, etc.
+  - Easier to maintain and debug in large apps.
+
+- 🔒 **Private Constructor with Auto Reset**
+  - Every call to `init()` fully resets internal states (`results`, `errors`, `keys`, `ttl`, etc.).
+
+- 🌐 **Smarter Input Collection**
+  - Automatically merges `$_GET`, `$_POST`, and raw JSON from `php://input`.
+  - No need to manually parse input again.
+
+- 🧪 **Fluent Interface**
+  - You can now write responses like:
+    ```php
+    Response::key('user')->index('profile')->result(['name' => 'John']);
+    ```
+
+- 🧼 **Improved Readability and Simplicity**
+  - All methods return `$this` or `self::singleton()` for smooth chaining.
+  - Code is clean, short, and easy for junior and senior developers to follow.
+
+---
+
+## 🧯 Version 3.0.0 – Stable & Basic (Early 2024)
+
+This was the original **stable release** of the Response class.  
+It provided basic JSON response handling in a singleton-style package.
+
+### Features Included:
+- ✅ Add results via `result($value)`
+- ❌ Add errors via `error($message)`
+- 🔁 Group responses using `key($name)`
+- 📥 Optionally include user input with `input(true)`
+- 🧾 Response as `array()` or `json()`
+- 🔄 Automatic input parsing from `$_GET`, `$_POST`, and `php://input`
+- 🧼 Singleton structure with private constructor and `init()` method
 
 ---
 
-## [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.
+## 💡 Why Use This PHP Package?
+
+- Built by a real-world **senior PHP developer** with over **12 years of experience**
+- Ideal for **Laravel**, **RESTful APIs**, **microservices**, **modular monoliths**, and more
+- Easy to use, even for beginners
+- Clean output format for **mobile apps**, **front-end frameworks**, and **automated testing**
+
+---
+
+## 🔍 SEO & GitHub Keywords
+
+> _To help other developers find this package, the following terms are relevant:_
+
+- PHP JSON Response Composer Package
+- Laravel API Response Helper
+- PHP Singleton Response Class
+- Return structured JSON response in PHP
+- Fluent PHP API response builder
+- Composer PHP package by [Uxman Sarwar](https://github.com/uxmansarwar)
+- PHP developer tools 2025
+- PHP API response formatter
+- Best Composer packages for Laravel APIs
+
+---
+
+## 🧑‍💻 About the Author
+
+This package is built and maintained by [Uxman Sarwar](https://github.com/uxmansarwar),  
+a **senior PHP developer since 2013**, with deep experience in:
+
+- Laravel | PHP 8+ | Tailwind CSS  
+- JavaScript | Vue.js | REST APIs  
+- SaaS Architecture | DevOps | Clean Code  
+
+📧 Reach me: [uxmansrwr@gmail.com](mailto:uxmansrwr@gmail.com)  
+🔗 Connect on [LinkedIn](https://www.linkedin.com/in/uxmansarwar)  
+🐙 Star & follow my work on [GitHub](https://github.com/uxmansarwar)
+
+---
+
+## ⬇️ Install This Package
+
+composer require uxmansarwar/response
+
+Then use it like this:
+
+```php
+use UxmanSarwar\Response;
 
+echo Response::key('user')->result(['name' => 'John'])->json();
+```

README.md

@@ -1,133 +1,107 @@
-# Response - PHP API Response Handler
+# 📦 Response – Elegant PHP API Response Handler
 
 [![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/)
+[![PHP Version](https://img.shields.io/badge/php-%3E%3D8.0-blue)](https://www.php.net/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/uxmansarwar/response?style=social)](https://github.com/uxmansarwar/response)
 
-## Overview
+## 🔍 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**.
+**`uxmansarwar/response`** is a powerful yet lightweight PHP package that makes it easy to manage structured API responses. Built with modern PHP practices, it follows a clean singleton pattern and supports result grouping, TTL, debug queries, and more. Ideal for Laravel, Symfony, WordPress, CodeIgniter, or raw PHP projects.
 
-### **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**.
+Developed and maintained by [Uxman Sarwar](https://github.com/uxmansarwar), a senior PHP developer since 2013.
+
+## ✅ Features
+
+- Singleton-based fluent API
+- Add results, errors, queries, TTL, and input metadata
+- Auto-collects `$_GET`, `$_POST`, and raw JSON input
+- Customizable result/error key groups with `key()` and `index()`
+- Get structured responses as JSON or array
+- Great for APIs, microservices, and AJAX handlers
 
 ---
 
-## Installation
+## ⚙️ Installation
 
-### **Install via Composer**
-You can install this package using Composer:
-```sh
-composer require uxmansarwar/response
-```
+### Via Composer
 
-### **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 'vendor/autoload.php';
+```bash
+composer require uxmansarwar/response
 ```
 
 ---
 
-## **Usage Examples**
+## 🚀 Quick Start
+
+### Initialize
 
-### **1. Initializing the Response Handler**
 ```php
 use UxmanSarwar\Response;
 
 Response::init();
 ```
 
-### **2. Storing Results**
+### Add Result
+
 ```php
-Response::result("User created successfully");
-Response::result(["id" => 1, "name" => "John Doe"]);
+Response::result(['id' => 1, 'name' => 'Alice']);
 ```
 
-### **3. Handling Errors**
+### Add Error
+
 ```php
-Response::error("Invalid API request");
-Response::error("Failed to connect to the database");
+Response::error('Invalid request type');
 ```
 
-### **4. Retrieving Response Data**
-#### JSON Output:
+### Grouped Result with Key/Index
+
 ```php
-echo Response::json();
-```
-**Example Output:**
-```json
-{
-    "result": [
-        "User created successfully",
-        { "id": 1, "name": "John Doe" }
-    ],
-    "error": [
-        "Invalid API request",
-        "Failed to connect to the database"
-    ]
-}
+Response::key('user')->index('info')->result(['email' => 'user@example.com']);
 ```
 
-#### Array Output:
+### Set Time-To-Live (TTL)
+
 ```php
-$response_array = Response::collection();
-print_r($response_array);
+Response::ttl(60);
 ```
 
----
-
-## **Advanced Features**
+### Attach Debug Query
 
-### **5. Grouping Responses with a Key**
 ```php
-Response::key("user")->result(["id" => 2, "name" => "Jane Doe"]);
-echo Response::json();
+Response::query('SELECT * FROM users WHERE id = 1');
 ```
 
-### **6. Include User Input in Response**
+### Include Input Data
+
 ```php
 Response::input(true);
-echo Response::json();
-```
-If a request is made with:
-```sh
-GET /api.php?id=10&name=Alice
 ```
-The output will include:
-```json
-"input": {
-    "id": "10",
-    "name": "Alice"
-}
+
+### Output as JSON
+
+```php
+echo Response::json();
 ```
 
-### **7. Custom Error & Result Keys**
-You can define custom keys for results and errors:
+### Output as Array
+
 ```php
-Response::key("dns");
+print_r(Response::array());
 ```
 
 ---
 
-## **Use Case Example: API Response Handling**
+## 💡 Example Use Case: API Endpoint
+
 ```php
 Response::init();
 
 if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
     Response::error("Only POST requests are allowed");
 } else {
     $data = Response::$_INPUT;
-    if (!isset($data['username']) || empty($data['username'])) {
+    if (empty($data['username'])) {
         Response::error("Username is required");
     } else {
         Response::result("User registered successfully");
@@ -139,20 +113,48 @@ echo Response::json();
 
 ---
 
-## **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
 
----
-
-## **Testing the Package**
-To install and run tests:
-```sh
+```bash
 composer install
 vendor/bin/phpstan analyse src --level=max
 vendor/bin/pest
 ```
 
+---
+
+## 🌐 Use Cases
+
+- Laravel: Replace default `response()->json()` with a fluent helper
+- WordPress: Handle AJAX with structured output
+- Symfony: Wrap controller responses with grouped structure
+- REST APIs: Make consistent error/result formatting
+- Microservices: Inject debug info and TTL for downstream caching
+
+---
+
+## 👨‍💻 About the Author
+
+This package is created by [Uxman Sarwar](https://github.com/uxmansarwar), a full-stack PHP Laravel developer.
+
+- GitHub: [@uxmansarwar](https://github.com/uxmansarwar)
+- LinkedIn: [Uxman Sarwar](https://linkedin.com/in/uxmansarwar)
+- Email: [uxmansrwr@gmail.com](mailto:uxmansrwr@gmail.com)
+
+If you found this package useful, consider ⭐ starring the repo and sharing it with other developers.
+
+---
+
+## 🔗 SEO & GitHub Keywords
+
+PHP API response library, structured API output PHP, response formatter, Laravel response helper, singleton response PHP, uxmansarwar response composer, REST API output PHP, error handler class PHP, api response json PHP, PHP response class Laravel
+
+---
+
+## 📥 Composer Install Reminder
+
+```
+composer require uxmansarwar/response
+```
 
+Happy coding! 🚀