README

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

安装

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

通过运行以下命令通过composer安装包：

composer require marcelgwerder/laravel-api-handler

一旦composer完成，请将服务提供者添加到app/config/app.php中的providers数组中

Marcelgwerder\ApiHandler\ApiHandlerServiceProvider::class,

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

use Marcelgwerder\ApiHandler\Facades\ApiHandler;

或者在app.php中设置别名

'ApiHandler' => Marcelgwerder\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资源，单个对象和对象集合。

单个对象

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

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

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

ApiHandler::parseSingle($book, 1);

对象集合

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

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

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

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

结果

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): 如果为 true，则结果数组将清理掉意外添加的关系。这些关系如果作为模型访问器的属性访问时可能会自动添加。全局默认的清理设置可以通过配置选项 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 会抛出错误。

包含相关模型

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

所有元字段默认都包含在响应头中。以下是一些自定义头：

使用信封作为响应

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

信封具有以下结构

{
  "meta": {

  },
  "data": [

  ]
}