README

它支持 Laravel 9+ 和 PHP 8.2+

• Laravel API 工具包
  • 描述
  • 安装
  • 发布配置文件
  • 用法
    • 响应
      • API 成功 JSON 响应格式。
      • API 分页 JSON 响应格式。
      • API 错误 JSON 响应格式。
      • 仅包含 API 消息的 JSON 响应格式
    • 枚举
    • 头部
    • 中间件类
    • 异常

描述

此包包含许多帮助创建 API 的实用 API。

安装

使用以下命令通过 composer 安装此包

composer require thuraaung2493/laravel-api-utils

发布配置文件

php artisan vendor:publish --provider="Thuraaung\APIUtils\LaravelAPIUtilsServiceProvider" --tag="api-utils"

用法

响应

所有 API 响应类都实现了 Responsable 接口。

  use Thuraaung\APIUtils\Http\Responses\API\SuccessResponse;
  use Thuraaung\APIUtils\Http\Responses\API\PaginatedResponse;
  use Thuraaung\APIUtils\Http\Responses\API\FailResponse;
  use Thuraaung\APIUtils\Http\Responses\API\MessageOnlyResponse;
  use Thuraaung\APIUtils\Http\Responses\API\Response;

  // API Success Response with resource data.
  return new SuccessResponse($userResource); // OR
  return Response::of()->sendSuccess($userResource);

  // API Success Response with resource data.
  return new PaginatedResponse($userPaginationResource); // OR
  return Response::of()->paginated($userPaginationResource);

  // API Fail Response with errors.
  return new FailResponse(errors: ['email' => 'Email is invalid.']); // OR
  return Response::of()->sendFail(['email' => 'Email is invalid.']);

  // API Message-Only Response.
  return new MessageOnlyResponse('Login successful.', Status::OK); // OR
  return Response::of()
    ->status(Status::OK)
    ->sendMessage('Login successful.')

API 成功 JSON 响应格式。

{
    "data": "resource",
    "message": "Success.",
    "status": 200
}

API 分页 JSON 响应格式。

{
    "data": "resource",
    "links": {},
    "meta": {},
    "message": "Success.",
    "status": 200
}

API 错误 JSON 响应格式。

{
    "title": "Failed!",
    "message": "Something went wrong!",
    "errors": [],
    "status": 500
}

仅包含 API 消息的 JSON 响应格式

{
    "message": "Success",
    "status": 500
}

枚举

头部

    use Thuraaung\APIUtils\Http\Headers\Headers;
    use Thuraaung\APIUtils\Http\Headers\ContentType;
    use Thuraaung\APIUtils\Http\Headers\ContentEncoding;

    // Create headers with pre defined in config.
    Headers::default();
    // Transform array
    Headers::default()->toArray();

    // Other utils methods
    Headers::of()
        ->accept(ContentType::JSON)
        ->contentType(ContentType::JSON)
        ->acceptEncoding(ContentEncoding::GZIP)
        ->contentEncoding(ContentEncoding::GZIP, vapor: false)
        ->contentLength(214)
        ->toArray();

中间件类

异常

App\Exceptions\Handler.php

    use Thuraaung\APIUtils\Exceptions\APIExceptionsHandler;

    class Handler extends APIExceptionsHandler
    {
        // others

        public function register(): void
        {
            $this->handleAuthenticationException()
                ->handleAccessDeniedException()
                ->handleNotFoundException()
                ->handleMethodNotAllowException()
                ->handleNotAcceptableException()
                ->handleUnprocessableEntityException()
                ->handleTooManyRequestsException()
                ->handleMergeExceptions([]);
        }

        protected function isJsonRequest(): bool
        {
            return \request()->isJson() && \request()->is('api/*');
        }
    }