Skip to content

Commit 8ce0a88

Browse files
DaniloWADaniloWA
committed
docs: update How to Use section with detailed explanation and configuration options
1 parent a4a6fd0 commit 8ce0a88

File tree

4 files changed

+896
-248
lines changed

4 files changed

+896
-248
lines changed

‎README.md‎

Lines changed: 355 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@
99

1010
## 📚 Index
1111

12+
<a href="#-how-to-use-resume" style="font-size: 18px; font-weight: bold;">🔍 How to Use</a>
13+
<span style="font-size: 15px; color: #666; ">Overview of the most commonly used methods and their brief descriptions.</span>
14+
1215
- [Features](#-features)
1316
- [Requirements](#-requirements)
1417
- [Installation](#-installation)
@@ -108,6 +111,358 @@ The **Laravel API Response Builder** package integrates several advanced concept
108111

109112
- **Standardized Error Handling:** The package standardizes the way error messages and statuses are generated. It provides a consistent approach to error responses, allowing for easier troubleshooting and improved user experience. Configuration options are available to adjust error message formats and response codes, ensuring that error handling aligns with your application’s requirements.
110113

114+
## 📝 How to Use Resume
115+
116+
In this section, we highlight the two most frequently used methods (**Success** and **Error** ) in the package for quick reference. For a comprehensive overview and detailed explanations of all available methods, including additional functionalities and usage scenarios, please consult the full documentation.
117+
118+
- **Success** - Returns a standard success response with optional data and a default message.
119+
- **SuccessWithMeta** - Returns a success response with data and additional metadata.
120+
- **SuccessWithHeaders** - Returns a success response with data and custom headers included.
121+
- **SuccessWithPagination** - Returns a success response with data and pagination details.
122+
- **Error** - Returns an error response with a specified status code and message.
123+
- **ErrorWithTrace** - Returns an error response with an additional trace for debugging purposes.
124+
- **ErrorWithSuggestions** - Returns an error response with suggestions for resolving the issue.
125+
126+
### Customizing Response Settings
127+
128+
You can customize the response structure and behavior in the package configuration file. Here are some key options:
129+
130+
- **Custom Response Structure:** Modify the default response keys (`status`, `message`, `data`) to fit your API needs.
131+
132+
```php
133+
/*
134+
|--------------------------------------------------------------------------
135+
| Custom Response Structure
136+
|--------------------------------------------------------------------------
137+
| Define a custom structure for responses. The example below includes
138+
| 'status', 'message', and 'data', but you can modify these as needed.
139+
|
140+
*/
141+
'custom_response_structure' => [
142+
'status' => 'status',
143+
'message' => 'message',
144+
'data' => 'data',
145+
],
146+
```
147+
148+
- **Response Data Wrapper:** Enable or disable wrapping the response data in an additional `data` key. This helps maintain a consistent response structure.
149+
150+
```php
151+
/*
152+
|--------------------------------------------------------------------------
153+
| Response Data Wrapper
154+
|--------------------------------------------------------------------------
155+
| If enabled, the response data will be wrapped in an additional 'data'
156+
| key. This is useful if you want a consistent structure for all responses.
157+
|
158+
*/
159+
'wrap_data' => true,
160+
```
161+
162+
- **Response Data Wrapper Key:** Customize the key used to wrap the response data. The default key is `data`, but you can change it according to your API structure.
163+
164+
```php
165+
/*
166+
|--------------------------------------------------------------------------
167+
| Response Data Wrapper Key
168+
|--------------------------------------------------------------------------
169+
| This value sets the key used to wrap the response data. By default, it is
170+
| 'data', but you can customize it according to your API structure.
171+
|
172+
*/
173+
'wrap_data_key' => 'items',
174+
```
175+
176+
These configuration options allow you to tailor the response structure to fit the needs of your application and ensure consistency across your API responses.
177+
178+
---
179+
180+
### success()
181+
182+
**Description:**
183+
184+
The `success()` method returns a JSON response with a successful status code (200) and a success message. This is useful for standardizing success responses in your API.
185+
186+
**Parameters:**
187+
188+
- **`mixed $data`**:
189+
190+
- **Optional**
191+
- **Type**: `array` or `object`
192+
- **Description**: The data to include in the response. This can be any data structure that you want to return to the client.
193+
- **Example**: `['user' => $user]` or `new User($userId)`.
194+
195+
- **`string|null $message`**:
196+
197+
- **Optional**
198+
- **Type**: `string` or `null`
199+
- **Description**: The success message to include in the response. If not provided, a default message will be used. This parameter is optional.
200+
- **Example**: `'User fetched successfully.'` or `null`.
201+
202+
- **`bool|null $wrap`**:
203+
204+
- **Optional**
205+
- **Type**: `bool` or `null`
206+
- **Description**: Determines whether to wrap the data in a wrapper object. If `true`, the data will be wrapped according to the configuration. If `false`, no wrapping will be applied. If `null`, the wrapping behavior will follow the default configuration setting. This parameter is optional.
207+
- **Example**: `true` | `false` or `null` .
208+
209+
- **`string|null $wrapKey`**:
210+
211+
- **Optional**
212+
- **Type**: `string` or `null`
213+
- **Description**: The key for wrapping the data. If specified, the data will be wrapped under this key. If not provided, the default key from the configuration will be used. This parameter is optional.
214+
- **Example**: `'items'` or `null`.
215+
216+
- **`int $statusCode`**:
217+
- **Optional**
218+
- **Type**: `int`
219+
- **Description**: The HTTP status code for the response. Default is `200`, but can be changed if needed.
220+
- **Example**: `200` (for a successful request).
221+
222+
**Returns:**
223+
224+
- **`IlluminateJsonResponse`**: A JSON response object with the provided data and message.
225+
226+
**Usage Examples:**
227+
228+
0. **Default Success Response:**
229+
230+
```php
231+
$response = JsonResponse::success();
232+
```
233+
234+
- **Description**: Returns a JSON response with the user data and a default success message.
235+
- **Example Output:**
236+
```json
237+
{
238+
"status": "success",
239+
"message": "Operation completed successfully.",
240+
"data": null
241+
}
242+
```
243+
244+
1. **Basic Success Response:**
245+
246+
```php
247+
$response = JsonResponse::success(['user' => $user]);
248+
```
249+
250+
- **Description**: Returns a JSON response with the user data and a default success message.
251+
- **Example Output:**
252+
```json
253+
{
254+
"status": "success",
255+
"message": "Operation successful.",
256+
"data": {
257+
"user": {
258+
"id": 1,
259+
"name": "John Doe",
260+
"email": "john.doe@example.com"
261+
}
262+
}
263+
}
264+
```
265+
266+
2. **Success Response with Custom Message:**
267+
268+
```php
269+
$response = JsonResponse::success(['user' => $user], 'User fetched successfully.');
270+
```
271+
272+
- **Description**: Returns a JSON response with the user data and a custom success message.
273+
- **Example Output:**
274+
```json
275+
{
276+
"status": "success",
277+
"message": "User fetched successfully.",
278+
"data": {
279+
"user": {
280+
"id": 1,
281+
"name": "John Doe",
282+
"email": "john.doe@example.com"
283+
}
284+
}
285+
}
286+
```
287+
288+
3. **Success Response with Wrapping:**
289+
```php
290+
$response = JsonResponse::success(['user' => $user], 'User fetched successfully.', true);
291+
```
292+
- **Description**: Returns a JSON response with the user data wrapped under the key `'items'` by default and a custom success message.
293+
- **Example Output:**
294+
```json
295+
{
296+
"status": "success",
297+
"message": "User fetched successfully.",
298+
"data": {
299+
"items": {
300+
"user": {
301+
"id": 1,
302+
"name": "John Doe",
303+
"email": "john.doe@example.com"
304+
}
305+
}
306+
}
307+
}
308+
```
309+
4. **Success Response with Custom Wrap key:**
310+
```php
311+
$response = JsonResponse::success(['user' => $user], 'User fetched successfully.', true, 'customWrap');
312+
```
313+
- **Description**: Returns a JSON response with the user data wrapped under the custom key `'customWrap'` and a custom success message.
314+
- **Example Output:**
315+
```json
316+
{
317+
"status": "success",
318+
"message": "User fetched successfully.",
319+
"data": {
320+
"customWrap": {
321+
"user": {
322+
"id": 1,
323+
"name": "John Doe",
324+
"email": "john.doe@example.com"
325+
}
326+
}
327+
}
328+
}
329+
```
330+
331+
---
332+
333+
### `error()`
334+
335+
**Description:**
336+
337+
The `error()` method returns a JSON response with an error status code and an error message. This is useful for standardizing error responses in your API.
338+
339+
**Parameters:**
340+
341+
- **`int $statusCode`**:
342+
343+
- **Required**
344+
- **Type**: `int`
345+
- **Description**: The HTTP status code to indicate the type of error (e.g., 400 for Bad Request, 404 for Not Found, 500 for Internal Server Error).
346+
- **Example**: `404`.
347+
348+
- **`string|null $message`**:
349+
350+
- **Optional**
351+
- **Type**: `string` or `null`
352+
- **Description**: The error message to include in the response. If not provided, a default error message will be used. This parameter is optional.
353+
- **Example**: `'Resource not found.'` or `null`.
354+
355+
- **`mixed $data`**:
356+
357+
- **Optional**
358+
- **Type**: `array` or `object` or `null`
359+
- **Description**: The data to include in the response. This can be used to provide additional information about the error (e.g., validation errors). If not provided, no additional data will be included. This parameter is optional.
360+
- **Example**: `['field' => 'username', 'error' => 'Username is required.']` or `null`.
361+
362+
- **`bool|null $wrap`**:
363+
364+
- **Optional**
365+
- **Type**: `bool` or `null`
366+
- **Description**: Determines whether to wrap the error data in a wrapper object. If `true`, the data will be wrapped according to the configuration. If `false`, no wrapping will be applied. If `null`, the wrapping behavior will follow the default configuration setting. This parameter is optional.
367+
- **Example**: `true` | `false` or `null`.
368+
369+
- **`string|null $wrapKey`**:
370+
371+
- **Optional**
372+
- **Type**: `string` or `null`
373+
- **Description**: The key for wrapping the error data. If specified, the data will be wrapped under this key. If not provided, the default key from the configuration will be used. This parameter is optional.
374+
- **Example**: `'error'` or `null`.
375+
376+
**Returns:**
377+
378+
- **`IlluminateJsonResponse`**: A JSON response object with the provided status code, message, and data.
379+
380+
**Usage Examples:**
381+
382+
0. **Default Error Response**
383+
384+
```php
385+
$response = JsonResponse::error(404);
386+
```
387+
388+
- **Description**: Returns a JSON response with a `404` status code and a default error message.
389+
- **Example Output:**
390+
```json
391+
{
392+
"status": "error",
393+
"message": "The requested resource could not be found.",
394+
"data": null
395+
}
396+
```
397+
398+
1. **Basic Error Response:**
399+
400+
```php
401+
$response = JsonResponse::error(404, 'Resource not found.');
402+
```
403+
404+
- **Description**: Returns a JSON response with a `404` status code and a default error message.
405+
- **Example Output:**
406+
```json
407+
{
408+
"status": "error",
409+
"message": "Resource not found.",
410+
"data": null
411+
}
412+
```
413+
414+
2. **Error Response with Custom Message and Data:**
415+
416+
```php
417+
$response = JsonResponse::error(400, 'Bad request', ['field' => 'username', 'error' => 'Username is required.']);
418+
```
419+
420+
- **Description**: Returns a JSON response with a `400` status code, a custom error message, and additional data describing the validation error.
421+
- **Example Output:**
422+
```json
423+
{
424+
"status": "error",
425+
"message": "Bad request",
426+
"data": {
427+
"field": "username",
428+
"error": "Username is required."
429+
}
430+
}
431+
```
432+
433+
3. **Error Response with Wrapping:**
434+
```php
435+
$response = JsonResponse::error(500, 'Internal server error', null, true);
436+
```
437+
- **Description**: Returns a JSON response with a `500` status code and the error wrapped under the key `'items'` by default.
438+
- **Example Output:**
439+
```json
440+
{
441+
"status": "error",
442+
"message": "Internal server error",
443+
"data": {
444+
"items": null
445+
}
446+
}
447+
```
448+
4. **Error Response with custom Wrap key:**
449+
```php
450+
$response = JsonResponse::error(500, 'Internal server error', null, true, 'error');
451+
```
452+
- **Description**: Returns a JSON response with a `500` status code and the error wrapped under the custom key `'error'`.
453+
- **Example Output:**
454+
```json
455+
{
456+
"status": "error",
457+
"message": "Internal server error",
458+
"data": {
459+
"error": null
460+
}
461+
}
462+
```
463+
464+
---
465+
111466
## 🌐 Documentation
112467

113468
### [JSON Response](./wiki/json-response.md)

‎composer.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "doliveira/laravel-api-response-builder",
3-
"version": "1.0.7",
3+
"version": "1.0.8",
44
"description": "A Laravel package designed to simplify the creation of structured and formatted API responses (JSON, XML) with custom status codes, messages, and data. XML support is currently under construction.",
55
"type": "library",
66
"license": "MIT",

0 commit comments

Comments
 (0)