README

这是一个Laravel框架的API包。它允许您构建一个灵活的RESTful API，可以被外部应用和您自己的应用消费。

安装

Composer

将以下内容添加到您的composer.json文件中的require对象

"mmanos/laravel-api": "dev-master"

然后，运行composer install来安装包。

服务提供者

在您的app配置文件中注册Mmanos\Api\ApiServiceProvider。

类别名

将类别名添加到app/config/app.php文件中的aliases数组中。

'aliases' => array(
	// ...
	'Api' => 'Mmanos\Api\Api',
)

Laravel 4

使用1.0分支或v1.*标签以支持Laravel 4。

配置

发布配置文件和迁移

将lucadegasperi/oauth2-server-laravel的配置文件和迁移发布到您的应用。

$ php artisan vendor:publish --provider="LucaDegasperi\OAuth2Server\OAuth2ServerServiceProvider"

编辑发布的配置文件以符合您的认证需求。请参阅此配置选项页面以获取更多信息。

发布mmanos/laravel-api的配置文件和迁移到您的应用。

$ php artisan vendor:publish --provider="Mmanos\Api\ApiServiceProvider"

然后运行迁移。

$ php artisan migrate

将以下行添加到您的app/Http/Kernel.php文件中的$middleware数组，以捕获任何OAuth错误并适当地响应

'LucaDegasperi\OAuth2Server\Middleware\OAuthExceptionHandlerMiddleware'

为了使某些授权和资源服务器与Laravel 5正确工作，请从$middleware数组中删除App\Http\Middleware\VerifyCsrfToken行，并将其放置在$routeMiddleware数组中，如下所示：'csrf' => 'App\Http\Middleware\VerifyCsrfToken',。

注意：请记住，在适当的路由上手动添加csrf中间件。

处理异常

我们需要修改异常处理器，以正确格式化由该包抛出的异常。更新App/Exceptions/Handler.php文件，以使用该包的异常处理器。

use Exception;
use Mmanos\Api\Exceptions\Handler as ExceptionHandler;

class Handler extends ExceptionHandler {
	...
}

然后，将Mmanos\Api\Exceptions\HttpException异常类添加到$dontReport数组中，以便不报告常规HTTP异常。

控制器

配置

将ControllerTrait添加到每个API控制器中。您可以选择将其添加到由所有其他控制器扩展的BaseController中。

use Illuminate\Routing\Controller;
use Mmanos\Api\ControllerTrait;

class BaseController extends Controller
{
	use ControllerTrait;
}

分页

如果您从控制器操作返回分页对象，此包将向响应添加以下头信息

• 分页-页码
• 分页-数量
• 分页-总数
• 分页-最后一页

设置自定义响应头

您可以直接从控制器操作中访问响应对象并设置任何其他头信息。

$this->response()->header('Example-Header', 'Example value');

错误

处理构建API时的错误很容易。只需使用Api::abort方法抛出一个将被格式化成有用形式的异常。

抛出一个404未找到错误

Api::abort(404);

或403访问拒绝错误

Api::abort(403);

自定义错误消息

Api::abort(403, 'Access denied to scope: users:write');

将验证对象中的错误传递过去，以获取包含所有验证错误的整洁响应

Api::abort(422, $validator->errors());

保护API端点

您可以使用protect路由过滤器来确保请求已认证

$this->beforeFilter('protect');

或您可以直接调用Api::protect()方法。

如果此检查失败，将调用Api::abort(401)，导致返回未授权错误响应。

检查作用域访问

使用checkscope路由过滤器来确保请求的资源可访问

$this->beforeFilter('checkscope:users.write');

或您可以直接调用Api::checkScope('users:write')方法。

如果此检查失败，将调用Api::abort(403)，导致返回带有作用域名称的访问拒绝错误响应。

转换输出

您控制器操作返回的任何模型、集合或分页对象都将自动通过任何绑定的转换器类发送。

转换器

转换器允许您轻松且一致地将对象转换为数组。通过使用转换器，您可以类型转换整数、类型转换布尔值，并嵌套关系。

将类绑定到转换器

Api::bindTransformer('User', 'Transformers\User');

设置类属性

或者，您可以在类中添加一个 transformer 属性，以便该包自动识别

class User extends Eloquent
{
	public $transformer = 'Transformers\User';
}

创建转换器类

确保您的转换器类有一个 transform 静态方法

namespace Transformers;

class User
{
	public function transform($object, $request)
	{
		$output = $object->toArray();
		$output['id'] = (int) $output['id'];
		$output['created_at'] = $object->created_at->setTimezone('UTC')->toISO8601String();
		$output['updated_at'] = $object->updated_at->setTimezone('UTC')->toISO8601String();
		
		if ($request->input('hide_email')) {
			unset($output['email']);
		}
		
		return $output;
	}
}

内部请求

这个包的一大特点是能够在您的API内部执行请求。这允许您在可消费的API之上构建应用程序。

执行请求

使用 Api::internal() 方法来发起内部请求

$users_array = Api::internal('api/users')->get();

传递额外参数

$users_array = Api::internal('api/users', array('sort' => 'newest'))->get();

指定HTTP方法

$new_user_array = Api::internal('api/users', array('email' => 'test@example.com'))->post();

CORS支持

CORS支持默认启用，但仅在检测到 Origin 标头时。调整配置文件中的设置以控制行为和头值。