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));

配置

要覆盖配置，在您的应用配置文件夹中创建一个名为 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'));

结果

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

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

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

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

getResponse($resultOrFail = false): 返回包含正文、标题和 HTTP 状态码的 Laravel Response 对象。如果 $resultOrFail 为真，则内部使用 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 在没有 limit 的情况下定义偏移量时会抛出错误。

包含相关模型

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

/api/books?_with=author

关系也可以嵌套

/api/books?_with=author.awards

要使这起作用，您必须为每个关系方法添加 @Relation 注解，例如

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

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

注意： 当您结合使用 _fields 和 _with 限制字段时。底层中，字段通过关系的主键/外键进行扩展。Eloquent 需要链接键来获取相关模型。

包含元信息

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

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

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

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

为响应使用信封

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

信封具有以下结构

{
  "meta": {

  },
  "data": [

  ]
}