Skip to content

Commit ecb0101

Browse files
DaniloWADaniloWA
committed
wip
1 parent 20a1d1f commit ecb0101

File tree

15 files changed

+900
-343
lines changed

15 files changed

+900
-343
lines changed

‎README.md‎

Lines changed: 142 additions & 170 deletions
Original file line numberDiff line numberDiff line change
@@ -1,170 +1,142 @@
1-
# Laravel API Response Builder
2-
3-
**Laravel API Response Builder** is a Laravel package designed to simplify the creation of structured and formatted API responses (JSON, XML) with customizable status codes, messages, and data. This package provides a flexible way to handle API responses, including error handling, logging, and various configuration options.
4-
5-
## Features
6-
7-
- **Structured Responses**: Define custom response structures for consistency.
8-
- **Format Options**: Choose between JSON and XML response formats.
9-
- **Logging**: Log requests and responses for debugging and auditing.
10-
- **Compression**: Optionally compress responses to reduce payload size.
11-
- **Error Handling**: Include detailed error messages for debugging.
12-
13-
## Installation
14-
15-
To install the package, run the following command:
16-
17-
```bash
18-
composer require doliveira/laravel-api-response-builder
19-
```
20-
21-
## Configuration
22-
23-
After installing the package, publish the configuration file using the following command:
24-
25-
```bash
26-
php artisan vendor:publish --provider="Doliveira\LaravelResponseBuilder\Providers\ResponseBuilderServiceProvider"
27-
```
28-
29-
This will create a `config/laravel-api-response-builder.php` file where you can customize the package settings.
30-
31-
## Configuration Options
32-
33-
Here's a brief overview of the available configuration options:
34-
35-
- **`default_format`**: The default format for responses (`'json'` or `'xml'`).
36-
- **`json_options`**: Options for JSON encoding (e.g., `JSON_UNESCAPED_SLASHES`).
37-
- **`xml_root_element`**: The default root element for XML responses.
38-
- **`default_status_code`**: The default HTTP status code for responses.
39-
- **`detailed_errors`**: Whether to include detailed error messages for debugging.
40-
- **`wrap_data`**: Whether to wrap response data in an additional `'data'` key.
41-
- **`default_locale`**: The default locale for custom messages.
42-
- **`default_response_language`**: The default language for responses (`'en'` or `'pt'`).
43-
- **`compress_responses`**: Whether to compress responses.
44-
- **`log_responses`**: Whether to log responses.
45-
- **`logging_level`**: The level of detail for logging responses.
46-
- **`api_key_header`**: The name of the header used for API keys.
47-
- **`custom_response_structure`**: Define a custom structure for responses.
48-
- **`debug_mode`**: Enable or disable debug mode.
49-
- **`log_requests`**: Whether to log requests.
50-
- **`log_response_time`**: Whether to log response times.
51-
52-
## Usage
53-
54-
### JSON Responses
55-
56-
#### Success Response
57-
58-
```php
59-
use Doliveira\LaravelResponseBuilder\JsonResponse;
60-
61-
return JsonResponse::success($data, 'Operation successful.');
62-
```
63-
64-
#### Error Response
65-
66-
```php
67-
use Doliveira\LaravelResponseBuilder\JsonResponse;
68-
69-
return JsonResponse::error(400, 'Bad request.', $data);
70-
```
71-
72-
### XML Responses
73-
74-
To create XML responses, use the `XmlResponse` class:
75-
76-
```php
77-
use Doliveira\LaravelResponseBuilder\XmlResponse;
78-
79-
$response = new XmlResponse($statusCode, $message, $data);
80-
return $response->build();
81-
```
82-
83-
## Error Handling
84-
85-
The package allows you to include detailed error messages for debugging. By default, this is disabled in production environments:
86-
87-
```php
88-
'logging_level' => 'info',
89-
'detailed_errors' => false,
90-
```
91-
92-
You can enable detailed error messages for debugging purposes by setting `'detailed_errors'` to `true` in the configuration.
93-
94-
## Examples
95-
96-
### Success JSON Response
97-
98-
```json
99-
{
100-
"status": 200,
101-
"message": "Operation successful.",
102-
"data": {
103-
"id": 1,
104-
"name": "Example"
105-
}
106-
}
107-
```
108-
109-
### Error JSON Response
110-
111-
```json
112-
{
113-
"status": 400,
114-
"message": "Bad request.",
115-
"data": null
116-
}
117-
```
118-
119-
### Success XML Response
120-
121-
```xml
122-
<response>
123-
<status>200</status>
124-
<message>Operation successful.</message>
125-
<data>
126-
<id>1</id>
127-
<name>Example</name>
128-
</data>
129-
</response>
130-
```
131-
132-
### Error XML Response
133-
134-
```xml
135-
<response>
136-
<status>400</status>
137-
<message>Bad request.</message>
138-
<data/>
139-
</response>
140-
```
141-
142-
## Logging
143-
144-
The package can log requests, responses, and response times. Configure logging settings in `config/laravel-api-response-builder.php`:
145-
146-
```php
147-
'log_responses' => true,
148-
'log_requests' => true,
149-
'log_response_time' => true,
150-
'logging_level' => 'info',
151-
```
152-
153-
## Contributing
154-
155-
If you want to contribute to the development of this package, please fork the repository and submit a pull request.
156-
157-
## License
158-
159-
This package is licensed under the MIT License.
160-
161-
## Contact
162-
163-
For any questions or feedback, please contact:
164-
165-
- **Danilo Oliveira**: [daniloworkdev@gmail.com](mailto:daniloworkdev@gmail.com)
166-
- **Website**: [daniloo.dev](http://www.daniloo.dev)
167-
168-
---
169-
170-
**Note:** The Package is currently under construction and may be updated further. As this is an early release, there may be bugs or incomplete features. We appreciate your understanding and feedback as we continue to improve the package.
1+
# Laravel API Response Builder
2+
3+
<p align="center">
4+
<img src="https://raw.githubusercontent.com/lwwcas/laravel-countries/master/assets/map.jpg" alt="Laravel API Response Builder"/>
5+
</p>
6+
7+
<p align="center">
8+
<img src="https://img.shields.io/packagist/v/doliveira/laravel-api-response-builder" alt="Latest Version" />
9+
<img src="https://img.shields.io/packagist/dt/doliveira/laravel-api-response-builder" alt="Total Downloads" />
10+
11+
</p>
12+
13+
<p align="center">
14+
Welcome to the <strong>Laravel API Response Builder</strong>! This package simplifies the creation of structured and formatted API responses in both JSON and XML formats. It provides customizable status codes, messages, and data handling, making it a versatile tool for managing API responses, including error handling, logging, and extensive configuration options.
15+
</p>
16+
17+
## 📚 Index
18+
19+
- [Installation](#installation)
20+
- [Technologies](#technologies)
21+
- [Concepts & Patterns](#concepts--patterns)
22+
- [Prerequisites](#prerequisites)
23+
- [Documentation](#documentation)
24+
- [Links](#links)
25+
- [Contributing](#contributing)
26+
- [License](#license)
27+
- [Contact](#contact)
28+
29+
## 🚀 Features
30+
31+
- **Structured Responses:** Create consistent JSON and XML responses effortlessly.
32+
- **Customizable Status Codes & Messages:** Adapt responses to fit your requirements.
33+
- **Error Handling & Logging:** Detailed logging for both responses and requests.
34+
- **Flexible Configuration:** Adjust settings for data wrapping, response languages, and more.
35+
36+
## ⚙️ Prerequisites
37+
38+
Ensure your project meets the following requirements before using this package:
39+
40+
- **Laravel Framework:** Version 8.12 or higher.
41+
- **PHP:** Version 7.3 or higher.
42+
- **Composer:** PHP dependency manager.
43+
44+
## 📦 Installation
45+
46+
To integrate the Laravel API Response Builder into your Laravel project, follow these steps:
47+
48+
1. **Install via Composer:**
49+
50+
Run the following command in your terminal:
51+
52+
```bash
53+
composer require doliveira/laravel-api-response-builder
54+
```
55+
56+
2. **Publish the Configuration:**
57+
58+
After installation, publish the configuration file:
59+
60+
```bash
61+
php artisan vendor:publish --provider="Doliveira\LaravelResponseBuilder\Providers\ResponseBuilderServiceProvider"
62+
```
63+
64+
This will create a configuration file at `config/responsebuilder.php` where you can customize the package settings.
65+
66+
3. **Configuration:**
67+
68+
Open the `config/responsebuilder.php` file and adjust the settings as needed for your project. Configure options such as data wrappers, API key headers, and logging preferences.
69+
70+
## 🧰 Technologies
71+
72+
The **Laravel API Response Builder** utilizes the following technologies:
73+
74+
- **Laravel Framework:** A PHP framework for web applications.
75+
- **PHP:** The server-side scripting language.
76+
- **JSON:** Data format for API responses.
77+
- **XML:** Data format for API responses (currently under development).
78+
- **Log:** Laravel's logging facilities for recording response details.
79+
80+
Claro, aqui está uma versão aprimorada para a seção "Concepts & Patterns", baseada no código e na funcionalidade descrita:
81+
82+
---
83+
84+
## 📚 Concepts & Patterns
85+
86+
The **Laravel API Response Builder** package integrates several advanced concepts and patterns designed to enhance API response management:
87+
88+
- **Response Wrapping:** This pattern wraps your response data in a unified format, ensuring consistency across all API responses. It includes customizable data wrappers that can be adjusted through the `config/responsebuilder.php` configuration file. This approach simplifies response handling and provides a clear structure for both successful and error responses.
89+
90+
- **Detailed Logging:** The package offers comprehensive logging capabilities for both responses and requests. Using Laravel’s built-in logging facilities, it captures key details such as response status, headers, and content. This feature supports various logging levels and allows you to specify log file paths, enabling efficient debugging and monitoring of your API interactions.
91+
92+
- **Flexible Configuration Management:** Leveraging Laravel’s configuration system, the package provides extensive options for customizing the response structure. You can easily configure data wrappers, API key headers, default status codes, and response languages. This flexibility allows you to tailor the package’s behavior to fit the specific needs of your project.
93+
94+
- **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.
95+
96+
## 🌐 Documentation
97+
98+
### [JSON Response](#json-response)
99+
100+
- **Auto** - [Description](#) | [Examples](#)
101+
- **Success** - [Description](#) | [Examples](#)
102+
- **Error** - [Description](#) | [Examples](#)
103+
104+
### [Config](#config)
105+
106+
- **Custom Response Structure** - [Details](#custom-response-structure)
107+
- [Data Wrapper](#data-wrapper)
108+
- [API Key Header](#api-key-header)
109+
- [Response Language](#response-language)
110+
- [Default Status Code](#default-status-code)
111+
- [JSON Options](#json-options)
112+
- **Logs** - [Details](#logs)
113+
- [Log Responses](#log-responses)
114+
- [Request Logging](#request-logging)
115+
- [Response Time Logging](#response-time-logging)
116+
- [Logging Level](#logging-level)
117+
- [Log Files Path](#log-files-path)
118+
119+
## 🔗 Links
120+
121+
- [Official Documentation](#documentation)
122+
- [GitHub Repository](https://github.com/doliveira/laravel-api-response-builder)
123+
- [Support & Issues](https://github.com/doliveira/laravel-api-response-builder/issues)
124+
125+
## 🤝 Contributing
126+
127+
To contribute to the development of this package, please fork the repository and submit a pull request.
128+
129+
## 📝 License
130+
131+
This package is licensed under the MIT License.
132+
133+
## 📬 Contact
134+
135+
For any questions or feedback, please reach out to:
136+
137+
- **Danilo Oliveira:** [daniloworkdev@gmail.com](mailto:daniloworkdev@gmail.com)
138+
- **Website:** [daniloo.dev](http://www.daniloo.dev)
139+
140+
---
141+
142+
**Note:** This package is currently under development, and XML support is still in progress. As an early release, there might be bugs or incomplete features. We appreciate your patience and feedback.

0 commit comments

Comments
 (0)