lumen

HTTP路由

• 基本路由

• 路由参数

  1. 必填参数
  2. 可选参数
  3. 正则表达式约束

• 命名路由

• 路由组

  1. 中间件
  2. 命令空间
  3. 路由前缀

基本路由

你可以在 route/web.php 文件中定义应用程序的全部路由。最基本的Lumen路由仅接受URL和一个Closure：

$router->get('foo', function(){
	return 'Hello, World';
});

$router->post('foo', function(){
	//
});

可供使用的路由方法

我们可以注册路由来响应任何方法的HTTP请求：

$router->get($uri, $callback);
$router->post($uri, $callback);
$router->put($uri, $callback);
$router->patch($uri, $callback);
$router->delete($uri, $callback);
$router->options($uri, $callback);

路由参数

必填参数

当然，有时需要在路由中捕获一些URL片段。例如，从URL中捕获用户的ID，可以通过通过定义路由参数来执行此操作：

$router->get('user/{id}', function ($id) {
	return "User：" . $id;
});

也可以根据需要在路由中定义多个参数：

$router->get('posts/{postId}/comments/{commentId}', function ($postId, $commentId) {
	//
});

路由的参数都会被放在[大括号]内。当运行路由时，参数会传递到Closure里面。

注意：路由参数不能包含-字符。请用下划线_代替。

可选参数

你可以通过将部分路由URI包含在[...]中来定义可选的路由参数。那么像/foo[bar]将会匹配到/foo和/foobar。可选参数仅支持放在URI的末尾。换句话说，你不能在路由定义的中间位置放置可选参数：

$router->get('user'[/{name}]', function ($name = null) {
	return $name;
});

正则表达式约束

你可以通过在路由定义中使用正则表达式来约束路由参数的格式：

$router->get('user2/{name:[a-zA-Z]}', function () {
	//
});

命名路由

命名路由可以方便的为特定路由生成URL或者进行重定向。你可以使用as数组键指定名称到路由上：

$router->get('profile', ['as' => 'profile', function() {
	//
}]);

你还可以指定控制器行为的路由名称：

$router->get('profile', [
	'as' => 'profile',
	'uses' => 'UserController@showProfile',
]);

生成指定路由的URL

为路由制定了名称后，就可以使用全局辅导函数route来生成链接或者重定向到该路由：

//Generating URLs...

$url = route('profile');

//Generating Redirects...

return redirect()->route('profile');

如果是有定义参数的命名路由，可以把参数作为route函数的第二个参数传入，指定的参数将会自动插入到URL中对应的位置：

$router->get('user/{id}/profile', ['as' => 'profile', function ($id) {
	return $id;
}]);

$url = route('profile', ['id' => 1]);

路由组

路由群组允许你共用路由属性，例如：中间件、命名空间，你可以利用路由组统一为多个路由设置共同属性，而不需要在每个路由都设置一次。共用属性被指定为数组格式，当做$router->group方法的第一个参数。

为了了解更多路由群组的相关内容，我们可以通过几个常用样例来熟悉这些特性。

中间件

要给路由组中所有的路由分配中间件，你可以在group属性数组中使用middleware字段。中间件会依照它们在数组中列出的顺序来运行：

$router->group(['middleware' => 'auth'], function () use ($router) {
	$router->get('/', function () {
		//使用Auth中间件
	});

	$router->get('user/profile', function () {
		//使用Auth 中间件
	});
});

命名空间

另一个常见的例子是，指定相同的PHP命名空间给控制器群组。可以使用namespace参数来指定群组内所有控制器的命名空间：

$router->group(['namespace' => 'Admin'], function () use ($router) {
	//使用"App\Http\Controllers\Admin"命名空间
	$router->group(['namespace' => 'User', function () use ($router) {
		//使用"App\Http\Controllers\Admin\User" 命名空间...
	}]);
});

路由前缀

通过路由群组数组属性中的prefix，在路由群组内为每个路由指定的URI加上前缀。例如，你可能想要在路由群组中将所有的路由URI加上前缀admin：

$router->group(['prefix,' => 'admin'], function () use ($roter) {
	$router->get('users', function () {
		//匹配The "/admin/users"URL
	});
});

你也可以使用prefix参数去指定路由群组*用的参数：

$router->group(['prefix' => 'accounts/{accountId}'], function () use ($router) {

$router->get('detail', function ($accountId) {

//匹配The "/accounts/{accountId}/detail" URL

});

});

HTTP中间件

• 简介

• 定义中间件

• 注册中间件

  • 全局中间件
  • 为路由指定中间件

• 中间件参数

• Terminal中间件

简介

HTTP中间件提供了一个方便的机制来过滤进入应用程序的HTTP请求。例如，lumen内置了一个中间件来验证用户的身份认证。如果用户未通过省份证，中间件将会把用户导向登录页面，反之，当用户通过了身份证，中间件将会通过此请求并接着往下执行。

当然，除了身份证之外，中间件也可以被用来运行各式各样的任何，如：CORS中间件负责替换所有即将离开程序的响应加入适当的标头；而日志中间件则可以记录所有出入应用从程序的请求。

所有的中间件都放在app/Http/Middleware目录内。

定义中间件

你可以通过赋值lumen内置的示例文件ExampleMiddleware来创建一个中间件。在这个中间件中，我们只允许参数age大于200的请求才能访问该路由。否则，我们将此用户重定向到首页"home"这个URI上。

正如你所见，假如给定的age参数小于或者等于200，这个中间件将返回一个HTTP重定向到客户端；否则，请求将进一步传递到应用中。要让请求继续传递到应用程序中（即允许“通过”中间件验证的），只需要使用$request作为参数去调用回调函数$next。

最好将中间件想象为一系列HTTP请求必须经过才能进入你的应用的层。每一个都会检查请求

（是否符合某些条件），（如果不符合）甚至可以（在请求访问你的应用之前）完全拒绝掉。

前置/后置中间件

中间件是在请求之前或者之后运行取决于中间件本身。例如，接下来的这个中间件将在应用处理请求before执行其任务：

middleware()方法中列出这个中间件：

$app->middleware([
App\Http\Middleware\OldMiddleware::class
]);

### 为路由分配中间件 ###

如果你想将中间件分配给特定的路由，首先需要在bootstrap/app.php文件中调用$app->routeMiddleware()方法时为中间件分配一个简短的键：

$app->routeMiddleware([
'auth' => App\Http\Middleware\Authenticate::class,
]);

一旦在HTTP内核中定义好了中间件，就可以在路由选项内使用middleware键：

$router->get('admin/profile', ['middleware' => 'auth', function () {
//
}]);

可以使用数组为路由指定多个中间件：

$router->get('/', ['middleware' => ['first', 'second'], function () {
//
}]);

# 中间件参数 #

中间件也可以接受自定义传参，例如，要在运行特定操作前检查已验证用户是否具备该操作的“角色”，可以创建RoleMiddleware来接受角色名称作为额外的传参。

附加的中间件参数将会在$next参数之后被传入中间件：

user()->hasRole($role)) {
//重定向...
}

return $next($request);
}
}

在路由中可以使用冒号：来区隔中间件名称与指派参数，多个参数可以使用逗号作为分割：

$router->put("post/{id}", ['middleware' => 'role:editor', function($id) {
//
}]);

### Terminable 中间件 ###

有时中间件可能需要在HTTP响应发送到浏览器哦之后处理一些工作。例如，“session”中间件会在响应发送到浏览器之后将会话数据写入存储器中。想要做到这一点，你需要定义一个名为“terminable”的中间并添加一个terminal方法：

get("user/{id}", "UserController@show");

现在，当请求匹配到这个特定的URL时，UserController类中的show方法就会执行。当然，路由的参数也同样传递给了这个方法。

### 控制器和命名空间 ###

有一点非常重要，那就是我们要注意在定义控制器路由时，不需要指定完整的控制器命名空间。我们只需定义“根”命名空间App\Http\Controllers之后的类名部分。默认情况下，bootstrap/app.php文件在加载routes.php时已经把所有路由都配置到了根控制器命名空间。

如果你选择在App\Htpp\Controllers目录内层使用PHP命名空间嵌套或者组织控制器，只要使用相对于App\Http\Controllers根命名空间的特定名称即可。因此，如果你的控制器类全名是App\Http\Controllers\Photos\AdminController，那么你应该注册一个路由，如下所示：

$router->get('foo', 'Photos\AdminController@method');

### 命名控制器路由 ###

像闭包那样，你可以给控制器路由指定一个名称：

$router->get('foo', ['uses' => 'FooController@method', 'as' => 'name']);

你也可以使用route辅助函数，来生成指向控制器路由的URL：

$url = route('name');

### 控制器中间件 ###

中间件可通过如下方式分配到路由中：

$router->get('profile', [
'middleware' => 'auth',
'uses' => 'UserController@showProfile'
]);

然而，更方便的方式是在控制器的构造方法里面使用middleware方法指定中间件。你甚至可以限制中间件只应用于该控制器类的某些方法：

class UserController extends Controller
{
/**
*实例化一个新的UserController实例。
*@return void
*/
public function __construct()
{
$this->middleware('auth');

$this->middleware('log', [
'only' => ['fooAction', 'barAction']
]);

$this->middleware('subscribed', ['except' => [
'fooAction',
'barAction',
]]);
}
}

## 依赖注入与控制器 ##

#### 构造器注入 ####

lumen使用[服务容器]来解析所有的控制器的依赖注入。因此，你可以在控制器的构造函数中使用类型提示需要的任何依赖。这些依赖会自动的解析并注入到控制器实例中：

namespace App\Http\Controllers;

use App\Repositories\UserRepository;

class UserController extends Controller
{
/**
*新建一个控制器实例
*
*@param UserRepository $users
*@return void
*/
public function __contruct(UserRepository $users)
{
$this->users = $users;
}
}

方法注入

除了构造器注入以外，你也可以在你的控制器方法中使用类型提示依赖。例如，在某个方法中添加Illuminate\Http\Request实例的类型提示：

input('name');
}
}

如果你想在控制器里获取路由参数，只需要在路由之后列出参数即可。例如，你的路由这样来定义：
$router->put('user/{id}', 'UserController@update');

你可以像下面的例子一样定义你的控制器，用类型提示注入Illuminate\Http\Request类和你的路由参数id：

input('name');
//
}
}

如果你的控制器方法也期望从路由参数中获取数据，只需要将路由参数放在其他依赖后面，比如你的路由是这样定义的：

$router->put('user/{id}', 'UserController@update');

像下面这样定义你的控制器方法，就可以使用Illuminate\Http\Request类型提示，同时获取到路由参数id：

path();

is方法会返回请求的URI是否与指定规则匹配，你可以使用*符号作为通配符：

if($request->is('admin/*')) {
//
}

如果要获取完整的URL而不是URI，可以使用url或者fullURL方法：

//不包含请求参数
$url = $request->url();

//包含请求参数
$url = $request->fullUrl();

# 获取请求的方法 #

method方法将会请求的HTTP动作，你可以使用isMethod方法校验HTTP动作是否与指定字符串匹配：

$method = $request->method();

if ($request->isMethod('post')) {
//
}

# PSR-7请求 #

PSR-7标准规定了HTTP消息接口包含了请求及响应，如果你想获得PSR-7的请求实例，就需要先
安装几个库，laravel使用Symfony的HTTP消息桥组件，将原laravel的氢气及响应转换至PSR-7所支持的实现：

composer require symfony/psr-http-message-bridge

composer require zendframework/zend-diactors

安装完这些库后，你就可以在路由或者控制器中，简单的对请求类型使用类型提示来获取PSR-7请求：

use Psr\Http\Message\ServerRequestInterface;

$router->get('/', function (ServerReuestInterface $request) {
//
});

如果你从路由或者控制器反悔了一个PSR-7的响应实例，那么它会被框架自动转换为laravel的响应实例并显示。

# 获取输入数据 #

## 获取指定输入值 ##

你可以通过Illuminate\Http\Request实例，使用几个简单的方法来获取所有的用户输入数据，而不需要担心请求的HTTP动作，因为它们的获取方式是相同的：

$name = $request->input('name');

你可以在input方法的第二个参数中传入一个默认值，当请求参数不存在时，就会返回默认值：

$name = $request->input('name', 'Sally');

当数据是以数组形式输入时，你可以使用“点”符号来获取数组：

$name = $request->input('products.0.name');

$name = $request->input('products.*.name');

# 确认输入值是否存在 #

你可以通过has方法判断输入值是否存在，输入值存在时has方法将会返回true：

if($request->has('name')) {
//
}

当给定一个数组时，has方法将确认是否所有指定值都存在：

if ($request->has(['name', 'email'])) {
//
}

如果你想确定请求中是否存在值并且不为空，可以使用filled方法：

if($request->filled('name')) {
//
}

# 获取所有输入数据 #

你可以使用all方法以数组形式获取所有的输入数据：

$input = $request->all();

# 获取部分输入数据 #

如果你想获取数据的子集，你可以是only和except方法，这两个方法都接受单个数组或者动态列表作为参数：

$input = $request->only(['username', 'password']);

$input = $request->only('username', 'password');

$input = $request->except(['credit_card']);

$input = $request->except('credit_card');

# 文件上传 #

### 获取上传文件 ###

你可以使用Illuminate\Http\Request实例中的发file方法获取上传的文件，file方法返回的对象是Symfony\Component\HttpFoundation\File\UploadFile类的实例，这个类继承了PHP的SplFileInfo类，并且提供了多种与文件交互的方法：

$file = $request->file('photo');

你可以使用hasFile方法确认上传的文件是否存在：

if ($request->hasFile('photo')) {
//
}

验证上传是否成功

除了检查文件是否存在之外，你还可以通过isValid方法验证上传是否存在问题：

if ($request->file('photo')->isValid()) {
//
}

## 移动上传文件 ##

要将上传的文件移动到新的位置，你应该使用move方法，这个方法会将文件从临时位置（由PHP配置决定）移动到你指定永久存储位置：

$request->file('photo')->move($destinationPath);

$request->file('photo')->move($destinationPath, $fileName);

# 其他上传文件方法 #

UploadFile实例还有很多其他可用的方法，可以到该类的API文档了解这些方法的详细信息。

# HTTP响应 #

## 基本响应 ##

当然，所有的路由及控制器必须返回某个类型的响应，并发送回用户的浏览器。laravel提供了集中不同的方法来返回响应。最基本的响应就是从路由或者控制器简单的返回一个字符串：

$router->get('/', function () {
return 'Hello World';
});

指定的字符串会被框架自动转为HTTP响应。

### 响应对象 ###

但是，对于大多数路由和控制器行为操作，你将返回完整的Illuminate\Http\Response实例。返回完整的Response实例允许你自定义响应的HTTP状态码和标题。一个Response实例继承自Symfony\Componet\HttpFoundation\Response类，并且提供了多种构建HTTP响应的方法：

use Illuminate\Http\Response;

$router->get('home', function () {
return (new Response($content, $status))
->header('Content-Type', $value);
});

为了方便起见，你可以使用response辅助函数：

$router->get('home', function () {
return response($content, $status)
->header('Content-Type', $value);
});

注意：有关Response方法的完整列表可以参考API文档一级Symfony api文档。

## 附加标头至响应 ##

大部分的响应方法是可以链式调用的，折让你可以顺畅的创建响应。举例来说，你可以在响应发送给用户之前，使用header方法增加一系列的标头至响应：

return response($content)
->header('Content-Type', $type)
->header('X-header-One', 'header Value')
->header('X-Header-Two', 'header Value');

或者你可以使用withHeaders方法来设置数组标头：
return response($content)
->withHeaders([
'Content-Type' => $type,
'X-header-One' => 'Header Value',
'X-header-Two' => 'Header Value',
]);

## 其他响应类型 ##

使用辅助函数response可以轻松的生成其他类型的响应实例、当你调用辅助函数response并且不带任何参数时，将会返回Laravel\Lumen\Http\ResponseFactory contract的实现。此Contract提供了一些有用的方法来生成响应。

JSON响应

json方法会自动将标头的Content-Type设置为application/json。并且通过PHP的接送_encode函数将制定的数组转换为json：

return response()->json(['name' => 'Abigail', 'state' => 'CA']);

你可以选择提供一个状态码和一个额外的标题数组：

return response()->json(['error' => 'Unauthorized'], 401, ['X-Header-One' => 'Header Value']);

如果你想创建一个JSONP响应，则可以使用json方法并加上setCallback方法：

return response()
->json(['name' => 'Abigail', 'state' => 'CA'])
->setCallback($request->input('callback'));

文件下载

download方法可以用于生成强制让用户的浏览器下载指定路劲文件的响应。download方法接受文件名称作为方法的第二个参数，此名称为用户下载文件时看见的文件名称。最后，你可以传递一个标头的数组作为第三个参数传入该方法：

return reponse()->download($pathToFile);

return response()->download($pathToFile, $name, $headers);

注意：管理文件下载的扩展包Symfony HTTPFoundation，要求下载文件必须是ASCII文件名。

## 重定向 ##

重定向响应是类illuminate\Http\RedirectResponse的实例，并且包含用户要重定向至另一个URL所需的正确标头。有几种方法可以生成RedirectResponse的实例。最简单的方法就是通过redirect辅助函数：

$router->get('dashboard', function () {
return redirect('home/dashboard');
});

### 重定向至命名路由 ###

当你调用redirect辅助函数并且不带任何参数时，将会返回laravel\Lumen\Http\Redirecotr的实例，你可以对该Redirector的实例调用任何方法。举个例子，要生成一个RedirectResponse到一个命名路由，你可以使用route方法：

return redirect()->route('login');

如果你的路由有参数，则可以将参数放进route方法的第二个参数，如下：

//For a route with follwing URI：profile/{id}
return redirect()->route('profile', ['id' => 1]);

如果你要重定向至路由并且路由的参数为Eloquent模型的[ID]，则可以直接将模型传入，ID将会自动被提取：

return redirect()->route('profile', [$user]);

## 用户认证 ##

#### 简介 ####

lumen虽然与laravel使用了相同的底层类库实现，但是因lumen面向的是无状态API的开发，不支持session，所以默认的配置不同。lumen必须使用无状态的机制来实现认证，如api令牌（Token）。

#### 开始 ####

#### 认证服务提供者 ####

注意：在使用lumen的认证功能前，请取消bootstrap/app.php文件中的AuthServiceProvider调用代码的注释。

AuthServiceProvider存放在app/Providers文件夹中，此文件中只有一个Auth::viaRequest调用。viaRequest会在系统需要认证的时候被调用，此方法接受一个Closure（匿名函数）参数。在此closure(匿名函数)内，你可以任意的解析App\User并返回，或者在解析失败时返回null：

$this->app['auth']->viaRequest('api', function ($request) {
//返回User或者null...
});

同样，你可以使用你期望的方式取得用户认证，比如在请求头或者查询字符串中使用api令牌、请求中的bearer令牌，或者使用应用程序需要的任何其他方法。

如果你的项目没有使用Eloquent，你需要返回一个Illuminate\Auth\GenericUser类的实例。这个类接受一个属性数组作为构造函数的唯一参数：

use Illuminate\Auth\GenericUser;

return new GenericUser(['id' => 1, 'name' => 'Taylor']);

# 缓存 #

### 简介 ###
laravel为各种缓存系统提供了统一的api。缓存配置位于.env文件中。在该文件中你可以指定应用默认使用哪个缓存驱动。laravel支持当前流行的后端缓存，例如memcached和Redis。

不同于laravel

lumen缓存驱动与laravel缓存驱动使用了完全相同的代码。除配置之外，在lumen中使用缓存和在laravel中使用缓存没有区别；因此，请参阅laravel文档来获取使用示例。

注意：在使用cache facade之前，请确保在bootstrap/app.php文件中没有注释掉$app->withFacaes()方法的调用。

Redis支持

在使用lumen的Redis缓存之前，你需要通过composer安装illuminate/redis(5.5.*)包。然后，你需要在bootstrap/app.php文件中注册illuminate\Redis\RedisServiceProvider。

如果你没有在bootstrap/app.php文件中调用$app->withEloquent()，那么你应该在bootstrap/app.php文件中调用$app->configure('database');以确保正确加载Redis数据库配置。

# 缓存 #

### 简介 ###
laravel为各种缓存系统提供了统一的api。缓存配置位于.env文件中。在该文件中你可以指定应用默认使用哪个缓存驱动。laravel支持当前流行的后端缓存，例如Memcached和Redis。

### 不同于laravel ###

lumen缓存驱动与laravel缓存驱动使用了完全相同的代码。除配置之外，在lumen中使用缓存和在laravel中使用缓存没有区别；因此，请参阅laravel文档来获取使用示例。

注意：在使用Cache Facade之前，请确保在bootstrap/app.php文件中没有注释掉$app->withFacdes()方法的调用。

Redis支持

在使用lumen的Redis缓存之前，你需要通过composer安装illuminate/redis（5.5.*）包。然后，你需要在bootstrap/app.php文件中注册illuminate\Redis\RedisServiceProvider。

如果你没有在bootstrap/app.php文件中调用$app->withEloquent()。那么你应该在bootstrap/app.php文件中调用$app->configure()；以确保正确加载Redis数据库配置。

# 数据库 #

### 配置 ###

lumen让连接数据库和执行查询变得非常简单。目前lumen支持四种数据库系统：MySQL，Postgres，SQLite和SqlServer。

你可以在.env配置文件中使用DB_*选项配置数据库设置，例如数据库驱动、host、用户名和密码。

### 基本用法 ###

注意：如果你想使用DB facade，你应该去掉在bootstrap/app.php文件中$app->withFacades()的调用的注释。

例如，在不启用facades时，你可以通过app辅助函数连接数据库：

$result = app('db')->select("SELECT * FROM users");

或者，在启用facades后，你可以通过DB facade来连接数据库：

$result = DB::select("SELECT * FROM users");

### 基本查询 ###

要了解如何通过数据库组件执行基本的原始SQL查询，请参考laravel文档

### 查询构造器 ###

lumen同样支持Eloquent ORM的流式查询构造器。要了解这个特性的更多信息，请参阅laravel文档。

### Eloquent ORM ###
如果你喜欢使用Eloquent ORM，你应该去掉bootstrap/app.php文件中对$app->withQloquent()调用的注释。
当然，你可以在lumen中非常容易的使用完整的Eloquent ORM。要了解如何使用Eloquent，请参考laravel文档。

### 迁移 ###

关于如何创建数据库表和执行迁移的更多文档，请参考laravel文档中的迁移。

# 加密与解密 #

## 配置 ##

在使用lumen的加密之前，你应该先把.env文件中APP_KEY选项设置为32位随机字符串。如果没有适当地设置这个值，所有被lumen加密的值都将是不安全的。

### 基本用法 ###

#### 加密一个值 ####

你可以使用crypt门面来加密一个值。所有的加密值都使用OpenSSL和AES-256-CBC来进行加密。此外，所有加密过的值都会使用消息认证码（MAC）来进行签名，以检测加密字符串是否被篡改过：

例如，我们可以使用encrypt方法加密机密信息，并把它保存在Eloquent模型：

fill([
'secret' => Crpty::encrypt($request->secret)
])->save();
}
}

加密一个值

当然，你可以使用crypt门面的decrypt方法来解密值。如果该值不能够被正确的解密。例如当MAC（消息认证码）无效时，就会抛出异常Illuminate \Contracts\Encryption\DecryptException：

use Illuminate\Contracts\Encryption\DecryptException;

try{
$desrypted = Crypt::decrypt($encryptedValue);
}catch (DecryptException $e){
//
}

## 错误与日志 ##

### 简介 ###

当你开始一个新的Lumen项目时，lumen就已经帮你配置好错误和异常处理的操作。另外，lumen也集成了Monolog日志函数库，Monolog支持和提供多种强大的日志处理功能。

有关错误的更多信息，请参阅完整的laravel错误文档。
有关日志的更多信息，请参阅完整的laravel的日志文档。

## 错误处理 ##

#### 介绍 ####

当你启动一个新的laravel项目时，错误及异常处理是已为你配置好了的。
App\Exceptions\Handler类负责记录应用程序触发的所有异常并呈现给用户。在本文档中，我们将深入探讨这个类。

配置

你的config/app.php配置文件中的debug选项决定了对于一个错误实际上讲显示多少信息给用户。默认情况下，该选项的设置将遵循存储在.env文件中的APP_DEBUG环境变量的值。

对于本地开发，你应该将APP_DEBUG环境变量的值设置为true。在生产环境中，该值赢始终未false。如果在生产将该值设置为true，则可能会将敏感配置暴露给应用程序的最终用户。

异常处理器

report方法

所有异常都是由App\Exceptions\Handler类处理。这个类包含两个方法：report和rendor。我们将详细剖析这些方法。report方法用户记录异常或将它们发送给如Bugsnag或者Sentry等外部服务。默认情况下，report方法将异常传递给记录异常的基类。不过，你可以任何自己喜欢的方式来记录异常。

例如，如果你需要以不同方式报告不同类型的异常，则可以使用PHP的instanceof比较运算符：

/**
*报告或者记录异常
*
*此处是发送异常给sentry、Bugsnag等外部服务的好位置。
*
*@param \Exception $exception
*@return void
*/
public function report()
{
if ($exception instance CustomException) {
//
}
return parent::report($exception);
}

{tip}不要在report方法中进行太多的instanceof检查，而应该考虑使用[可报告异常（reportable exception）]
{(/docs/laravel/5.7/errors#renderable-exceptions)}。

### Report辅助函数 ###

有时你可能需要报告异常，但又不希望终止当前请求的处理。report辅助函数允许你使用异常处理器的report方法在不显示错误页面的情况下快速报告异常：

public function isValid()
{
try{
}catch(Exception $e){
report($e);
return false;
}
}

### 按类型忽略异常 ###

异常处理器的$dontReport属性包含一组不会被记录的异常类型。例如，由04错误导致的异常一级其他几种类型的错误不会写入日志文件。你可以根据需要添加其他异常类型到此数组中：

/**
*不应被报告的异常类型清单。
*
*@var array
*/
protected $dontReport = [
\Illuminate\Auth\AuthenticationException::class,
\Illuminate\Auth\Access\AuthorizationException::class,
\Symfony\Component\HttpKernel\Exception\HttpException::class,
\Illuminate\DataBase\Eloquent\ModelNotFoundException::class,
\Illuminate\Validation\ValidationException::class,
];

#### Render方法 ####

Rendor方法负责将给定的异常转换为将被发送回浏览器的HTTP响应。默认值情况下，异常将传递给你生成响应的基类。不过，你可以按自己意愿检查异常类型或者返回自己的自定义响应：

/**
*将异常1转换为HTTP响应。
*
*@param \Illuminate\Http\Request $request
*@param \Illuminate\Exception $exception
*@return \Illuminate\Http\Response
*/
public funtion render($request, Exception $exception)
{
if ($exception instanceof CustomException) {
return response()->view('errors.custom', [], 500);
}

return parent::render($request, $exception);
}

## Reportable & Renderable 异常 ##

除了在异常处理器的report和render方法中检查异常类型，你还可以直接在定义异常上定义report和render方法。当定义了这些方法时，它们会被框架自动调用：

{{ $exception->getMessage() }}

# 日志 #

### 简介 ###
为了帮助你更多的了解应用程序中到底发生了什么，laravel提供了强大的日志服务，允许你将日志消息，系统错误日志记录到文件，甚至使用slack通知到你的整个团队。

在laravel框架中，laravel使用monolog库，它为各种强大的日志处理提供支持。laravel使用配置这些处理程序变得简单，允许泥混合并匹配它们自定义的应用程序日志处理。

### 配置 ###

所有的应用程序日志系统配置都位于config/logging.php配置文件中。这个文件允许你配置你的应用程序日志通信，
所以务必查看每个可用的通信及它们的选项。当然，我们将在下面回顾一些常用的选项。

默认情况下，laravel将使用stack去记录日志消息。stack通道被用来将多个日志通道聚合到一个单一的通道中。关于堆栈的更多信息，查看以下文档。

### 配置通道名称 ###

默认强狂下，monolog使用与当前环境匹配的【通道名称】进行实例化，比如production或者local。要改变这个值，需添加一个name选项到你的通道配置中：

'stack' => [
'driver' => 'stack',
'name' => 'channel-name',
'channels' => ['single', 'slack'],
];

### 可用的通道驱动 ###

名称 描述
single 一个便于创建[多通道]通道的包装器
daily 单个文件或者基于日志通道的路径（StreamHandler）
slack 一个每天轮换的基于monolog驱动的RotatingFileHandler
syslog 一个基于monolog驱动的sysloghandler
errorlog 一个基于monolog驱动的errorlogHandler
monolog 一个可以任何支持monolog处理程序的monolog工厂驱动程序
custom 一个调用指定工厂创建通信通道的驱动程序

{tip}有关monolog和custom驱动，查看高级通道自定义

## 配置slack通道 ##

slack通道需要url配置选项。这个URL应当与你为slack团队配置的一个incoming webhook相匹配。

构建日志栈

如前所述，stack驱动允许你将多个通道合并到一个单一日志通道中。为了说明如何使用日志栈，让我们看一个你可能在生产应用配置中看到的实例配置：

'channels' => [
'stack' => [
'driver' => 'stack',
'channels' => ['syslog', 'slack'],
],

'syslog' => [
'driver' => 'slack',
'url' => env('LOG_SLACK_WEBHOOK_URL'),
'username' => 'Laravel Log',
'emoji' => ':boom:',
'level' => 'critical',
],
],

让我们剖析这个配置。首先，注意我们的stack通道通过它的Channels选项聚合其它两个通道：syslog和slack。因此，当记录日志消息时，这两个通道都有机会去记录日志消息。

### 日志级别 ###

注意上面实例中在syslog和slack通道配置中存在的level配置选项。这个选项决定了一个消息必须被通道记录的最小[level]。monolog为laravel的日志服务提供了RFC-542规范中定义的所有日志级别：emergency，
alert，critical，error，warning，notice，info和debug。

因此，假设我们记录一个日志消息使用debug方法：

Log::debug('An informational message.');

根据我们的配置，syslog通道将写消息到系统日志；然而，由于错误消息不是critical或者这个级别之上，它将不被发送到slack。但是，如果我们记录一个emergency消息，它将被同时发送到系统日志和slack，因为emergency级别高于我们对两个通道最低级别的阈值：

#### Log::emergency('The system is down!'); ####

### 记录日志消息 ###

你可以通过Log外观类将信息写入到日志。如前所述，日志器提供在RPC 5424规范中定义的八个日志级别：

emergency，alert，critical，error，warning，notice，info和debug：

Log::emergency($message);
Log::alert($message);
Log::critical($message);
Log::error($mesage);
Log::warning($message);
Log::notice($message);
Log::info($message);
Log::debug($message);

因此，你可以调用这些方法中的任何一个去记录相应级别的一个日志消息。默认情况下，消息将写入到你的config/logging.php配置文件配置的默认日志通道中：
User::findOrFail($id)]);
}
}

## 记录日志到指定通道 ##

有时候你可能希望将日志记录到非默认通道。你可以使用log facade中的channel方法，将日志记录到应用配置中存在的任何聚到：

Log::channel('stack')->info('Something happened!');

如果你想按需要创建多个渠道的日志堆栈，你可以使用stack方法：

Log::stack(['single', 'slack'])->info("Something happened!");

先进的monolog日志通道定制

自定义monolog日志通道

首先你可能需要完全配置monolog现有的通道。例如：你想要为现有通道自定义一个monolog formatterInterface实现。

首先，在频道配置文件中定义一个tap数组。tap数组应该该包含所需的类列表，这些类就是Monolog实例创建后需要自定义（或者开发）的类：

'single' => [
'driver' => 'single',
'tap' => [],
],

## 事件 ##

#### 简介 ####
lumen事件提供了简单的监听器实现，允许你订阅和监听事件，事件类通常被保存在app/Events目录下，而它们的侦听器被保存在app/Listeners目录下。

### 与laravel的差异 ###

通常，lumen中的事件方法恰好与laravel全栈框架功能一致，所以，请阅读完整的laravel文档。lumen同样支持事件广播，它允许客户端的JavaScript监听服务器的事件。然而，这里还是有些差异值得谈论。

### 生成器 ###

lumen中没有可以用来生成事件和监听器的命令，你可以通过简单赋值ExampleEvent或者ExampleListener文件来定义你自己的事件和监听器，这两个示例文件提供了每个事件和监听器的基础类结构。

#### 注册事件或者监听器 ####

像laravel框架一样，lumen应用内置的EventServiceProvider提供了一个注册所有事件监听器的地方。listen属性一个数组，它包含了所有的事件（键）和监听器（值）。所以，你可以根据应用程序的需要添加事件到这个数组：

/**
*应用程序的事件监听器映射。
*
*@var array
*/
protected $listen = [
'App\Events\ExampleEvent => [
'App\Listeners\ExampleListener',
],
];

### 触发事件 ###

你可以使用event辅助函数或者event门面在lumen应用程序中触发事件。同样，这些函数的行为与laravel框架一致：

event(new ExampleEvent);

Event::dispatch(new ExampleEvent);

### 队列 ###

#### 简介 ####

lumen的队列服务给不同的后端队列提供统的API。队列允许你延迟处理消失的任务，例如在远程服务器上执行任务直到更晚的时间，而同一时间你的应用程序可以快速的处理web应用程序的请求。

就像该框架的许多其他部分一样，lumen的队列服务跟laravel的队列服务功能相同。因此，如果要了解更多关于lumen的队列，则可以参阅laravel消息队列文档。

### 配置 ###

队列配置选项对话都在.env文件中。

如果您想要完全自定义的配置，必须您将vendor/laravel/lumen-framework/config/queue.php文件完整的复制到你的项目目录根中config目录，并且要调整必要的配置。如果config目录不存在，则要创建。

### 驱动程序先决条件 ###

#### 数据库 ####

使用为了database队列驱动程序，您将需要数据库表保存作业和失败情况：

Schema::create('jobs', function (Blueprint $table) {
$table->bigIncrement('id');
$table->string('queue');
$table->longText('payload');
$table->tinyInteger('attempts')->unsigned();
$table->unsignedInteger('reserved_at')->nullable();
$table->unsignedInteger('available_at');
$table->unsignedInteger('created_at');
$table->index(['queue', 'reserved_at']);
});

Schema::create('failed_jobs', function (Blueprint $table) {
$table->increment('id');
$table->text('connection');
$table->text('queue');
$table->longText('payload');
$table->longText('exception');
$table->timestamp('failed_at')->useCurrent();
});

### Redis的 ###

要想使用Redis队列驱动程序，需要先通过composer安装illuminate/redis(5.5.*)扩展包。然后再bootstrap/app.php文件中注册Illuminate\Redis\RedisServiceProvider;

### 其他队列驱动程序的依赖包 ###

下面列出其他队列驱动程序所需要的依赖扩展包：
亚马逊SQS：aws/aws-sdk-php ~3.0
Beanstalked：pda/pheanstalk ~3.0

#### 与laravel的差异 ####

与框架的许多其他部分一样，lumen队列作业的功能与laravel的队列作业功能相同。因此，要了解lumen队列作业功能，请查看完整的laravel队列文档。

不过呢，我们现在讲讨论两个框架间的一些细微差异。首先，我们来谈谈lumen中如何生成队列作业。

#### 生成器 ####

lumen不包括用于自动创建新job类的生成器。因此你需要赋值框架所带的exampleJob类。这个类提供了每个job类共享的基本结构。examplejob所继承的job基类已包含所需的interactswithqueue，queueable和serializesmodels特性：

withFacades()调用的注释：

Queue::push(new ExampleJob);

### 服务容器： ###

#### 简介 ####

laravel的服务容器是一个管理类依赖和执行依赖注入的强力工具。依赖注入是个花俏的名字，事实上是指：类的依赖通过构造器或者在某些情况下通过【setter】方法【注入】。

### 与laravel的差异 ###

lumen使用了与laravel框架相同的服务器。所以，你可以使用它们所有强大的功能。有关容易的完整文档，请阅读laravel容器文档。

#### 获取服务容器 ####
laravel\lumen\application实例是Illuminate\Container\Container的扩展，所以你可以当做服务容器来使用。
通常我们会在服务提供者注册我们的容器解析规则。当然，你可以使用bind、singleton’instance、以及容器提供的其他方法。请记住，所有这些方法都记录在laravel服务器容易文档中。
解析实例

想要从服务容器中解析实例，你可以在大部分的功能类里自动解析（依赖注入），如路由closure，控制器的构造方法、控制器方法、中间件、事件监听器，或者队列等。或者，你也可以在应用程序中的任何地方使用App函数来进行解析：

$instance = app(Something::class);

# 服务提供者 #

简介
服务提供者是所有lumen应用程序启动的中心所在。包括你自己的应用程序，以及所有的核心服务，都是服务提供者启动的。

但是，我们所说的启动值得是什么？一般而言，我们指的是注册事物，包括注册服务容易绑定、事件侦听器、中间件，甚至路由、服务提供者设置你的应用程序的中心所在。

若你打开lumen的bootstrap/app.php文件，你将会看到$app->register()方法的调用。你也许需要额外的调用来注册你的服务提供者。

### 编写服务提供者 ###

所有的服务提供者都集成了illuminate\Support\ServiceProvider这个类。这个抽象类要求你在你的提供者上定义至少一个方法：register。在register方法内，你应该只需要将事物绑定到服务容器中。永远不要试图在register方法中注册任何事件侦听器，路由或者任何其他功能。

注册方法

如前面所讲，在register方法中，你只要将事物绑定到【服务容器中】。永远不要试图在register方法中注册任何事件侦听器、路由或者任何其它功能。否则，你有可能会以外的使用到尚未加载的服务提供者提供的服务。

现在，让我们来看一个基本的服务提供者代码：

app->singleton(Connection::class, function ($app) {
return new Connection(config('riak'));
});
}
}

这个服务提供者自定义了一个register方法，并且用这个方法在服务容器中绑定了Riak\Connection的一个实例。如果你不是很了解服务容器的运行原理，请查看[its documentation]。

### 启动方法 ###

那么，如果我们要在服务提供者当中注册一个视图组件呢？这应该在boot方法内完成。此方法在所有其他服务提供者都注册之后才能调用，也就意味着可以访问已经被框架注册的所有服务：

register()方法调用。你也行需要额外的调用$app->register()来注册你的服务提供者。

# 测试 #

### 简介 ###

lumen在创建时就已考虑到测试部分。事实上，lumen默认就支持用PHPunit来做测试，并为你的应用程序创建好了phpunit.xml文件。框架还提供了一些便利的辅助函数，让你可以更直观的测试应用程序的json响应。

## 测试环境 ##

在运行测试时，lumen自动配置讲缓存驱动配置为array，意味着在测试的时候不会保存任何的缓存数据。

你可以随意创建其他必要的测试配置环境。testing的环境变量可以在phpunit.xml文件中进行修改；

## 定义和运行测试 ##

要创建一个测试用例，直接将新的测试文件创建到tests文件夹下即可。测试文件必须继承TestCase。接着就可以像平常使用PHPunit一样来定义测试方法。要运行测试只需要在命令行上运行PHPunit命令即可：

assertTrue(true);
}
}

注意：如果要在你的类自定义setUp方法，请确保调用了parent::setUp。

## 应用测试 ##

lumen提供了一个非常好用的api，使用它用来向你的应用发起HTTP请求，并查看输出结果。

#### 测试json api接口 ####

lumen同样提供了几个测试用于测试json api接口和响应数据的助手。例如，get，post，put，patch和delete方法可以被用于发起各种HTTP请求方式，并且声明以json格式返回一个指定的数组：

json('POST', '/user', ['name' => 'Sally']);
->seeJson([
'created' => true,
]);
}
}

seeJson方法数组转换为json，并验证这个json片段发生在应用返回的整个json响应的任意位置。所以，即使在json响应中存在其他属性，只要指定的片段存在，这个测试任然会成功！

验证完全匹配的json

如果你想验证传入的数组是否与应用程序返回的json完全匹配，你可以用seeJsonEquals方法：
post('/user', ['name' => 'Sally'])
->seeJsonEquals([
'created' => true,
]);
}
}

### 认证 ###

actingAs辅助函数提供了简单的方式来让指定的用户认证为当前的用户：
create();
$this->actingAs($user)
->get('/user');
}
}

自定义HTTP请求

如果你想要创建一个自定义的HTTP请求到应用程序上，并获取完整的 Illuminate\Http\Response对象，可以使用call方法：

public function testApplication()
{
$response = $this->call('GET', '/');
$this->assertEquals(200, $response->status());
}
如果你想构造POST，PUT，或者PATCH请求，可以在请求时传入一个数组作为请求参数，当然，你也可以在路由及控制器中通过请求实例来获取传过来的参数：

$response = $this->call('POST', '/user', ['name' => 'Taylor']);

使用数据库

为了使得测试使用了数据库的应用更加简便，lumen提供了各种有用的工具。首先，你可以使用seeInDatabase助手函数来断言数据库中是否存在给定条件的数据。例如，我们想要验证users表中的有一条email的值为[e-mail]的记录，我们可以按如下操作：

public function testDatabse()
{
//Make call to application...

$this->seeInDatabase('users', ['email' => '[e-mail]']);
}

当然，seeInDatabase方法和类似的助手方法就是会为了方便使用。你也可以在测试中*使用PHPunit的内置断言方法。

### 每次测试之后重置数据库 ###

在每次测试后重置数据库时非常有必要的，这样之前的测试数据不会响应后面的测试。

#### 使用迁移 ####

有一个选择是每次测试之后回滚数据库，并且在下一次测试之前将其迁移。lumen提供了一个简单的DatabaseMigrations特性，它可以自动位您处理。简单的在您的测试类中运用这个特性如下：

get('/foo');
}
}

## 使用事务 ##

另一个选择是将每一个测试用例包装在数据库事务中。撸们提供了便利的DatabaseTransactions特性，可以为您自动的执行这些：

define('App\User', function ($faker) {
return [
'name' => $faker->name,
'email' => $faker->email,
];
});

在作为工厂定义的闭包中，您可以返回模型上所有属性的默认测试值。闭包将接收Faker PHP库的一个实例，它将允许您便利的生成各种随机数据以方便测试。

当然，您可以将您自己的额外的工厂添加到ModelFactory.php文件中。

## 多种工厂类型 ##

有时您可能希望同一个Eloquent模型有多种工厂。例如，可能您会希望除了普通的用户之外还有管理员用户的工厂。您可能会使用defineAs方法定义这些工厂：

$factory->defineAs('App\User', 'admin', function ($faker) {
return [
'name' => $faker->name,
'email' => $faker->email,
'admin' => true,
];
});

您可以使用raw方法检索其基本属性，而不是复制基本用户工厂中的所有属性。一旦拥有这些属性，只需要使用您需要的任何附加值补充它们：

$factory->defineAs('App\Users', 'admin', function ($faker) use ($factory) {
$user = $factory->raw('App\User');
return array_merge($user, ['admin' => true]);
});

## 在测试中使用工厂 ##

在工厂定以后，就可以在测试或者是数据库的填充文件中，通过全局的factory函数来生成模型实例。接着让我们先来看看几个创建模型的例子。首先我们会使用make方法创建模型，但不将他们保存至数据库：
public function testDatabase()
{
$user = factory('App\User')->make();
}

如果你想要写模型中的某些默认值，则可以传递一个包含数值的数组至make方法。只有指定的数值会被替换，其他剩余的数值则会安装工程指定的默认值来设置：

$user = factory('App\User')->make([
'name' => 'Abigail',
]);

你还可以创建许多模型的集合或者创建给定类型的模型：

//Create three App\User isntance...

$users = factory('App\User', 3)->make();

//Create an App\User "admin" instance...
$user = factory('App\User', 'admin')->make();

//Create three App\User "admin" instances...
$users = factory("App\User", 'admin', 3)->make();

维持工厂模式
可以使用create方法创建模型实例，还可以使用save方法将数据保存到数据库：

public function testDatabase()
{
$user = factory("App\User")->create();
// Use model in tests...
}

同样，你也可以使用数组的方式使用create方法将数据写入模型

$user = factory('App\User')->create([
'name' => 'abigail',
]);

添加关联至模型

你甚至可以保存多个模型到数据库上。在本例中，我们还会增加关联至我们所创建的模型。当使用create方法创建多个模型时，它会返回一个Eloquent集合实例，让你能使用集合提供的便利方法，例如each方法：
$users = factory('App\User', 3)
->create()
->each(function ($u) {
$u->posts()->save（factory('App\Posts')->make);
});

模拟
模拟事件
如果你大量地使用lumen的事件系统，你可能会希望在测试停止或者模拟某些事件。例如，如果你在测试你的注册功能，你可能不希望所有的UserRegistered事件被触发，因为它们会触发“欢迎”邮件的发送。

lumen提供了简单的expectsEvents方法，以验证预期的事件有没有被运行，可防止该事件的任何处理进程被进行：
expectsEvents('App\Events\UserRegistered');
//测试用户注册功能...
}
}

如果你想阻止所有的事件处理程序运行，你可以使用withoutEvents方法：

withoutEvents();
//Test user registraction code。。。
}
}

模拟任务

有时你可能希望当请求发送至应用程序时，简单地对控制器所派送的任务进行测试。这么做能够让你隔离测试路由或者控制器，设置除了任务以外的逻辑。当然，在此之后你也可以在一个单独的测试案例中测试该任务。

lumen提供了一个简便的expectsJob方法，以验证预期的任务有没有被派送，但任务本身不会被运行：

expectsJobs('App\Jobs\PurchasePodcast');
//测试购买博客代码...
}
}

注意：该方法只检测通过全局猪手函数dispatch或者路由或控制器中的$this->dispatch方法派送的任务。它并不会检测被直接发送到Queue::push的任务。

模拟facades

在测试时，经常需要模拟对lumen facade的调用。例如，考虑如下控制器的操作：
once()
->with('key')
->andReturn('value');

$this->get('/users');
}
}

注意：你不应该模拟Request门面。应该在测试时使用如call及post这样的HTTP辅助函数来传递你想要的数据。

# 数据验证 #

## 简介 ##

lumen提供了数种不同的方法来验证传入应用程序的数据。默认情况下，lumen的基本控制器类使用名为ProvidesConvenienceMethods的trait，其提供了一种便捷的方法来使用各种强大的验证规则验证传入的HTTP请求。

一般来说，lumen中的数据验证与laravel中的数据验证并无多大区别，因此你应该查过完整的laravel数据验证文档以熟悉其使用；不过，它们之间也存在少许重要的差异。

# 与laravel的差异 #

## 表单请求 ##

lumen不支持表单请求。如果想使用表单请求，则赢使用完整的laravel框架。

$this->validate方法

在lumen中可用的$this->validate辅助方法将始终返回带有相关错误消息的json响应。而该方法的laravel版本，如果请求不是ajax请求，返回的则是重定向响应。由于lumen是无状态的，且不支持会话，所以闪存错误信息在会话中是不可能的。如果想要使用重定向及闪存错误数据，应该使用完整的laravel框架。

与laravel不同的是，lumen支持在Route闭包中访问validate方法：

use Illuminate\Http\Request;

$router->post('/user', function (Request $request) {
$this->validate($request, [
'name' => 'required',
'email' => 'required|email|unique:users',
]);

//存储用户
});

当然，你可以*地使用Validator::make facade方法手动创建验证器实例，就像在laravel中一样。

exists和unique规则

如果想要使用exists或者unique验证规则，则应该在bootstrap/app.php文件中取消$app->withEloquent()方法调用的注释。

视图变量$errors

lumen不支持session，因此在laravel中每个视图都可用的$errors视图变量在lumen中式不可用的。如果验证失败，那么$this->validate辅助方法会抛出Illuminate\ValidationException异常，期中嵌入了包含所有相关错误消息的json响应，如果你并非只构建仅发送json响应的无状态api，则应使用完整的laravel框架。tongzhuo_examination_db