Laravel API Response

https://github.com/creativecrafts/laravel-api-response
Admin
Laravel API Response is a powerful and flexible package that provides a standardized way to...
Tokens:11,477
Snippets:68
Trust Score:6.4
License:MIT
Update:9 months ago
Show doc for...
Tokens:
Raw
### Content Negotiation with JSON and XML in API

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

This example demonstrates content negotiation for API responses using cURL. It shows how to request data in JSON (default) and XML formats by setting the 'Accept' header. The server then responds with the appropriate content type, enabling clients to choose their preferred data format.

```bash
# Request JSON (default)
curl -X GET "https://api.example.com/users" \
  -H "Accept: application/json"

# Response (JSON):
# {
#     "success": true,
#     "message": "Users retrieved",
#     "data": [{"id": 1, "name": "John"}],
#     "api_version": "1.0"
# }

# Request XML
curl -X GET "https://api.example.com/users" \
  -H "Accept: application/xml"

# Response (XML):
# <?xml version="1.0"?>
# <root>
#     <success>true</success>
#     <message>Users retrieved</message>
#     <data>
#         <item_0>
#             <id>1</id>
#             <name>John</name>
#         </item_0>
#     </data>
#     <api_version>1.0</api_version>
# </root>
```

--------------------------------

### Install Laravel API Response Package

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Installs the Laravel API Response package using Composer. This is the first step to integrate the package into your Laravel project.

```bash
composer require creativecrafts/laravel-api-response
```

--------------------------------

### Basic API Response with Facade (PHP)

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Illustrates using the `LaravelApiResponse` facade within controllers to create standardized API responses. Examples include retrieving a single user and creating a new user with a 201 status code.

```php
<?php

namespace App\Http\Controllers;

use App\Models\User;
use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;

class UserController extends Controller
{
    public function show(int $id)
    {
        $user = User::findOrFail($id);

        return LaravelApiResponse::successResponse(
            message: 'User retrieved successfully',
            data: $user->toArray()
        );
    }

    public function store(Request $request)
    {
        $user = User::create($request->validated());

        return LaravelApiResponse::successResponse(
            message: 'User created successfully',
            data: $user->toArray(),
            statusCode: 201
        );
    }
}

// Response output (201 Created):
// {
//     "success": true,
//     "message": "User created successfully",
//     "data": {"id": 3, "name": "New User", "email": "new@example.com"},
//     "api_version": "1.0"
// }
```

--------------------------------

### Run Package Tests (Bash)

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Execute the package's test suite using Composer. This command runs all defined tests to ensure the package is functioning correctly.

```bash
composer test
```

--------------------------------

### Basic Success Response using Facade

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Illustrates how to return a success response using the LaravelApiResponse facade. This provides a more idiomatic Laravel approach to accessing package functionality.

```php
use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;

class UserController extends Controller
{
    public function index()
    {
        $users = User::all();
        return LaravelApiResponse::successResponse('Users retrieved successfully', $users);
    }
}
```

--------------------------------

### Basic Success Response using Dependency Injection

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Demonstrates how to return a success response using the LaravelApi class injected into a controller. It includes fetching all users and returning them with a success message.

```php
use CreativeCrafts\LaravelApiResponse\LaravelApi;

class UserController extends Controller
{
    protected $api;

    public function __construct(LaravelApi $api)
    {
        $this->api = $api;
    }

    public function index()
    {
        $users = User::all();
        return $this->api->successResponse('Users retrieved successfully', $users);
    }
}
```

--------------------------------

### Generating Success Responses with Options (PHP)

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Shows various ways to utilize the `successResponse` method, including basic responses, responses with custom status codes, and responses incorporating HATEOAS links for hypermedia navigation.

```php
<?php

use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;

// Basic success response
return LaravelApiResponse::successResponse(
    message: 'Operation completed successfully',
    data: ['id' => 1, 'name' => 'Product A', 'price' => 29.99]
);

// Success response with custom status code
return LaravelApiResponse::successResponse(
    message: 'Resource created',
    data: ['id' => 42, 'title' => 'New Article'],
    statusCode: 201
);

// Success response with HATEOAS links
return LaravelApiResponse::successResponse(
    message: 'User retrieved',
    data: ['id' => 1, 'name' => 'John Doe', 'email' => 'john@example.com'],
    links:
        [
            'self' => ['href' => '/api/users/1'],
            'posts' => ['href' => '/api/users/1/posts'],
            'profile' => ['href' => '/api/users/1/profile']
        ]
);

// Response output:
// {
//     "success": true,
//     "message": "User retrieved",
//     "data": {"id": 1, "name": "John Doe", "email": "john@example.com"},
//     "_links": {
//         "self": {"href": "/api/users/1"},
//         "posts": {"href": "/api/users/1/posts"},
//         "profile": {"href": "/api/users/1/profile"}
//     },
//     "api_version": "1.0"
// }
```

--------------------------------

### Enable API Response Compression (PHP)

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Configure whether API response compression is enabled. This setting is controlled by an environment variable, defaulting to true if not specified.

```php
'enable_compression' => env('API_RESPONSE_COMPRESSION', true),
```

--------------------------------

### Add Custom Response Methods (Macros) in Laravel

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Demonstrates how to extend the Laravel API Response functionality by adding custom response methods (macros) using the Macroable trait. This allows for reusable, predefined response formats for common scenarios like asynchronous operations or specific HTTP status codes. It requires registering these macros in the AppServiceProvider's boot method.

```php
<?php

use CreativeCrafts\LaravelApiResponse\LaravelApi;
use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;
use Illuminate\Support\Facades\Response;

// In AppServiceProvider boot() method:
public function boot()
{
    // Custom "accepted" response for async operations
    LaravelApi::macro('acceptedResponse', function (string $message, string $jobId) {
        return Response::json([
            'success' => true,
            'message' => $message,
            'job_id' => $jobId,
            'status_url' => "/api/jobs/{$jobId}/status"
        ], 202);
    });

    // Custom "teapot" response (RFC 2324)
    LaravelApi::macro('teapotResponse', function (string $message = "I'm a teapot") {
        return Response::json(['message' => $message], 418);
    });

    // Custom maintenance mode response
    LaravelApi::macro('maintenanceResponse', function (string $message = 'Service temporarily unavailable') {
        return Response::json([
            'success' => false,
            'message' => $message,
            'retry_after' => 3600
        ], 503);
    });
}

// Usage in controllers:
class JobController extends Controller
{
    public function startLongRunningJob(Request $request)
    {
        $jobId = dispatch(new ProcessLargeDataset($request->all()));

        return LaravelApiResponse::acceptedResponse(
            message: 'Job queued for processing',
            jobId: $jobId
        );
    }
}

// Response output (202 Accepted):
// {
//     "success": true,
//     "message": "Job queued for processing",
//     "job_id": "abc123-def456",
//     "status_url": "/api/jobs/abc123-def456/status"
// }
```

--------------------------------

### Publish Laravel API Response Configuration

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Publishes the default configuration file for the Laravel API Response package to your application's config directory. This allows for customization of package behavior.

```bash
php artisan vendor:publish --tag=api-response-config
```

--------------------------------

### Return a Paginated API Response

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Shows how to return a paginated response for collections of data. This integrates with Laravel's built-in pagination system to provide paginated results to the API consumer.

```php
$users = User::paginate(15);
return $this->api->paginatedResponse('Users retrieved successfully', $users);
```

--------------------------------

### Return a Success API Response

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Shows the basic syntax for returning a success response from an API endpoint. This method is used to indicate that an operation was completed successfully and to return associated data.

```php
return $this->api->successResponse('Operation successful', $data);
```

--------------------------------

### Custom Error Code Mappings

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Allows defining custom error codes and their corresponding details (title, description, help URL) for more structured and informative error responses.

```APIDOC
## Custom Error Code Mappings

### Description
Define custom error code mappings for detailed error responses.

### Method
POST (Implicitly, as it's a controller method returning a response)

### Endpoint
Not explicitly defined, depends on the route configuration.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
<?php

use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;

class ApiController extends Controller
{
    public function __construct()
    {
        // Set up custom error code mappings
        LaravelApiResponse::setErrorCodeMappings([
            1001 => [
                'title' => 'Invalid Input',
                'description' => 'The provided input data is invalid',
                'help_url' => 'https://docs.example.com/errors/1001'
            ],
            1002 => [
                'title' => 'Resource Conflict',
                'description' => 'The resource already exists or conflicts with existing data',
                'help_url' => 'https://docs.example.com/errors/1002'
            ],
            2001 => [
                'title' => 'Payment Failed',
                'description' => 'The payment could not be processed',
                'help_url' => 'https://docs.example.com/errors/2001'
            ]
        ]);
    }

    public function processPayment(Request $request)
    {
        // Payment processing fails
        return LaravelApiResponse::errorResponse(
            message: 'Payment processing failed',
            statusCode: 402,
            errorCode: 2001
        );
    }
}
```

### Response
#### Error Response (e.g., 402)
A JSON object containing error details, including custom mapped information.

#### Response Example
```json
{
    "success": false,
    "message": "Payment processing failed",
    "error_code": 2001,
    "error_details": {
        "title": "Payment Failed",
        "description": "The payment could not be processed",
        "help_url": "https://docs.example.com/errors/2001"
    },
    "api_version": "1.0"
}
```
```

--------------------------------

### Return a Conditional API Response

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Illustrates how to return a conditional response, which is useful for caching and conditional requests. This method automatically handles ETag and Last-Modified headers.

```php
return $this->api->conditionalResponse($data, 'Data retrieved successfully');
```

--------------------------------

### Generate Partial Response with Sparse Fieldsets (PHP)

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Constructs an API response that includes only the fields explicitly requested by the client via a 'fields' query parameter. This is useful for optimizing bandwidth and reducing response payload size by allowing clients to specify exactly the data they need.

```php
<?php

use App\Models\User;
use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;

class UserController extends Controller
{
    public function show(Request $request, int $id)
    {
        $user = User::findOrFail($id);

        // Client requests: GET /api/users/1?fields=id,name,email
        $requestedFields = $request->has('fields')
            ? explode(',', $request->input('fields'))
            : [];

        return LaravelApiResponse::partialResponse(
            data: $user->toArray(),
            fields: $requestedFields,
            message: 'User retrieved successfully'
        );
    }
}

// Request: GET /api/users/1?fields=id,name,email
// Response output (only requested fields):
// {
//     "success": true,
//     "message": "User retrieved successfully",
//     "data": {
//         "id": 1,
//         "name": "John Doe",
//         "email": "john@example.com"
//     },
//     "api_version": "1.0"
// }

// Note: Other fields like created_at, updated_at, etc. are excluded

```

--------------------------------

### Metadata Response

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Generates a response that includes API metadata, such as version, available endpoints, and additional custom information like documentation links or support emails.

```APIDOC
## metadataResponse

### Description
Generate a response with API metadata including available endpoints.

### Method
POST (Implicitly, as it's a controller method returning a response)

### Endpoint
Not explicitly defined, depends on the route configuration.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
<?php

use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;

class ApiController extends Controller
{
    public function metadata()
    {
        return LaravelApiResponse::metadataResponse(
            additionalInfo: [
                'documentation' => 'https://api.example.com/docs',
                'support_email' => 'api-support@example.com',
                'rate_limits' => [
                    'requests_per_minute' => 60,
                    'burst_limit' => 100
                ]
            ]
        );
    }
}
```

### Response
#### Success Response (200)
A JSON object containing API version, endpoints, and additional information.

#### Response Example
```json
{
    "success": true,
    "message": "API Metadata",
    "data": {
        "version": "1.0",
        "endpoints": [
            {"uri": "api/users", "methods": ["GET", "HEAD", "POST"], "name": "users.index"},
            {"uri": "api/users/{id}", "methods": ["GET", "HEAD"], "name": "users.show"},
            {"uri": "api/posts", "methods": ["GET", "HEAD"], "name": "posts.index"}
        ],
        "additional_info": {
            "documentation": "https://api.example.com/docs",
            "support_email": "api-support@example.com",
            "rate_limits": {"requests_per_minute": 60, "burst_limit": 100}
        }
    },
    "api_version": "1.0"
}
```
```

--------------------------------

### Configure API Rate Limiting

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Provides configuration options for API rate limiting. These settings, typically found in the `laravel-api-response.php` config file, control the maximum number of attempts and the decay time for rate limits.

```php
'rate_limit_max_attempts' => env('API_RATE_LIMIT_MAX_ATTEMPTS', 60),
'rate_limit_decay_minutes' => env('API_RATE_LIMIT_DECAY_MINUTES', 1),
```

--------------------------------

### Configure API Response Logging Channel (PHP)

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Specify the logging channel used for API responses. This allows for centralized logging of API interactions. The default channel is 'api'.

```php
'log_channel' => 'api',
```

--------------------------------

### Partial Response (Sparse Fieldsets) API

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Generates a response that includes only the fields explicitly requested by the client, allowing for reduced payload size and improved performance.

```APIDOC
## GET /api/users/{id}?fields={field1},{field2},...

### Description
Retrieves a user's data, returning only the fields specified in the `fields` query parameter.

### Method
GET

### Endpoint
`/api/users/{id}`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the user.

#### Query Parameters
- **fields** (string) - Optional - A comma-separated list of fields to include in the response.

### Request Example
```php
<?php

use AppModelsUser;
use CreativeCraftsLaravelApiResponseFacadesLaravelApiResponse;

class UserController extends Controller
{
    public function show(Request $request, int $id)
    {
        $user = User::findOrFail($id);

        // Client requests: GET /api/users/1?fields=id,name,email
        $requestedFields = $request->has('fields')
            ? explode(',', $request->input('fields'))
            : [];

        return LaravelApiResponse::partialResponse(
            data: $user->toArray(),
            fields: $requestedFields,
            message: 'User retrieved successfully'
        );
    }
}
```

### Response
#### Success Response (200 OK)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the outcome of the request.
- **data** (object) - Contains the user data, including only the requested fields.
  - **[field]** (any) - The requested field and its value.
- **api_version** (string) - The version of the API.

#### Example Response
```json
{
    "success": true,
    "message": "User retrieved successfully",
    "data": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com"
    },
    "api_version": "1.0"
}
```

**Note**: Fields not specified in the `fields` query parameter will be excluded from the response.
```

--------------------------------

### Include HATEOAS Links in API Responses (PHP)

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Add HATEOAS (Hypermedia as the Engine of Application State) links to API responses. This allows clients to discover related resources. The links are provided as an array of relationship keys and their corresponding href values.

```php
$links = [
    'self' => ['href' => '/api/users/1'],
    'posts' => ['href' => '/api/users/1/posts'],
];

return $this->api->successResponse('User retrieved', $userData, 200, [], $links);
```

--------------------------------

### Localize API Messages (PHP)

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Translate messages using the package's localization feature. The `localize` method takes a message key as input and returns the translated string.

```php
$message = $this->api->localize('messages.welcome');
```

--------------------------------

### Enable Custom API Exception Handler (PHP)

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Configure the custom exception handler to automatically format exceptions into consistent API error responses. This is enabled by default and can be controlled via an environment variable.

```php
'use_exception_handler' => env('API_USE_EXCEPTION_HANDLER', true),
```

--------------------------------

### Generate Bulk Operation Response (PHP)

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Creates a response structure for reporting the results of multiple operations performed in a single request. It aggregates the success or failure status of each individual operation, providing detailed feedback for bulk actions.

```php
<?php

use App\Models\User;
use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;

class UserController extends Controller
{
    public function bulkUpdate(Request $request)
    {
        $operations = [];

        foreach ($request->input('users') as $index => $userData) {
            try {
                $user = User::findOrFail($userData['id']);
                $user->update($userData);

                $operations[$index] = [
                    'success' => true,
                    'message' => "User {$user->id} updated successfully",
                    'data' => $user->toArray()
                ];
            } catch (\Exception $e) {
                $operations[$index] = [
                    'success' => false,
                    'message' => "Failed to update user: {$e->getMessage()}",
                    'error_code' => 1001
                ];
            }
        }

        return LaravelApiResponse::bulkOperationResponse(
            operations: $operations,
            message: 'Bulk update completed'
        );
    }
}

// Response output:
// {
//     "success": false,  // false if any operation failed
//     "message": "Bulk update completed",
//     "operations": {
//         "0": {
//             "success": true,
//             "message": "User 1 updated successfully",
//             "data": {"id": 1, "name": "Updated Name", "email": "user@example.com"}
//         },
//         "1": {
//             "success": false,
//             "message": "Failed to update user: No query results for model [App\Models\User]",
//             "error_code": 1001
//         }
//     },
//     "api_version": "1.0"
// }
```

--------------------------------

### Customize API Response Structure (PHP)

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Define the structure of API responses by configuring keys for success, messages, data, errors, and metadata. This allows for a consistent response format across your API.

```php
'response_structure' => [
    'success_key' => 'success',
    'message_key' => 'message',
    'data_key' => 'data',
    'errors_key' => 'errors',
    'error_code_key' => 'error_code',
    'meta_key' => 'meta',
    'links_key' => '_links',
    'include_api_version' => true,
],
```

--------------------------------

### Return an Error API Response

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Demonstrates how to return an error response from an API endpoint. This method is used to signal that an error occurred during the operation, providing an error message, code, and status code.

```php
return $this->api->errorResponse('An error occurred', $errorCode, $statusCode);
```

--------------------------------

### Configure API Exception Handler in Laravel

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

This snippet shows how to configure the API response package's exception handler in Laravel. It enables automatic exception conversion to API responses and specifies environments where detailed exception information should be displayed. This reduces boilerplate error handling in controllers.

```php
<?php

// config/api-response.php
return [
    // Enable automatic exception handling
    'use_exception_handler' => env('API_USE_EXCEPTION_HANDLER', true),

    // Environments where exception details are shown
    'show_exception_environments' => ['local', 'testing', 'development'],
];

// The exception handler automatically converts:
// - ValidationException -> 422 validation error response
// - ModelNotFoundException -> 404 "Resource not found"
// - AuthenticationException -> 401 "Unauthenticated"
// - AuthorizationException -> 403 "Unauthorized"
// - NotFoundHttpException -> 404 "Endpoint not found"
// - HttpException -> Appropriate status code with message
// - Other exceptions -> 500 "Server Error"

// Example: When a model is not found
use Illuminate\Routing\Controller;
use App\Models\User;
use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;

class UserController extends Controller
{
    public function show(int $id)
    {
        // If user doesn't exist, ModelNotFoundException is automatically
        // converted to a proper API response
        $user = User::findOrFail($id);

        return LaravelApiResponse::successResponse(
            message: 'User found',
            data: $user->toArray()
        );
    }
}

// Automatic response when User not found:
// {
//     "success": false,
//     "message": "Resource not found",
//     "error_code": 1,
//     "api_version": "1.0"
// }
```

--------------------------------

### Extend API Response with Custom Methods (PHP)

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Add custom response methods to the LaravelApi class using Laravel's Macroable trait. This enables extending the package's functionality without modifying its core code.

```php
use CreativeCrafts\LaravelApiResponse\LaravelApi;
use Illuminate\Support\Facades\Response;

LaravelApi::macro('teapotResponse', function ($message = "I'm a teapot") {
    return Response::json(['message' => $message], 418);
});

// Then in your controller:
return $this->api->teapotResponse();
// Or using the facade:
return LaravelApiResponse::teapotResponse("Custom teapot message");
```

--------------------------------

### Define Custom Error Code Mappings - PHP

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Allows defining custom error code mappings for detailed error responses. This is achieved by calling `setErrorCodeMappings` on the LaravelApiResponse facade, providing an array where keys are error codes and values are objects containing title, description, and help URL.

```php
<?php

use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;

class ApiController extends Controller
{
    public function __construct()
    {
        // Set up custom error code mappings
        LaravelApiResponse::setErrorCodeMappings([
            1001 => [
                'title' => 'Invalid Input',
                'description' => 'The provided input data is invalid',
                'help_url' => 'https://docs.example.com/errors/1001'
            ],
            1002 => [
                'title' => 'Resource Conflict',
                'description' => 'The resource already exists or conflicts with existing data',
                'help_url' => 'https://docs.example.com/errors/1002'
            ],
            2001 => [
                'title' => 'Payment Failed',
                'description' => 'The payment could not be processed',
                'help_url' => 'https://docs.example.com/errors/2001'
            ]
        ]);
    }

    public function processPayment(Request $request)
    {
        // Payment processing fails
        return LaravelApiResponse::errorResponse(
            message: 'Payment processing failed',
            statusCode: 402,
            errorCode: 2001
        );
    }
}

// Response output:
// {
//     "success": false,
//     "message": "Payment processing failed",
//     "error_code": 2001,
//     "error_details": {
//         "title": "Payment Failed",
//         "description": "The payment could not be processed",
//         "help_url": "https://docs.example.com/errors/2001"
//     },
//     "api_version": "1.0"
// }
```

--------------------------------

### Bulk Operation Response API

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Handles responses for bulk operations, providing individual results for each operation within the batch. It indicates overall success or failure based on the individual outcomes.

```APIDOC
## POST /api/users/bulk-update

### Description
Performs bulk updates on user records and returns the results of each individual operation.

### Method
POST

### Endpoint
`/api/users/bulk-update`

### Parameters
#### Request Body
- **users** (array) - Required - An array of user data objects, each containing an 'id' and fields to update.
  - **id** (integer) - Required - The ID of the user to update.
  - **[field]** (any) - Optional - Fields to update for the user.

### Request Example
```php
<?php

use AppModelsUser;
use CreativeCraftsLaravelApiResponseFacadesLaravelApiResponse;

class UserController extends Controller
{
    public function bulkUpdate(Request $request)
    {
        $operations = [];

        foreach ($request->input('users') as $index => $userData) {
            try {
                $user = User::findOrFail($userData['id']);
                $user->update($userData);

                $operations[$index] = [
                    'success' => true,
                    'message' => "User {$user->id} updated successfully",
                    'data' => $user->toArray()
                ];
            } catch (Exception $e) {
                $operations[$index] = [
                    'success' => false,
                    'message' => "Failed to update user: {$e->getMessage()}",
                    'error_code' => 1001
                ];
            }
        }

        return LaravelApiResponse::bulkOperationResponse(
            operations: $operations,
            message: 'Bulk update completed'
        );
    }
}
```

### Response
#### Success Response (200 OK)
- **success** (boolean) - `false` if any individual operation failed, `true` otherwise.
- **message** (string) - A message indicating the completion of the bulk operation.
- **operations** (object) - An object containing the results of each individual operation, keyed by their original index.
  - **[index]** (object) - Result of a single operation.
    - **success** (boolean) - Indicates if this specific operation succeeded.
    - **message** (string) - A message describing the outcome of this operation.
    - **data** (object) - The updated user data, if the operation was successful.
    - **error_code** (integer) - An error code, if the operation failed.
- **api_version** (string) - The version of the API.

#### Example Response
```json
{
    "success": false,
    "message": "Bulk update completed",
    "operations": {
        "0": {
            "success": true,
            "message": "User 1 updated successfully",
            "data": {"id": 1, "name": "Updated Name", "email": "user@example.com"}
        },
        "1": {
            "success": false,
            "message": "Failed to update user: No query results for model [App\Models\User]",
            "error_code": 1001
        }
    },
    "api_version": "1.0"
}
```
```

--------------------------------

### Generate Conditional Response with Caching Headers (PHP)

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Generates an API response with ETag and Last-Modified headers for efficient client-side caching. If the client's cached data is still valid (based on If-None-Match or If-Modified-Since headers), it returns a 304 Not Modified status. Otherwise, it returns the updated data with a 200 OK status.

```php
<?php

use App\Models\Article;
use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;

class ArticleController extends Controller
{
    public function show(int $id)
    {
        $article = Article::findOrFail($id);

        return LaravelApiResponse::conditionalResponse(
            data: [
                'id' => $article->id,
                'title' => $article->title,
                'content' => $article->content,
                'updated_at' => $article->updated_at->toIso8601String()
            ],
            message: 'Article retrieved successfully'
        );
    }
}

// Response headers:
// ETag: "a1b2c3d4e5f6..."
// Last-Modified: Mon, 01 Jan 2024 12:00:00 GMT
// Cache-Control: private, must-revalidate

// If client sends If-None-Match or If-Modified-Since headers and content
// hasn't changed, returns 304 Not Modified with no body.

// Response output (200 OK when content changed):
// {
//     "success": true,
//     "message": "Article retrieved successfully",
//     "data": {
//         "id": 1,
//         "title": "Sample Article",
//         "content": "Article content here...",
//         "updated_at": "2024-01-01T12:00:00+00:00"
//     },
//     "api_version": "1.0"
// }
```

--------------------------------

### Specify Custom HTTP Status Codes (PHP)

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Set custom HTTP status codes for API responses. This allows you to accurately reflect the outcome of an API request, such as resource creation (201).

```php
return $this->api->successResponse('Resource created', $newResource, 201);
```

--------------------------------

### Conditional Response API

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Generates a conditional response with ETag and Last-Modified headers for efficient client-side caching. If the client's cached data is up-to-date, a 304 Not Modified response is returned.

```APIDOC
## GET /api/articles/{id}

### Description
Retrieves a specific article with caching headers.

### Method
GET

### Endpoint
`/api/articles/{id}`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the article.

### Request Example
```php
<?php

use AppModelsArticle;
use CreativeCraftsLaravelApiResponseFacadesLaravelApiResponse;

class ArticleController extends Controller
{
    public function show(int $id)
    {
        $article = Article::findOrFail($id);

        return LaravelApiResponse::conditionalResponse(
            data: [
                'id' => $article->id,
                'title' => $article->title,
                'content' => $article->content,
                'updated_at' => $article->updated_at->toIso8601String()
            ],
            message: 'Article retrieved successfully'
        );
    }
}
```

### Response
#### Success Response (200 OK)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the outcome of the request.
- **data** (object) - Contains the article details.
  - **id** (integer) - The article's ID.
  - **title** (string) - The article's title.
  - **content** (string) - The article's content.
  - **updated_at** (string) - The timestamp when the article was last updated.
- **api_version** (string) - The version of the API.

#### Example Response (200 OK)
```json
{
    "success": true,
    "message": "Article retrieved successfully",
    "data": {
        "id": 1,
        "title": "Sample Article",
        "content": "Article content here...",
        "updated_at": "2024-01-01T12:00:00+00:00"
    },
    "api_version": "1.0"
}
```

#### Not Modified Response (304 Not Modified)
Returned when the client's cached version is up-to-date. No response body is included.

#### Response Headers (for 200 OK)
- **ETag**: `"a1b2c3d4e5f6..."`
- **Last-Modified**: `Mon, 01 Jan 2024 12:00:00 GMT`
- **Cache-Control**: `private, must-revalidate`
```

--------------------------------

### Generate Error Response (PHP)

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Creates a standardized error response for API requests. It can include a custom message, status code, error code, and optionally, exception details and HATEOAS links. This is useful for handling various error scenarios in your API.

```php
<?php

use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;
use Exception;

// Basic error response
return LaravelApiResponse::errorResponse(
    message: 'Resource not found',
    statusCode: 404
);

// Error response with custom error code
return LaravelApiResponse::errorResponse(
    message: 'Invalid request parameters',
    statusCode: 400,
    errorCode: 1001
);

// Error response with exception details (shown in local/development environments)
try {
    // Some operation that throws an exception
    throw new Exception('Database connection failed');
} catch (Exception $e) {
    return LaravelApiResponse::errorResponse(
        message: 'An error occurred while processing your request',
        statusCode: 500,
        throwable: $e,
        errorCode: 5001
    );
}

// Response output (in development):
// {
//     "success": false,
//     "message": "An error occurred while processing your request",
//     "error_code": 5001,
//     "exception": {
//         "message": "Database connection failed",
//         "file": "/app/Http/Controllers/ApiController.php",
//         "line": 45,
//         "code": 0,
//         "trace": [...]
//     },
//     "api_version": "1.0"
// }
```

--------------------------------

### Generate API Metadata Response - PHP

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Generates a response containing API metadata, including version information, available endpoints, and additional custom information. This function utilizes the LaravelApiResponse facade and accepts an array of additional data.

```php
<?php

use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;

class ApiController extends Controller
{
    public function metadata()
    {
        return LaravelApiResponse::metadataResponse(
            additionalInfo: [
                'documentation' => 'https://api.example.com/docs',
                'support_email' => 'api-support@example.com',
                'rate_limits' => [
                    'requests_per_minute' => 60,
                    'burst_limit' => 100
                ]
            ]
        );
    }
}

// Response output:
// {
//     "success": true,
//     "message": "API Metadata",
//     "data": {
//         "version": "1.0",
//         "endpoints": [
//             {"uri": "api/users", "methods": ["GET", "HEAD", "POST"], "name": "users.index"},
//             {"uri": "api/users/{id}", "methods": ["GET", "HEAD"], "name": "users.show"},
//             {"uri": "api/posts", "methods": ["GET", "HEAD"], "name": "posts.index"}
//         ],
//         "additional_info": {
//             "documentation": "https://api.example.com/docs",
//             "support_email": "api-support@example.com",
//             "rate_limits": {"requests_per_minute": 60, "burst_limit": 100}
//         }
//     },
//     "api_version": "1.0"
// }
```

--------------------------------

### Update API Response Structure Dynamically in Laravel

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Illustrates how to temporarily override the API response structure keys at runtime for a specific API endpoint or controller action. This is achieved using the `updateResponseStructure` method provided by the Laravel API Response facade. This method allows for flexible response formatting without altering the global configuration.

```php
<?php

use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;

class ApiController extends Controller
{
    public function customFormatEndpoint(Request $request)
    {
        // Update response structure for this specific response
        LaravelApiResponse::updateResponseStructure([
            'data_key' => 'payload',
            'message_key' => 'info'
        ]);

        return LaravelApiResponse::successResponse(
            message: 'Custom formatted response',
            data: ['key' => 'value']
        );
    }
}

// Response output with updated structure:
// {
//     "success": true,
//     "info": "Custom formatted response",
//     "payload": {"key": "value"},
//     "api_version": "1.0"
// }
```

--------------------------------

### Streamed Response

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Generates a streamed response suitable for large datasets or real-time data. This is useful for exporting large amounts of data without consuming excessive memory.

```APIDOC
## streamResponse

### Description
Generate a streamed response for large datasets or real-time data.

### Method
POST (Implicitly, as it's a controller method returning a response)

### Endpoint
Not explicitly defined, depends on the route configuration in `routes/api.php` or `routes/web.php`.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
<?php

use AppModels\Order;
use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;

class ReportController extends Controller
{
    public function exportOrders()
    {
        $dataGenerator = function () {
            // Process orders in chunks to avoid memory issues
            Order::with('items')->chunk(100, function ($orders) {
                foreach ($orders as $order) {
                    yield [
                        'order_id' => $order->id,
                        'customer' => $order->customer_name,
                        'total' => $order->total,
                        'status' => $order->status,
                        'created_at' => $order->created_at->toIso8601String()
                    ];
                }
            });
        };

        return LaravelApiResponse::streamResponse(
            dataGenerator: $dataGenerator,
            message: 'Exporting orders'
        );
    }
}
```

### Response
#### Success Response (200)
Streamed line by line, each line is a JSON object.

#### Response Example
```json
{"success":true,"message":"Exporting orders","api_version":"1.0"}
{"order_id":1,"customer":"John Doe","total":150.00,"status":"completed","created_at":"2024-01-01T10:00:00+00:00"}
{"order_id":2,"customer":"Jane Doe","total":200.00,"status":"pending","created_at":"2024-01-02T11:30:00+00:00"}
...
```
```

--------------------------------

### Generate Streamed Response for Large Datasets - PHP

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Generates a streamed response suitable for large datasets or real-time data. It processes data in chunks to prevent memory issues and yields data row by row. This function requires the 'Order' model and the LaravelApiResponse facade.

```php
<?php

use App\Models\Order;
use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;

class ReportController extends Controller
{
    public function exportOrders()
    {
        $dataGenerator = function () {
            // Process orders in chunks to avoid memory issues
            Order::with('items')->chunk(100, function ($orders) {
                foreach ($orders as $order) {
                    yield [
                        'order_id' => $order->id,
                        'customer' => $order->customer_name,
                        'total' => $order->total,
                        'status' => $order->status,
                        'created_at' => $order->created_at->toIso8601String()
                    ];
                }
            });
        };

        return LaravelApiResponse::streamResponse(
            dataGenerator: $dataGenerator,
            message: 'Exporting orders'
        );
    }
}

// Response output (streamed line by line):
// {"success":true,"message":"Exporting orders","api_version":"1.0"}
// {"order_id":1,"customer":"John Doe","total":150.00,"status":"completed","created_at":"2024-01-01T10:00:00+00:00"}
// {"order_id":2,"customer":"Jane Doe","total":200.00,"status":"pending","created_at":"2024-01-02T11:30:00+00:00"}
// ...
```

--------------------------------

### Generate Validation Error Response (PHP)

Source: https://context7.com/creativecrafts/laravel-api-response/llms.txt

Generates a specific API response for validation errors. It takes an array of errors, typically from a Laravel Validator instance, and a message. This response format is standard for 422 Unprocessable Entity errors.

```php
<?php

use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;

class UserController extends Controller
{
    public function store(Request $request)
    {
        $validator = Validator::make($request->all(), [
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users',
            'password' => 'required|min:8|confirmed',
        ]);

        if ($validator->fails()) {
            return LaravelApiResponse::validationErrorResponse(
                errors: $validator->errors()->toArray(),
                message: 'The given data was invalid'
            );
        }

        // Continue with user creation...
    }
}

// Response output (422 Unprocessable Entity):
// {
//     "success": false,
//     "message": "The given data was invalid",
//     "errors": {
//         "email": ["The email has already been taken."],
//         "password": ["The password confirmation does not match."]
//     },
//     "error_code": 422,
//     "api_version": "1.0"
// }
```

--------------------------------

### Filter Response Fields (PHP)

Source: https://github.com/creativecrafts/laravel-api-response/blob/main/README.md

Limit the fields returned in an API response. This is useful for controlling the amount of data sent to the client. Specify an array of field names to include.

```php
$fields = ['id', 'name', 'email'];
return $this->api->successResponse('User data', $userData, 200, [], [], $fields);
```
Tokens:
Raw