README

此辅助包提供解析REST-API请求URL的功能。

安装

注意：此版本适用于Laravel 5。当使用Laravel 4时，您需要使用0.4.x版本。

通过运行composer安装此包

composer require youkoulayley/laravel-api-handler

composer安装完成后，将服务提供者添加到app/config/app.php文件中的providers数组中

Youkoulayley\ApiHandler\ApiHandlerServiceProvider::class,

现在将ApiHandler外观导入到您的类中

use Youkoulayley\ApiHandler\Facades\ApiHandler;

或在app.php中设置别名

'ApiHandler' => Youkoulayley\ApiHandler\Facades\ApiHandler::class,

就这样！

从0.3.x迁移到>= 0.4.x

关系注释

现在，关系方法需要@Relation注释来证明它们是关系方法，而不是其他方法（参见问题#11）。

/**
 * @Relation
 */
public function author() {
    return $this->belongsTo('Author');  
}

自定义标识列

如果您将数组作为parseSingle的第二个参数传递，现在必须存在列/值对。这允许我们传递多个条件，如

ApiHandler::parseSingle($books, array('id_origin' => 'Random Bookstore Ltd', 'id' => 1337));

配置

要覆盖配置，在您的应用程序的config文件夹中创建一个名为apihandler.php的文件。
查看包源代码中的配置文件以了解可用的选项。

URL解析

当前URL解析支持

• 限制字段
• 过滤
• 全文搜索
• 排序
• 定义限制和偏移量
• 附加相关模型
• 附加元信息（计数）

支持两种API资源，单个对象和对象集合。

单个对象

如果您处理单个对象资源的GET请求，例如/api/books/1，请使用parseSingle方法。

parseSingle($queryBuilder, $identification, [$queryParams])

• $queryBuilder：查询构建器对象，Eloquent模型或Eloquent关系
• $identification：用于id列的整数或用作对象唯一标识的数组列/值对（array('isbn' => '1234')）。
• $queryParams：包含查询参数的数组。如果未定义，则使用原始GET参数。

ApiHandler::parseSingle($book, 1);

对象集合

如果您处理表示多个对象的资源GET请求，例如/api/books，请使用parseMultiple方法。

parseMultiple($queryBuilder, $fullTextSearchColumns, [$queryParams])

• $queryBuilder：查询构建器对象，Eloquent模型或Eloquent关系
• $fullTextSearchColumns：定义用于全文搜索的列的数组。
• $queryParams：包含查询参数的数组。如果未定义，则使用原始GET参数。

ApiHandler::parseMultiple($book, array('title', 'isbn', 'description'));

结果

Both parseSingle 和 parseMultiple 返回一个具有以下可用方法的 Result 对象

getBuilder(): 返回应用了所有函数的原始 $queryBuilder。

getResult(): 返回Laravel的 get() 或 first() 函数返回的结果对象。

getResultOrFail(): 如果您期望多个对象，则返回Laravel的 get() 函数返回的结果对象，如果期望单个对象，则返回 firstOrFail()。

getResponse($resultOrFail = false): 返回一个包含正文、标头和HTTP状态码的Laravel Response对象。如果 $resultOrFail 为true，则内部使用 getResultOrFail() 方法而不是 getResult()。

getHeaders(): 返回准备好的标头数组。

getMetaProviders(): 返回元提供者对象数组。这些对象中的每个都通过其 get() 方法提供特定类型的元数据。

cleanup($cleanup): 如果为真，结果数组将从意外添加的关系中清理出来。如果它们作为模型访问器中的属性被访问，这些关系可以自动添加。清理的全局默认值可以通过使用配置选项 cleanup_relations 来定义，默认为 false。

ApiHandler::parseSingle($books, 42)->cleanup(true)->getResponse();

过滤

除了预定义的函数 _fields、_with、_sort、_limit、_offset、_config 和 _q 之外，每个查询参数都被解释为过滤器。在将参数传递给 parseMultiple 之前，请务必删除不用于过滤的额外参数。

/api/books?title=The Lord of the Rings

所有过滤器都使用 AND 运算符组合。

/api/books?title-lk=The Lord*&created_at-min=2014-03-14 12:55:02

上面的示例将生成以下 SQL where 子句

WHERE `title` LIKE "The Lord%" AND `created_at` >= "2014-03-14 12:55:02"

也可以为单个过滤器使用多个值。多个值由竖线 | 分隔。除非有 -not 后缀，否则多个值使用 OR 组合。例如，所有ID为5或6的书籍

/api/books?id=5|6

或所有ID不是5或6的书籍

/api/books?id-not=5|6

这也可以使用 -in 后缀实现

/api/books?id-in=5,6

分别的 not-in 后缀

/api/books?id-not-in=5,6

后缀

排序

两种排序方式：升序和降序。应该降序排序的每一列始终以一个 - 开头。

/api/books?_sort=-title,created_at

全文搜索

支持两种全文搜索实现。您可以通过更改配置文件中的 fulltext 选项来选择使用哪种实现，可以是 default 或 native。

注意： 当使用空的 _q 参数时，搜索将始终返回空结果。

有限的定制实现（默认）

给定文本被分割成关键词，然后这些关键词在数据库中搜索。每当其中一个关键词存在时，对应的行就被包含在结果集中。

/api/books?_q=The Lord of the Rings

上面的示例返回包含一个或多个关键词 The、Lord、of、the、Rings 的行。要在全文搜索中考虑的列传递给 parseMultiple。

原生 MySQL 实现

如果您的 MySQL 版本支持您使用的引擎的全文搜索，您可以在 API 处理器中使用这种高级搜索。
只需将 fulltext 配置选项更改为 native，并确保在传递给 parseMultiple 的列上有一个适当的全文索引。

每个结果还将包含一个 _score 列，允许您根据与搜索词的匹配程度对结果进行排序。例如。

/api/books?_q=The Lord of the Rings&_sort=-_score

您可以通过修改配置文件中的 fulltext_score_column 设置来调整此列的名称。

限制结果集

要定义结果中数据集的最大数量，请使用 _limit。

/api/books?_limit=50

要定义结果中数据集的偏移量，请使用 _offset。

/api/books?_offset=20&_limit=50

请注意，为了使用 offset，您必须始终指定一个 limit。MySQL 在没有 limit 的情况下定义偏移量时会抛出错误。

包含相关模型

API 处理器也支持 Eloquent 关系。因此，如果您想获取所有带作者的书籍，只需将作者添加到 _with 参数中。

/api/books?_with=author

关系也可以嵌套

/api/books?_with=author.awards

为了使其工作，您必须将 @Relation 注解添加到每个关系方法中，如下所示

/**
 * @Relation
 */
public function author() {
    return $this->belongsTo('Author');  
}

这是出于安全原因，以便只能通过使用 _with 来调用实际的关系方法。

注意： 当与 _with 结合使用 _fields 来限制字段时，在底层，字段会扩展为关系的主键/外键。Eloquent 需要链接键来获取相关模型。

包含元信息

可以在响应中添加额外的信息。目前有两种类型的计数可以添加到响应头中。

total-count 表示资源的所有元素的数量，或者更具体地说，是原始传递的查询构建实例上的计数。还有 filter-count，它还考虑了过滤器。例如，它们可以用于实现分页。

/api/books?id-gt=5&_config=meta-total-count,meta-filter-count

默认情况下，所有元字段都通过响应头提供。以下自定义头被使用

使用信封响应

默认情况下，元数据包含在响应头中。如果您希望在响应体中将所有内容放在一起，可以通过包含 response-envelope 到 _config 参数中，或者覆盖包的默认 config.php 来请求所谓的“信封”。

信封具有以下结构

{
  "meta": {

  },
  "data": [

  ]
}