lumen 框架中文文档 Word版本

LUMEN

jiangliqing MICROSOFTchina.suzhou

介绍 (6)

什么是 Lumen? (6)

在什么时候使用 Lumen? (6)

Lumen 的限制 (6)

Lumen 包含了哪些 Laravel 的功能 (7)

安装 (8)

安装 Composer (8)

安装 Lumen (8)

环境需求 (8)

配置信息 (9)

优雅链接 (9)

配置 (10)

介绍 (10)

安装后的配置 (10)

配置文件 (10)

优雅链接 (11)

HTTP 路由 (12)

基础路由 (12)

路由参数 (13)

命名路由 (13)

路由群组 (13)

CSRF 保护 (14)

请求方法欺骗 (15)

抛出 404 错误 (16)

HTTP 中间件 (17)

简介 (17)

建立中间件 (17)

注册中间件 (19)

可终止中间件 (19)

HTTP 控制器 (21)

介绍 (21)

基础控制器 (21)

控制器中间件 (22)

依赖注入和控制器 (22)

HTTP 请求 (25)

获取请求实例 (25)

取得输入数据 (26)

旧输入数据 (27)

Cookies (28)

上传文件 (29)

其他的请求信息 (30)

HTTP 响应 (31)

基础响应 (31)

重定向 (31)

其他响应 (33)

视图 (View) (34)

基本用法 (34)

服务提供者 (36)

简介 (36)

基本提供者例子 (36)

注册提供者 (37)

服务容器 (38)

介绍 (38)

基本用法 (38)

将接口绑定到实现 (40)

上下文绑定 (40)

标签 (40)

容器事件 (41)

缓存 (42)

配置 (42)

基础使用 (42)

数据库使用基础 (44)

配置 (44)

基础使用 (44)

Migrations (45)

加密 (46)

介绍 (46)

基本用法 (46)

错误和记录 (47)

配置 (47)

错误处理 (47)

HTTP 异常 (48)

日志 (48)

事件 (50)

基本用法 (50)

事件处理队列 (51)

文件系统 / 云存储 (53)

简介 (53)

配置文件 (53)

基本用法 (53)

辅助方法 (56)

数组 (56)

路径 (60)

字串 (60)

网址 (63)

其他 (64)

分页 (65)

配置 (65)

使用 (65)

追加分页链接 (66)

转换至 JSON (67)

Queues (68)

设置 (68)

基本用法 (69)

更多调度的方法 (71)

Queueing Closures (71)

执行一个队列监听 (72)

常驻队列处理器 (73)

已失败的工作 (74)

会话 (76)

配置 (76)

使用 (76)

暂存数据（Flash Data） (78)

数据库 Sessions (78)

Session 驱动 (78)

Templates (79)

Blade 模板 (79)

其他 Blade 控制语法结构 (80)

测试 (83)

介绍 (83)

定义并执行测试 (83)

测试环境 (83)

从测试调用路由 (84)

模拟 Facades (84)

框架 Assertions (85)

辅助方法 (87)

重置应用程序 (87)

表单验证 (88)

基本用法 (88)

路由 / 控制器验证 (90)

使用错误信息 (92)

错误信息&视图 (94)

可用验证规则 (95)

添加条件验证规则 (101)

自定义错误信息 (103)

自定义验证规则 (105)

介绍

什么是 Lumen?

Lumen 是一个由 Laravel 元件搭建而成的微框架, 由 Laravel 官方维护. Lumen 为速度而生, 是当前最快的PHP 框架之一, 甚至比类似的微框架Silex 速度还要快.

Lumen 比其他微框架的优点是, 构建在 Laravel 之上, 使其具备 Laravel 强大的功能, 如路由, 依赖注入, Eloquent ORM, 数据库迁移管理, 队列和计划任务等.

Laravel 本来就是一个功能齐全, 速度飞快的框架, 但是 Lumen 因为去除了很多 Laravel 的配置和可自定

义的选项, 速度越加飞快, 毫秒必争.

飞快的速度, 再加上 Laravel 非常方便的功能, 使用 Lumen 开发应用会是非常愉悦的体验.

在什么时候使用 Lumen?

Lumen 专为微服务或者 API 设计, 举个例子, 如果你的应用里面有部分业务逻辑的请求频率比较高, 就可以单独把这部分业务逻辑拿出来, 使用 Lumen 来构建一个小 App.

因为 Lumen 是对 Laravel 优化了框架的加载机制, 所以 Lumen 对资源的要求少很多.

当然, 你可以使用队列系统与你的主 Laravel 应用进行交互. Laravel 和 Lumen 从一开始就是设计成能一起很好的工作, 并且, 配合使用, 允许你构架一个强大的, 以微服务为驱动的应用程序.

Lumen 同时也非常适用于构建 API 接口, 此类型的应用通常情况下不需要具备全栈框架的所有功能, 如HTTP 会话管理, Cookies, 和模版系统.

Lumen 的限制

因为对框架的加载进行了优化, 去除灵活性来换取速度, 所以 Lumen 的可自定义性不是很强, 一些专为Laravel 开发的扩展包可能无法使用, 如开发者工具条, CMS 系统等.

Lumen 没有使用 Symfony 的路由模块, 而是采用了速度更加快的nikic/fast-route. 如果你需要使用Symfony 的路由功能, 如子域名等高级路由功能, Lumen 可能不适合你, 建议使用功能更加齐全的 Laravel.

如果你真的选择了全栈框架, 请放心使用, 构建在 Laravel 上的应用程序能处理每天 15,000,000 以上的请求, 没什么可担忧的.

Lumen 包含了哪些 Laravel 的功能

Lumen 包含了大部分的 Laravel 全栈框架的功能:

?Blade 模版引擎

?Caching 缓存系统

?Command Scheduler 计划任务

?Controllers 控制器

?Eloquent ORM 数据库操作

?Error Handling 错误处理

?Database Abstraction 数据库抽象层

?Dependency Injection 依赖注入

?Logging 日志系统

?Queued Jobs 队列系统

Lumen 独特的初始化机制, 使其在功能强大的同时, 具备了高性能, 是构建微服务架构应用的绝佳方案.

请随意查阅各个功能对应的文档.

安装

安装 Composer

Lumen 使用 Composer 来管理依赖扩展包, 所以, 在使用 Lumen 之前, 你需要先安装 Composer.

安装 Lumen

通过 Lumen 命令安装

首先, 使用下面命令下载 Lumen 命令:

composer globalrequire"laravel/lumen-installer=~1.0"

请确定把~/.composer/vendor/bin路径放置于您的 PATH 里，这样 Lumen 执行文件就会存在你的系统。

一旦安装完成后，就可以使用lumen new命令建立一份全新安装的 Lumen 应用，例如：laravel new service将会在当前目录下建立一个名为 service 的目录，此目录里面存放着全新安装的 Lumen 相关代码，此方法跟其他方法不一样的地方在于会提前安装好所有相关代码，不需要再通过 composer install 安装相关依赖，速度会快许多。

lumen newservice

通过 Composer 创建项目命令

你一样可以通过 Composer 在命令行执行 create-project 来安装 Lumen:

composer create-project laravel/lumen --prefer-dist

环境需求

Lumen 框架有一些系统上的需求：

?PHP >= 5.4

?Mcrypt PHP 扩展

?OpenSSL PHP 扩展

?Mbstring PHP 扩展

?Tokenizer PHP 扩展

配置信息

Lumen 几乎不需多余的配置就可以马上使用。你可以马上着手开发！然而，你可以查看其他的文档, 如下:

权限

Lumen 框架有一个目录需要额外配置权限: storage目录要让服务器有写入的权限。

优雅链接

Apache

Lumen 框架通过 public/.htaccess 文件来让网址中不需要 index.php。如果你的网页服务器是使用 Apache 的话，请确认是否有开启 mod_rewrite 模块。

假设 Laravel 附带的 .htaccess 文件在 Apache 无法生效的话，请尝试下面的方法：

Options +FollowSymLinks

RewriteEngine On

RewriteCond %{REQUEST_FILENAME}!-d

RewriteCond %{REQUEST_FILENAME}!-f

RewriteRule ^ index.php [L]

Nginx

Nginx上，在配置中增加下面的配置，就可以使用「优雅链接」了:

location /{

try_files $uri$uri//index.php?$query_string;

}

当然，如果你使用Homestead的话，优雅链接会自动的帮你配置完成。

配置

介绍

与 Laravel 不同的是, Lumen 只使用单一的.env配置文件, 你阅读下.env.example文件, 看下有哪些选项需要配置.

安装后的配置

Lumen 基本上不需要配置, 但是, 安装后的第一件事情是在.env文件里面设置你的APP_KEY, 此值应该为随机的 32 位字符串.

你可以查看其他的文档, 如下:

配置文件

默认情况下, Lumen 使用单一的.env文件来配置你的应用, 然而, 你也可以使用Laravel 风格的配置方法.

只需要把vendor/laravel/lumen/config文件夹下对应的配置文件复制到根目录下的config文件里面就行.

使用这种方法, 能有更多的配置灵活度.

自定义配置文件

你可以创建自定义的配置文件, 并使用$app->configure()方法进行加载.

举个栗子, 把自定义配置文件放置于config/options.php, 可以这样加载:

$app->configure('options');

优雅链接

Apache

Lumen 框架通过 public/.htaccess 文件来让网址中不需要 index.php。如果你的网页服务器是使用 Apache 的话，请确认是否有开启 mod_rewrite 模块。

假设 Laravel 附带的 .htaccess 文件在 Apache 无法生效的话，请尝试下面的方法：

Options +FollowSymLinks

RewriteEngine On

RewriteCond %{REQUEST_FILENAME}!-d

RewriteCond %{REQUEST_FILENAME}!-f

RewriteRule ^ index.php [L]

Nginx

Nginx上，在配置中增加下面的配置，就可以使用「优雅链接」了:

location /{

try_files $uri$uri//index.php?$query_string;

}

当然，如果你使用Homestead的话，优雅链接会自动的帮你配置完成。

HTTP 路由

基础路由

您将在app/Http/routes.php中定义应用中的大多数路由，这个文件被bootstrap/app.php加载。就如Laravel 一样, 大部分路由只需要接受一个 URI 和一个闭包(Closure) 参数：

基本的 GET 路由

$app->get('/',function(){

return'Hello World';

});

其他基础路由

$app->post('foo/bar',function(){

return'Hello World';

});

$app->patch('foo/bar',function(){

//

});

$app->put('foo/bar',function(){

//

});

$app->delete('foo/bar',function(){

//

});

你可以使用url帮助函数进行 URL 生成:

$url=url('foo');

把请求导向控制器

路由参数

你可以从 URL 中抓取你想要的参数.

基本路由参数

$app->get('user/{id}',function($id){

return'User '.$id;

});

正则表达式约束

$app->get('user/{name:[A-Za-z]+}',function($name){

//

});

命名路由

命名路由让你更方便于产生 URL 与重定向特定路由。您可以用 as 的数组键值指定名称给路由：

$app->get('user/profile',['as'=>'profile',function(){

//

}]);

也可以为控制器动作指定路由名称：

$app->get('user/profile',[

'as'=>'profile','uses'=>'UserController@showProfile'

]);

现在你可以使用路由名称产生 URL 或进行重定向：

$url=route('profile');

$redirect=redirect()->route('profile');

路由群组

有时候, 你想对好几个路由进行统一逻辑处理, 如中间件, 你可以使用路由群组功能.

中间件

中间件会对路由群组里面的路由进行作用, 使用参数middleware进行设定, 可以设定多个中间件, 请注意中间件的顺序是执行的顺序.

$app->group(['middleware'=>'foo|bar'],function($app)

{

$app->get('/',function(){

// Uses Foo & Bar Middleware

});

$app->get('user/profile',function(){

// Uses Foo & Bar Middleware

});

});

命名空间

您一样可以在 group 属性数组中使用namespace参数，指定在这群组中控制器的命名空间：

$app->group(['namespace'=>'Admin'],function(){

// Controllers Within The "App\Http\Controllers\Admin" Namespace

});

CSRF 保护

Lumen 提供简易的方法，让您可以保护您的应用程序不受到 CSRF (跨网站请求伪造) 攻击。跨网站请求伪造是一种恶意的攻击，借以代表经过身份验证的用户执行未经授权的命令。

Lumen 会自动在每一位用户的 session 中放置随机的 token ，这个 token 将被用来确保经过验证的用户是实际发出请求至应用程序的用户：

插入 CSRF Token 到表单

当然也可以在Blade 模板引擎使用：

您不需要手动验证在 POST 、PUT 、DELETE 请求的 CSRF token 。如果你在 bootstrap/app.php 文件里面开启的话, Laravel\Lumen\Http\Middleware\VerifyCsrfToken HTTP 中间件 将保存在 session 中的请求输入的 token 配对来验证 token 。

X-CSRF-TOKEN 除了寻找 CSRF token 作为「POST 」参数，中间件也检查 X-XSRF-TOKEN 请求头，比如，你可以把 token 存放在 meta 标签中, 然后使用 jQuery 将它加入到所有的请求头中：

$.ajaxSetup ({

headers :{

'X-CSRF-TOKEN': $('meta[name="csrf-token"]').attr ('content')

}

});

现在所有的 AJAX 请求会自动加入 CSRF token ：

$.ajax ({

url :"/foo/bar",

})

X-XSRF-TOKEN

Lumen 也在 cookie 中存放了名为 XSRF-TOKEN 的 CSRF token 。你可以使用这个 cookie 值来设

置X-XSRF-TOKEN 请求头。一些 Javascript 框架，比如 Angular ，会自动设置这个值。 请求方法欺骗

HTML 表单没有支持 PUT 、PATCH 或 DELETE 请求。所以当定义 PUT 、PATCH 以及 DELETE 路由并在 HTML 表单中被调用的时候，您将需要添加隐藏 _method 字段在表单中。

发送的 _method 字段对应的值会被当做 HTTP 请求方法。举例来说：

抛出 404 错误

这里有两种方法从路由手动触发 404 错误。

首先，您可以使用abort辅助函数：

abort(404);

abort辅助函数只是简单抛出带有特定状态代码的

Symfony\Component\HttpFoundation\Exception\HttpException异常。

第二，您可以手动抛出Symfony\Component\HttpKernel\Exception\NotFoundHttpException的实体。

有关如何处理404 异常状况和自定响应的更多信息，可以参考错误章节内的文档。

HTTP 中间件

简介

HTTP 中间件提供一个方便的机制来过滤进入应用程序的 HTTP 请求，例如，Lumen 默认包含了一个中间件来检验用户身份验证，如果用户没有经过身份验证，中间件会将用户导向登录页面，然而，如果用户通过身份验证，中间件将会允许这个请求进一步继续前进。

当然，除了身份验证之外，中间件也可以被用来执行各式各样的任务，CORS 中间件负责替所有即将离开程序的响应加入适当的响应头，一个日志中间件可以记录所有传入应用程序的请求。 Lumen 框架已经内置一些中间件，包括维护、身份验证、CSRF 保护，等等。所有的中间件都位于app/Http/Middleware目录内。

建立中间件

要建立一个新的中间件，只需要创建一个类, 并在类里面创建方法:

publicfunction handle($request,$next)

{

return$next($request);

}

举个例子, 在这个中间件内我们只允许年龄大于 200 的才能访问路由，否则，我们会将用户重新导向「home」的 URI 。

class OldMiddleware{

/**

* Run the request filter.

*

* @param \Illuminate\Http\Request $request

* @param \Closure $next

* @return mixed

*/

publicfunction handle($request, Closure $next)

{

if($request->input('age')<200){

return redirect('home');

}

return$next($request);

}

}

如你所见，若是年龄小于200，中间件将会返回 HTTP 重定向给客户端，否则，请求将会进一步传递到应用程序。只需调用带有$request的$next方法，即可将请求传递到更深层的应用程序(允许跳过中间件)。

HTTP 请求在实际碰触到应用程序之前，最好是可以层层通过许多中间件，每一层都可以对请求进行检查，甚至是完全拒绝请求。

Before / After 中间件

请求前后执行顺序, 指定某个中间件取决于这个中间件自身。这个中间件可以执行在请求前执行一些前置操作, 注意BeforeMiddleware：

class BeforeMiddleware implements Middleware{

publicfunction handle($request, Closure $next)

{

// Perform action

return$next($request);

}

}

然后，这个中间件也可以在请求后执行一些后置操作, 注意AfterMiddleware：

class AfterMiddleware implements Middleware{

publicfunction handle($request, Closure $next)

{

$response=$next($request);

// Perform action

return$response;

}

}

注册中间件

全局中间件

若是希望中间件被所有的 HTTP 请求给执行，只要将中间件的类加入到bootstrap/app.php的

$app->middleware()调用里面.

指派中间件给路由

如果你想为指定的路由加上中间件, 你需要先在bootstrap/app.php设置键值, 默认情况

下,$app->routeMiddleware()方法定义了应用的中间件, 想添加自定义的中间件, 只需要做如下:

$app->routeMiddleware([

'old'=>'App\Http\Middleware\OldMiddleware',

]);

一旦你设定了中间件, 你可以使用 middleware键在路由的选项参数里面, 见下面:

$app->get('admin/profile',['middleware'=>'old',function(){

//

}]);

可终止中间件

有些时候中间件需要在 HTTP 响应已被发送到用户端之后才执行，例如，Laravel 内置的「session」中间件，保存 session 数据是在响应已被发送到用户端之后才执行。为了做到这一点，你需要定义中间件为「可终止的」。

use Illuminate\Contracts\Routing\TerminableMiddleware;

class StartSession implements TerminableMiddleware{

publicfunction handle($request,$next)

{

return$next($request);

}

publicfunction terminate($request,$response)

{

// Store the session data...

}

}

如你所见，除了定义handle方法之外，TerminableMiddleware定义一个terminate方法。这个方法接收请求和响应。一旦定义了 terminable 中间件，你需要将它增加到 HTTP kernel 文件的全局中间件清单列表中。

本文来源：https://www.bwwdw.com/article/tcce.html