lordsling/api-response

dev-main 2021-11-07 22:08 UTC

MIT

• Lordsling

• php
• json
• api
• restful
• response
• laravel
• RESTful API

README

A collection of helpers for returning a response from your API more expressively

Installation

Install this package via Composer:

$ composer require lordsling/api-response

No extra setup is required. The helper file is autoloaded via the "autoload" attributes of the composer.json file

Configuration

Publish config file using Artisan command:

$ php artisan vendor:publish --provider="Lordsling\ApiResponse\ApiResponseServiceProvider"

Check config/api-response.php and read comments there if you need.

Sample Response API

{
    "success": true,
    "payload": null,
    "errors": []
}

Usage

2xx Success "success": true

HTTP 200 OK

/**
 * @param null $payload
 */
return ok($payload);

HTTP 200 OK

/**
 * @param null $payload
 */
return error($payload);

HTTP 200 OK

/**
 * @param null $payload
 */
return fail($payload);

HTTP 201 Created

/**
 * @param null $payload
 */
return created($payload);

HTTP 202 Accepted

/**
 * @param null $payload
 */
return accepted($payload);

HTTP 204 No Content

/**
 */
return noContent();

3xx Redirection

HTTP 301 Moved Permanently

/**
 * @param $newUrl
 */
return movedPermanently($newUrl);

HTTP 302 Found

/**
 * @param $url
 */
return found($url);

HTTP 303 See Other

/**
 * @param $newUrl
 */
return seeOther($newUrl);

HTTP 307 Temporary Redirect

/**
 * @param $tempUrl
 */
return temporaryRedirect($tempUrl);

4xx Client Errors "success": false

HTTP 400 Bad Request

/**
 * @param null $payload
 */
return badRequest($payload);

HTTP 401 Unauthorized

/**
 * @param null $payload
 */
return unauthorized($payload);

HTTP 402 Payment Required

/**
 * @param null $payload
 */
return paymentRequired($payload);

HTTP 403 Forbidden

/**
 * @param null $payload
 */
return forbidden($payload);

HTTP 404 Not Found

/**
 * @param null $payload
 */
return notFound($payload);

HTTP 405 Method Not Allowed

/**
 * @param null $payload
 */
return methodNotAllowed($payload);

HTTP 406 Not Acceptable

/**
 * @param null $payload
 */
return notAcceptable($payload);

HTTP 410 Gone

/**
 * @param null $payload
 */
return gone($payload);

HTTP 413 Payload Too Large

/**
 * @param null $payload
 */
return payloadTooLarge($payload);

HTTP 422 Unprocessable Entity

/**
 * @param null $payload
 */
return unprocessableEntity($payload);

HTTP 426 Upgrade Required

/**
 * @param null $payload
 */
return upgradeRequired($payload);

HTTP 429 Too Many Requests

/**
 * @param null $payload
 */
return tooManyRequests($payload);

5xx Server Errors "success": false

HTTP 500 Internal Server Errors

/**
 * @param null $payload
 */
return internalServerError($payload);

HTTP 501 Not Implemented

/**
 * @param null $payload
 */
return notImplemented($payload);

HTTP 502 Bad Gateway

/**
 * @param null $payload
 */
return badGateway($payload);

HTTP 503 Service Unavailable

/**
 * @param null $payload
 */
return serviceUnavailable($payload);

HTTP 504 Gateway Timeout

/**
 * @param null $payload
 */
return gatewayTimeout($payload);

HTTP 507 Insufficient Storage

/**
 * @param null $payload
 */
return insufficientStorage($payload);

Available methods

withHeaders

/**
 * @param array $headers
 */
->withHeaders([
    ['HeaderName' => 'value'],
    //...
]);

withErrors

/**
 * @param array $headers
 */
->withErrors([
    [
        'code' => 'code',
        'message' => 'message'
    ],
    //...
]);

withMeta

/**
 * @param $request
 * @param null $callback
 */
->withMeta($request, function ($request) {
    return ['query' => $request->query()];
});

withValidation

App/Exceptions/Handler.php

public function render($request, Throwable $e)
{
    if ($e instanceof ValidationException) {
        return unprocessableEntity()->withValidation($e);
    }
}

withTrace

App/Exceptions/Handler.php

public function render($request, Throwable $e)
{
    return internalServerError()
    /**
     * @param $exception
     */
    ->withTrace($e);
}

withMergeErrors

/**
 * @param ...$errorCodes
 */
->withMergeErrors(1000, 1001, 1002, /*...*/);
                    or
->withMergeErrors([1000, 1001, 1002, /*...*/]);

addError

/**
 * @param $code
 * @param string|null $message
 * @param array|null $details
 */
->addError(1000, 'Custom error message', ['details' => '...', //...]);

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

License

The MIT License (MIT). Please see License File for more information.