guanguans/laravel-api-response

Normalize and standardize Laravel API response data structures. - 规范化和标准化 Laravel API 响应数据结构。

1.0.9 2024-11-12 08:14 UTC

Requires

• php: >=7.4
• ext-json: *
• laravel/framework: ^8.83 || ^9.0 || ^10.0 || ^11.0
• spatie/laravel-package-tools: ^1.12

Requires (Dev)

• brainmaestro/composer-git-hooks: ^2.8 || ^3.0
• driftingly/rector-laravel: ^1.2
• ergebnis/composer-normalize: ^2.44
• ergebnis/license: ^2.5
• ergebnis/php-cs-fixer-config: dev-main
• ergebnis/rector-rules: ^1.1
• guanguans/ai-commit: dev-main
• guanguans/monorepo-builder-worker: ^1.4
• hyperf/composer-plugin: ^1.0
• icanhazstring/composer-unused: ^0.8
• laravel-lang/http-statuses: ^3.2
• maglnet/composer-require-checker: ^3.8 || ^4.0
• mockery/mockery: ^1.6
• orchestra/testbench: ^6.47 || ^7.0 || ^8.0 || ^9.0
• pestphp/pest: ^1.23 || ^2.0 || ^3.0
• pestphp/pest-plugin-faker: ^1.0 || ^2.0 || ^3.0
• pestphp/pest-plugin-laravel: ^1.2 || ^2.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^1.12 || ^2.0
• phpstan/phpstan-deprecation-rules: ^1.2 || ^2.0
• povils/phpmnd: ^3.5
• rector/rector: ^1.2
• spatie/pest-plugin-snapshots: ^1.1 || ^2.0
• spaze/phpstan-disallowed-calls: ^3.5 || ^4.0

Suggests

• laravel-lang/http-statuses: Provide localized message for HTTP status code.

MIT

• guanguans

• json
• rest
• data
• api
• restful
• response
• laravel
• structure
• normalize
• standardize

README

Normalize and standardize Laravel API response data structures. - 规范化和标准化 Laravel API 响应数据结构。

Features

• Support for customized response data structure
• Support for restful API response(optional)
• Support for automatically handled api exception
• Support for localized message
• Support for customized pipe(Process api response structure through pipeline)
• Support for customized exception pipe(Convert exception to api response through pipeline)

Requirement

• PHP >= 7.4

Installation

composer require guanguans/laravel-api-response --ansi -v

Configuration

Publish files(optional)

php artisan vendor:publish --provider="Guanguans\\LaravelApiResponse\\ServiceProvider" --ansi -v

Usage

Quick start

details

<?php

namespace App\Http\Controllers\Api;

use Guanguans\LaravelApiResponse\Support\Traits\ApiResponseFactory;
use Illuminate\Http\JsonResponse;
use Symfony\Component\HttpKernel\Exception\HttpException;

class Controller extends \App\Http\Controllers\Controller
{
    use ApiResponseFactory;

    /**
     * Default response structure
     *
     * ```json
     * {
     *     "status": "boolean",
     *     "code": "integer",
     *     "message": "string",
     *     "data": "mixed",
     *     "error": "array<string, mixed>
     * }
     * ```
     */
    public function examples(): JsonResponse
    {
        // return $this->apiResponse()->error($message);
        // return $this->apiResponse()->badRequest($message);
        // return $this->apiResponse()->unauthorized($message);
        // return $this->apiResponse()->exception($exception);
        // throw new \RuntimeException('This is a runtime exception.');
        // throw new HttpException(400);
        // return $this->apiResponse()->success($data);
        // return $this->apiResponse()->noContent($message);
        // ...
        return $this->apiResponse()->ok();
    }
}

Default response structure

details

{
    "status": "boolean",
    "code": "integer",
    "message": "string",
    "data": "mixed",
    "error": "array<string, mixed>"
}

Default response examples

model

<?php

namespace App\Http\Controllers\Api;

use Guanguans\LaravelApiResponse\Support\Traits\ApiResponseFactory;
use Guanguans\LaravelApiResponse\Tests\Laravel\Models\User;
use Illuminate\Http\JsonResponse;

class Controller extends \App\Http\Controllers\Controller
{
    use ApiResponseFactory;

    public function example(): JsonResponse
    {
        $user = User::query()->with(['country', 'posts'])->first();

        return $this->apiResponse()->success($user);
    }
}

{
    "status": true,
    "code": 200,
    "message": "OK",
    "data": {
        "id": 1,
        "name": "John",
        "country_id": 1,
        "created_at": "2024-01-01 00:00:01",
        "updated_at": "2024-01-01 00:00:01",
        "country": {
            "id": 1,
            "name": "China",
            "created_at": "2024-01-01 00:00:01",
            "updated_at": "2024-01-01 00:00:01"
        },
        "posts": [
            {
                "id": 1,
                "title": "PHP is the best language!",
                "user_id": 1,
                "created_at": "2024-01-01 00:00:01",
                "updated_at": "2024-01-01 00:00:01"
            },
            {
                "id": 2,
                "title": "JAVA is the best language!",
                "user_id": 1,
                "created_at": "2024-01-01 00:00:02",
                "updated_at": "2024-01-01 00:00:02"
            },
            {
                "id": 3,
                "title": "Python is the best language!",
                "user_id": 1,
                "created_at": "2024-01-01 00:00:03",
                "updated_at": "2024-01-01 00:00:03"
            }
        ]
    },
    "error": {}
}

eloquent collection

<?php

namespace App\Http\Controllers\Api;

use Guanguans\LaravelApiResponse\Support\Traits\ApiResponseFactory;
use Guanguans\LaravelApiResponse\Tests\Laravel\Models\User;
use Illuminate\Http\JsonResponse;

class Controller extends \App\Http\Controllers\Controller
{
    use ApiResponseFactory;

    public function example(): JsonResponse
    {
        $users = User::query()->with(['country', 'posts'])->get();

        return $this->apiResponse()->success($users);
    }
}

{
    "status": true,
    "code": 200,
    "message": "OK",
    "data": [
        {
            "id": 1,
            "name": "John",
            "country_id": 1,
            "created_at": "2024-01-01 00:00:01",
            "updated_at": "2024-01-01 00:00:01",
            "country": {
                "id": 1,
                "name": "China",
                "created_at": "2024-01-01 00:00:01",
                "updated_at": "2024-01-01 00:00:01"
            },
            "posts": [
                {
                    "id": 1,
                    "title": "PHP is the best language!",
                    "user_id": 1,
                    "created_at": "2024-01-01 00:00:01",
                    "updated_at": "2024-01-01 00:00:01"
                },
                {
                    "id": 2,
                    "title": "JAVA is the best language!",
                    "user_id": 1,
                    "created_at": "2024-01-01 00:00:02",
                    "updated_at": "2024-01-01 00:00:02"
                },
                {
                    "id": 3,
                    "title": "Python is the best language!",
                    "user_id": 1,
                    "created_at": "2024-01-01 00:00:03",
                    "updated_at": "2024-01-01 00:00:03"
                }
            ]
        },
        {
            "id": 2,
            "name": "Tom",
            "country_id": 2,
            "created_at": "2024-01-01 00:00:02",
            "updated_at": "2024-01-01 00:00:02",
            "country": {
                "id": 2,
                "name": "USA",
                "created_at": "2024-01-01 00:00:02",
                "updated_at": "2024-01-01 00:00:02"
            },
            "posts": [
                {
                    "id": 4,
                    "title": "Go is the best language!",
                    "user_id": 2,
                    "created_at": "2024-01-01 00:00:04",
                    "updated_at": "2024-01-01 00:00:04"
                },
                {
                    "id": 5,
                    "title": "JavaScript is the best language!",
                    "user_id": 2,
                    "created_at": "2024-01-01 00:00:05",
                    "updated_at": "2024-01-01 00:00:05"
                },
                {
                    "id": 6,
                    "title": "Ruby is the best language!",
                    "user_id": 2,
                    "created_at": "2024-01-01 00:00:06",
                    "updated_at": "2024-01-01 00:00:06"
                }
            ]
        },
        {
            "id": 3,
            "name": "Jerry",
            "country_id": 3,
            "created_at": "2024-01-01 00:00:03",
            "updated_at": "2024-01-01 00:00:03",
            "country": {
                "id": 3,
                "name": "Japan",
                "created_at": "2024-01-01 00:00:03",
                "updated_at": "2024-01-01 00:00:03"
            },
            "posts": [
                {
                    "id": 7,
                    "title": "C is the best language!",
                    "user_id": 3,
                    "created_at": "2024-01-01 00:00:07",
                    "updated_at": "2024-01-01 00:00:07"
                }
            ]
        },
        {
            "id": 4,
            "name": "Jack",
            "country_id": 4,
            "created_at": "2024-01-01 00:00:04",
            "updated_at": "2024-01-01 00:00:04",
            "country": {
                "id": 4,
                "name": "Korea",
                "created_at": "2024-01-01 00:00:04",
                "updated_at": "2024-01-01 00:00:04"
            },
            "posts": []
        },
        {
            "id": 5,
            "name": "Rose",
            "country_id": 5,
            "created_at": "2024-01-01 00:00:05",
            "updated_at": "2024-01-01 00:00:05",
            "country": {
                "id": 5,
                "name": "UK",
                "created_at": "2024-01-01 00:00:05",
                "updated_at": "2024-01-01 00:00:05"
            },
            "posts": []
        },
        {
            "id": 6,
            "name": "Lucy",
            "country_id": 6,
            "created_at": "2024-01-01 00:00:06",
            "updated_at": "2024-01-01 00:00:06",
            "country": {
                "id": 6,
                "name": "France",
                "created_at": "2024-01-01 00:00:06",
                "updated_at": "2024-01-01 00:00:06"
            },
            "posts": []
        },
        {
            "id": 7,
            "name": "Lily",
            "country_id": 7,
            "created_at": "2024-01-01 00:00:07",
            "updated_at": "2024-01-01 00:00:07",
            "country": {
                "id": 7,
                "name": "Germany",
                "created_at": "2024-01-01 00:00:07",
                "updated_at": "2024-01-01 00:00:07"
            },
            "posts": []
        }
    ],
    "error": {}
}

simple paginate

<?php

namespace App\Http\Controllers\Api;

use Guanguans\LaravelApiResponse\Support\Traits\ApiResponseFactory;
use Guanguans\LaravelApiResponse\Tests\Laravel\Models\User;
use Illuminate\Http\JsonResponse;

class Controller extends \App\Http\Controllers\Controller
{
    use ApiResponseFactory;

    public function example(): JsonResponse
    {
        $simplePaginate = User::query()->with(['country', 'posts'])->simplePaginate(3);

        return $this->apiResponse()->success($simplePaginate);
    }
}

{
    "status": true,
    "code": 200,
    "message": "OK",
    "data": {
        "data": [
            {
                "id": 1,
                "name": "John",
                "country_id": 1,
                "created_at": "2024-01-01 00:00:01",
                "updated_at": "2024-01-01 00:00:01",
                "country": {
                    "id": 1,
                    "name": "China",
                    "created_at": "2024-01-01 00:00:01",
                    "updated_at": "2024-01-01 00:00:01"
                },
                "posts": [
                    {
                        "id": 1,
                        "title": "PHP is the best language!",
                        "user_id": 1,
                        "created_at": "2024-01-01 00:00:01",
                        "updated_at": "2024-01-01 00:00:01"
                    },
                    {
                        "id": 2,
                        "title": "JAVA is the best language!",
                        "user_id": 1,
                        "created_at": "2024-01-01 00:00:02",
                        "updated_at": "2024-01-01 00:00:02"
                    },
                    {
                        "id": 3,
                        "title": "Python is the best language!",
                        "user_id": 1,
                        "created_at": "2024-01-01 00:00:03",
                        "updated_at": "2024-01-01 00:00:03"
                    }
                ]
            },
            {
                "id": 2,
                "name": "Tom",
                "country_id": 2,
                "created_at": "2024-01-01 00:00:02",
                "updated_at": "2024-01-01 00:00:02",
                "country": {
                    "id": 2,
                    "name": "USA",
                    "created_at": "2024-01-01 00:00:02",
                    "updated_at": "2024-01-01 00:00:02"
                },
                "posts": [
                    {
                        "id": 4,
                        "title": "Go is the best language!",
                        "user_id": 2,
                        "created_at": "2024-01-01 00:00:04",
                        "updated_at": "2024-01-01 00:00:04"
                    },
                    {
                        "id": 5,
                        "title": "JavaScript is the best language!",
                        "user_id": 2,
                        "created_at": "2024-01-01 00:00:05",
                        "updated_at": "2024-01-01 00:00:05"
                    },
                    {
                        "id": 6,
                        "title": "Ruby is the best language!",
                        "user_id": 2,
                        "created_at": "2024-01-01 00:00:06",
                        "updated_at": "2024-01-01 00:00:06"
                    }
                ]
            },
            {
                "id": 3,
                "name": "Jerry",
                "country_id": 3,
                "created_at": "2024-01-01 00:00:03",
                "updated_at": "2024-01-01 00:00:03",
                "country": {
                    "id": 3,
                    "name": "Japan",
                    "created_at": "2024-01-01 00:00:03",
                    "updated_at": "2024-01-01 00:00:03"
                },
                "posts": [
                    {
                        "id": 7,
                        "title": "C is the best language!",
                        "user_id": 3,
                        "created_at": "2024-01-01 00:00:07",
                        "updated_at": "2024-01-01 00:00:07"
                    }
                ]
            }
        ],
        "links": {
            "first": "http:\/\/localhost?page=1",
            "last": null,
            "prev": null,
            "next": "http:\/\/localhost?page=2"
        },
        "meta": {
            "current_page": 1,
            "from": 1,
            "path": "http:\/\/localhost",
            "per_page": 3,
            "to": 3
        }
    },
    "error": {}
}

resource

<?php

namespace App\Http\Controllers\Api;

use Guanguans\LaravelApiResponse\Support\Traits\ApiResponseFactory;
use Guanguans\LaravelApiResponse\Tests\Laravel\Models\User;
use Guanguans\LaravelApiResponse\Tests\Laravel\Resources\UserResource;
use Illuminate\Http\JsonResponse;

class Controller extends \App\Http\Controllers\Controller
{
    use ApiResponseFactory;

    public function example(): JsonResponse
    {
        $userResource = UserResource::make(User::query()->with(['country', 'posts'])->first());

        return $this->apiResponse()->success($userResource);
    }
}

{
    "status": true,
    "code": 200,
    "message": "OK",
    "data": {
        "id": 1,
        "name": "John",
        "country_id": 1,
        "created_at": "2024-01-01 00:00:01",
        "updated_at": "2024-01-01 00:00:01",
        "country": {
            "id": 1,
            "name": "China",
            "created_at": "2024-01-01 00:00:01",
            "updated_at": "2024-01-01 00:00:01"
        },
        "posts": [
            {
                "id": 1,
                "title": "PHP is the best language!",
                "user_id": 1,
                "created_at": "2024-01-01 00:00:01",
                "updated_at": "2024-01-01 00:00:01"
            },
            {
                "id": 2,
                "title": "JAVA is the best language!",
                "user_id": 1,
                "created_at": "2024-01-01 00:00:02",
                "updated_at": "2024-01-01 00:00:02"
            },
            {
                "id": 3,
                "title": "Python is the best language!",
                "user_id": 1,
                "created_at": "2024-01-01 00:00:03",
                "updated_at": "2024-01-01 00:00:03"
            }
        ]
    },
    "error": {}
}

resource collection

<?php

namespace App\Http\Controllers\Api;

use Guanguans\LaravelApiResponse\Support\Traits\ApiResponseFactory;
use Guanguans\LaravelApiResponse\Tests\Laravel\Models\User;
use Guanguans\LaravelApiResponse\Tests\Laravel\Resources\UserCollection;
use Illuminate\Http\JsonResponse;

class Controller extends \App\Http\Controllers\Controller
{
    use ApiResponseFactory;

    public function example(): JsonResponse
    {
        $userCollection = UserCollection::make(User::query()->with(['country', 'posts'])->get());

        return $this->apiResponse()->success($userCollection);
    }
}

{
    "status": true,
    "code": 200,
    "message": "OK",
    "data": [
        {
            "id": 1,
            "name": "John",
            "country_id": 1,
            "created_at": "2024-01-01 00:00:01",
            "updated_at": "2024-01-01 00:00:01",
            "country": {
                "id": 1,
                "name": "China",
                "created_at": "2024-01-01 00:00:01",
                "updated_at": "2024-01-01 00:00:01"
            },
            "posts": [
                {
                    "id": 1,
                    "title": "PHP is the best language!",
                    "user_id": 1,
                    "created_at": "2024-01-01 00:00:01",
                    "updated_at": "2024-01-01 00:00:01"
                },
                {
                    "id": 2,
                    "title": "JAVA is the best language!",
                    "user_id": 1,
                    "created_at": "2024-01-01 00:00:02",
                    "updated_at": "2024-01-01 00:00:02"
                },
                {
                    "id": 3,
                    "title": "Python is the best language!",
                    "user_id": 1,
                    "created_at": "2024-01-01 00:00:03",
                    "updated_at": "2024-01-01 00:00:03"
                }
            ]
        },
        {
            "id": 2,
            "name": "Tom",
            "country_id": 2,
            "created_at": "2024-01-01 00:00:02",
            "updated_at": "2024-01-01 00:00:02",
            "country": {
                "id": 2,
                "name": "USA",
                "created_at": "2024-01-01 00:00:02",
                "updated_at": "2024-01-01 00:00:02"
            },
            "posts": [
                {
                    "id": 4,
                    "title": "Go is the best language!",
                    "user_id": 2,
                    "created_at": "2024-01-01 00:00:04",
                    "updated_at": "2024-01-01 00:00:04"
                },
                {
                    "id": 5,
                    "title": "JavaScript is the best language!",
                    "user_id": 2,
                    "created_at": "2024-01-01 00:00:05",
                    "updated_at": "2024-01-01 00:00:05"
                },
                {
                    "id": 6,
                    "title": "Ruby is the best language!",
                    "user_id": 2,
                    "created_at": "2024-01-01 00:00:06",
                    "updated_at": "2024-01-01 00:00:06"
                }
            ]
        },
        {
            "id": 3,
            "name": "Jerry",
            "country_id": 3,
            "created_at": "2024-01-01 00:00:03",
            "updated_at": "2024-01-01 00:00:03",
            "country": {
                "id": 3,
                "name": "Japan",
                "created_at": "2024-01-01 00:00:03",
                "updated_at": "2024-01-01 00:00:03"
            },
            "posts": [
                {
                    "id": 7,
                    "title": "C is the best language!",
                    "user_id": 3,
                    "created_at": "2024-01-01 00:00:07",
                    "updated_at": "2024-01-01 00:00:07"
                }
            ]
        },
        {
            "id": 4,
            "name": "Jack",
            "country_id": 4,
            "created_at": "2024-01-01 00:00:04",
            "updated_at": "2024-01-01 00:00:04",
            "country": {
                "id": 4,
                "name": "Korea",
                "created_at": "2024-01-01 00:00:04",
                "updated_at": "2024-01-01 00:00:04"
            },
            "posts": []
        },
        {
            "id": 5,
            "name": "Rose",
            "country_id": 5,
            "created_at": "2024-01-01 00:00:05",
            "updated_at": "2024-01-01 00:00:05",
            "country": {
                "id": 5,
                "name": "UK",
                "created_at": "2024-01-01 00:00:05",
                "updated_at": "2024-01-01 00:00:05"
            },
            "posts": []
        },
        {
            "id": 6,
            "name": "Lucy",
            "country_id": 6,
            "created_at": "2024-01-01 00:00:06",
            "updated_at": "2024-01-01 00:00:06",
            "country": {
                "id": 6,
                "name": "France",
                "created_at": "2024-01-01 00:00:06",
                "updated_at": "2024-01-01 00:00:06"
            },
            "posts": []
        },
        {
            "id": 7,
            "name": "Lily",
            "country_id": 7,
            "created_at": "2024-01-01 00:00:07",
            "updated_at": "2024-01-01 00:00:07",
            "country": {
                "id": 7,
                "name": "Germany",
                "created_at": "2024-01-01 00:00:07",
                "updated_at": "2024-01-01 00:00:07"
            },
            "posts": []
        }
    ],
    "error": {}
}

error

<?php

namespace App\Http\Controllers\Api;

use Guanguans\LaravelApiResponse\Support\Traits\ApiResponseFactory;
use Illuminate\Http\JsonResponse;

class Controller extends \App\Http\Controllers\Controller
{
    use ApiResponseFactory;

    public function example(): JsonResponse
    {
        return $this->apiResponse()->error('This is an error.');
    }
}

{
    "status": false,
    "code": 400,
    "message": "This is an error.",
    "data": null,
    "error": {}
}

exception

<?php

namespace App\Http\Controllers\Api;

use Guanguans\LaravelApiResponse\Support\Traits\ApiResponseFactory;
use Illuminate\Http\JsonResponse;

class Controller extends \App\Http\Controllers\Controller
{
    use ApiResponseFactory;

    public function example(): JsonResponse
    {
        config()->set('app.debug', false);
        $runtimeException = new \RuntimeException('This is a runtime exception.');

        return $this->apiResponse()->exception($runtimeException);
    }
}

{
    "status": false,
    "code": 500,
    "message": "Internal Server Error",
    "data": null,
    "error": {
        "message": "Internal Server Error"
    }
}

debug exception

<?php

namespace App\Http\Controllers\Api;

use Guanguans\LaravelApiResponse\Support\Traits\ApiResponseFactory;
use Illuminate\Http\JsonResponse;

class Controller extends \App\Http\Controllers\Controller
{
    use ApiResponseFactory;

    public function example(): JsonResponse
    {
        config()->set('app.debug', true);
        $runtimeException = new \RuntimeException('This is a runtime exception.');

        return $this->apiResponse()->exception($runtimeException);
    }
}

{
    "status": false,
    "code": 500,
    "message": "This is a runtime exception.",
    "data": null,
    "error": {
        "message": "This is a runtime exception.",
        "exception": "RuntimeException",
        "file": "\/tests\/Feature\/ExceptionDataTypesTest.php",
        "line": 45,
        "trace": [
            {
                "function": "{closure}",
                "class": "P\\Tests\\Feature\\ExceptionDataTypesTest",
                "type": "->"
            },
            {
                "file": "\/vendor\/pestphp\/pest\/src\/Factories\/TestCaseFactory.php",
                "line": 151,
                "function": "call_user_func"
            },
            {
                "function": "Pest\\Factories\\{closure}",
                "class": "P\\Tests\\Feature\\ExceptionDataTypesTest",
                "type": "->"
            },
            {
                "file": "\/vendor\/pestphp\/pest\/src\/Concerns\/Testable.php",
                "line": 301,
                "function": "call_user_func_array"
            },
            {
                "file": "\/vendor\/pestphp\/pest\/src\/Support\/ExceptionTrace.php",
                "line": 29,
                "function": "Pest\\Concerns\\{closure}",
                "class": "P\\Tests\\Feature\\ExceptionDataTypesTest",
                "type": "->"
            },
            {
                "file": "\/vendor\/pestphp\/pest\/src\/Concerns\/Testable.php",
                "line": 302,
                "function": "ensure",
                "class": "Pest\\Support\\ExceptionTrace",
                "type": "::"
            },
            {
                "file": "\/vendor\/pestphp\/pest\/src\/Concerns\/Testable.php",
                "line": 278,
                "function": "__callClosure",
                "class": "P\\Tests\\Feature\\ExceptionDataTypesTest",
                "type": "->"
            },
            {
                "file": "\/vendor\/phpunit\/phpunit\/src\/Framework\/TestCase.php",
                "line": 1617,
                "function": "__test",
                "class": "P\\Tests\\Feature\\ExceptionDataTypesTest",
                "type": "->"
            },
            {
                "file": "\/vendor\/phpunit\/phpunit\/src\/Framework\/TestCase.php",
                "line": 1223,
                "function": "runTest",
                "class": "PHPUnit\\Framework\\TestCase",
                "type": "->"
            },
            {
                "file": "\/vendor\/phpunit\/phpunit\/src\/Framework\/TestResult.php",
                "line": 729,
                "function": "runBare",
                "class": "PHPUnit\\Framework\\TestCase",
                "type": "->"
            },
            {
                "file": "\/vendor\/phpunit\/phpunit\/src\/Framework\/TestCase.php",
                "line": 973,
                "function": "run",
                "class": "PHPUnit\\Framework\\TestResult",
                "type": "->"
            },
            {
                "file": "\/vendor\/phpunit\/phpunit\/src\/Framework\/TestSuite.php",
                "line": 685,
                "function": "run",
                "class": "PHPUnit\\Framework\\TestCase",
                "type": "->"
            },
            {
                "file": "\/vendor\/phpunit\/phpunit\/src\/Framework\/TestSuite.php",
                "line": 685,
                "function": "run",
                "class": "PHPUnit\\Framework\\TestSuite",
                "type": "->"
            },
            {
                "file": "\/vendor\/phpunit\/phpunit\/src\/TextUI\/TestRunner.php",
                "line": 651,
                "function": "run",
                "class": "PHPUnit\\Framework\\TestSuite",
                "type": "->"
            },
            {
                "file": "\/vendor\/phpunit\/phpunit\/src\/TextUI\/Command.php",
                "line": 146,
                "function": "run",
                "class": "PHPUnit\\TextUI\\TestRunner",
                "type": "->"
            },
            {
                "file": "\/vendor\/pestphp\/pest\/src\/Console\/Command.php",
                "line": 119,
                "function": "run",
                "class": "PHPUnit\\TextUI\\Command",
                "type": "->"
            },
            {
                "file": "\/vendor\/pestphp\/pest\/bin\/pest",
                "line": 61,
                "function": "run",
                "class": "Pest\\Console\\Command",
                "type": "->"
            },
            {
                "file": "\/vendor\/pestphp\/pest\/bin\/pest",
                "line": 62,
                "function": "{closure}"
            },
            {
                "file": "\/vendor\/bin\/pest",
                "line": 115,
                "function": "include"
            }
        ]
    }
}

exception handler

<?php

namespace App\Http\Controllers\Api;

use Guanguans\LaravelApiResponse\Middleware\SetJsonAcceptHeader;
use Illuminate\Http\JsonResponse;

class Controller extends \App\Http\Controllers\Controller
{
    public function __construct()
    {
        $this->middleware(SetJsonAcceptHeader::class)->only('example');
    }

    public function example(): JsonResponse
    {
        config()->set('app.debug', false);

        throw new \RuntimeException('This is a runtime exception.');
    }
}

{
    "status": false,
    "code": 500,
    "message": "Internal Server Error",
    "data": null,
    "error": {
        "message": "Internal Server Error"
    }
}

locale exception

<?php

namespace App\Http\Controllers\Api;

use Guanguans\LaravelApiResponse\Support\Traits\ApiResponseFactory;
use Illuminate\Http\JsonResponse;

class Controller extends \App\Http\Controllers\Controller
{
    use ApiResponseFactory;

    public function example(): JsonResponse
    {
        config()->set('app.debug', false);
        config()->set('app.locale', 'zh_CN');
        $runtimeException = new \RuntimeException('This is a runtime exception.');

        return $this->apiResponse()->exception($runtimeException);
    }
}

resources/lang/zh_CN.json

{
    "...": "...",
    "Unauthenticated.": "未认证。",
    "This is a runtime exception.": "这是一个运行时异常。"
}

{
    "status": false,
    "code": 500,
    "message": "这是一个运行时异常。",
    "data": null,
    "error": {
        "message": "这是一个运行时异常。"
    }
}

more examples...

• feature
• snapshots

FAQ

How to get [\Guanguans\LaravelApiResponse\ApiResponse] instance

<?php

namespace App\Http\Controllers\Api;

use Guanguans\LaravelApiResponse\Contracts\ApiResponseContract;
use Guanguans\LaravelApiResponse\Facades\ApiResponseFacade;
use Guanguans\LaravelApiResponse\Support\Traits\ApiResponseFactory;
use Illuminate\Http\JsonResponse;

class Controller extends \App\Http\Controllers\Controller
{
    use ApiResponseFactory;

    public function getInstance(): JsonResponse
    {
        /** @var \Guanguans\LaravelApiResponse\ApiResponse $apiResponse */
        // $apiResponse = ApiResponseFacade::getFacadeRoot();
        // $apiResponse = resolve(ApiResponseContract::class);
        // $apiResponse = app(ApiResponseContract::class);
        $apiResponse = $this->apiResponse();

        return $apiResponse->ok();
    }
}

How to specify api paths to automatically handle exception

• Reference to the ApiPathsRenderUsing.php
• Update the configuration api-response.render_using

How to always respond with successful http status code

• Reference to the StatusCodePipe.php
• Remove the configuration api-response.pipes.StatusCodePipe

How to localize message

• Reference to the MessagePipe.php
• Add localize status code message [install Laravel-Lang/http-statuses composer require --dev laravel-lang/http-statuses or create lang files resources/lang/***/http-statuses.php]
• Add localize message [create lang json files resources/lang/***.json]

How to customize pipe

• Reference to the Pipes
• Simple example:

<?php

static function (array $structure, \Closure $next): JsonResponse {
    if ($structure['data'] instanceof \Traversable) {
        $structure['data'] = iterator_to_array($structure['data']);
    }

    return $next($structure);
};

How to customize exception pipe

• Reference to the ExceptionPipes

How to operate pipe dynamically in a single api

• Reference to the HasPipes.php、HasExceptionPipes.php
• Simple example:

<?php

namespace App\Http\Controllers\Api;

use Guanguans\LaravelApiResponse\Support\Traits\ApiResponseFactory;
use Illuminate\Http\JsonResponse;

class Controller extends \App\Http\Controllers\Controller
{
    use ApiResponseFactory;

    public function example(): JsonResponse
    {
        return $this
            ->apiResponse()
            // ->unshiftPipes(...$pipes)
            // ->pushPipes(...$pipes)
            // ->beforePipes($findPipe, ...$pipes)
            // ->afterPipes($findPipe, ...$pipes)
            // ->removePipes(...$findPipes)
            // ->extendPipes($callback)
            // ->tapPipes($callback)
            ->success($data);
    }
}

Shortcut methods of http status

• Reference to the ConcreteHttpStatus.php

All methods

• Reference to the ApiResponseFacade.php

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• guanguans
• All Contributors

Thanks

License

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