README

这是用于开发非常简单且高效的 RESTful API 的 Laravel 5.* 包。它提供了使用 Laravel 内置验证器进行验证的功能，并具有扩展的可能性和一些有用的模型方法。它是完全可定制的。它真的很神奇，因为您可以定义部分响应并显著减少响应数据。所有其他功能，如排序、搜索、过滤，也都提供。

先决条件

PHP 版本 >= 5.5
Laravel 框架 5 及以上版本

安装

首先，您需要使用 composer 安装此包

composer require izupet/api

在 app.php 文件中添加服务提供者

Izupet\Api\Providers\ApiServiceProvider::class

Composer 完成工作后，运行以下 artisan 命令以生成配置文件

$ php artisan vendor:publish

在此 api.php 配置文件中，您可以设置默认的 limit、offset 等。

您已经完成了。包已安装并成功设置，准备使用。

用法

要创建新的资源，请使用 Laravel 内置的 artisan 命令

$ php artisan make:controller CarsController

要创建 CarsRequest 验证类，请运行

$ php artisan api:request CarsRequest

这将创建 app/Http/Requests 文件夹中的新文件。在控制器中，您可以使用此 CarsRequest 如下

use App\Http\Requests\CarsRequest;
use Izupet\Api\Traits\ApiResponse;

class CarsController extends Controller
{
    use ApiResponse;
    
    public function index(CarsRequest $request)
    {
        //
        
        return $this->respond('Ok', 200, []);
    }
}

此 $request 变量将已完全配备验证过的用户输入。使用 $request->all() 将返回验证过的和结构化的用户输入，以便进一步处理。如您所见，此控制器也使用了 ApiResponse trait。此 trait 旨在在任何需要返回响应的地方使用（控制器、异常处理器等）。有三个主要方法可供调用

1. respondCollection($data) 用于集合 - 通常与 GET 方法一起使用
2. respondOne($data) 用于单个对象 - 通常与 PUT 或 POST 方法一起使用
3. respond($message, $HTTPStatusCode, $data = null, array $extras = []) - 用于自定义响应的主要响应方法

所有响应都具有元属性，其中始终存在状态、消息和代码属性。状态根据代码自动生成（成功或错误）。如果响应成功，则添加数据属性到响应中，否则跳过。

respondCollection 响应的示例

{
    "meta": {
        "status": "success",
        "message": "Ok.",
        "code": 200,
        "total": 503,
        "limit": 10,
        "offset": 0
    },
    "data": []
}

respondOne 响应的示例

{
    "meta": {
        "status": "success",
        "message": "Ok.",
        "code": 200
    },
    "data": []
}

respond 错误响应的示例

{
    "meta": {
        "status": "error",
        "message": "Custom error message.",
        "code": 400
    }
}

如果查询字符串中存在 suppressResponseHttpStatusCode 参数，则响应将以状态码 200 返回。这在处理特殊应用程序时很有用。响应元属性中的代码保持不变。

此库最强大之处在于我们之前创建的验证请求类（见上文）。每个类都包含四个主要方法

• getRules() - 设置 GET 方法的规则
• postRules() - 设置 POST 方法的规则
• putRules() - 设置 PUT 方法的规则
• deleteRules() - 设置 DELETE 方法的规则

getRules 方法填充所有可用辅助规则的示例

public function getRules()
{
    return $this
        ->search(['model', 'brand'])
        ->pagination()
        ->fields(['id', 'model', 'brand', 'type', 'createdAt', 'images' => [
            'path', 'id', 'position', 'createdAt'
        ]])
        ->order(['model', 'brand', 'id'])
        ->filter([
            'type'                => 'in:coupe,convertable,suv,sedan',
            'images_position'     => 'numeric|min:0|max:4',
            'images_position_nq'  => 'numeric|min:0|max:4',
            'images_path'         => 'max:99',
            'brand'               => 'alpha',
            'images_createdAt_gt' => 'date_format:Y-m-d',
            'createdAt_lt'        => 'date_format:Y-m-d',
            'id'                  => 'numeric'
        ]);
}

因此，已设置 GET 方法的规则，让我们深入了解。

• search - 方法接受字段数组作为参数（可通过搜索的字段）

/cars?q=BMW

• pagination - 允许端点使用 limit 和 offset 参数（默认值在配置中设置）

/cars?limit=20&offset=40

• fields - 可以在响应中返回的字段。使用子数组设置关系字段

/cars?fields=id,model,images.path

• order - 可以按字段排序

/cars?order=id.desc

• filter - 可以过滤的字段。您可以使用内置验证器或自定义扩展。名称中的下划线表示 URL 中的点。后缀（ne = 不等于，gt = 大于，lt = 小于）也是重要功能，可完善此 API。您还可以按关系字段过滤。

/cars?type=sedan&images.createdAt.gt=2017-01-01

验证后，您可以在控制器中访问验证过的请求。让我们看看如果我们运行 dd($request->all())，请求看起来是什么样的

array:6 [▼
  "fields" => array:2 [▶]
  "order" => array:2 [▶]
  "search" => array:2 [▶]
  "pagination" => array:2 [▶]
  "filter" => array:2 [▶]
  "body" => array:1 [▶]
]

所有参数都已良好结构化并准备好在服务/仓库中使用。为此，有一些有用的方法可以与Eloquent一起使用。

使用此方法的仓库示例

class CarRepository
{
    public function __construct(
        \App\Car $car
    )
    {
        $this->car = $car;
    }

    public function all(array $input)
    {
        return $this->car->apiGet('fields', 'pagination', 'search', 'order', 'filter', 'relations', $input);
    }

    public function create(array $input)
    {
        return $this->car->apiCreate('fields', $input);
    }

    public function update(array $input, \App\Car $car)
    {
        return $car->apiUpdate('fields', 'relations', $input);
    }

    public function delete(\App\Car $car)
    {
        return $car->apiDelete();
    }
}

调用

\App\Cars::apiGet('fields', 'pagination', 'search', 'order', 'filter', 'relations', $input)

等于

    $cars = \App\Cars::apiFields($input['fields']['select'], true)
        ->apiPagination($input['pagination'])
        ->apiSearch($input['search'])
        ->apiOrder($input['order'])
        ->apiFilter($input['filter']['select']);
    
   $cars->apiRelations($cars, $input['fields']['relations'], $input['filter']['relations']);

第二个参数用于检索匹配过滤条件的记录总数。

创建、更新和删除的辅助方法

public function create(array $input)
{
    return $this->car->apiCreate('fields', $input);
}

public function update(array $input, \App\Car $car)
{
    return $car->apiUpdate('fields', 'relations', $input);
}

public function delete(\App\Car $car)
{
    return $car->apiDelete();
}