Flight是什么?

Flight是一个快速,简易,可扩展的PHP框架。Flight能使你快速和轻松地创建RESTful Web应用。

  1. require 'flight/Flight.php';
  2. Flight::route('/', function(){
  3. echo 'hello world!';
  4. });
  5. Flight::start();

需求

Flight需要PHP 5.3或更高版本。

License

Flight is released under the MIT license.

安装

1.框架下载

如果你在使用Composer,你可以运行如下命令:

  1. composer require mikecao/flight

或者你可以直接下载,之后将Flight框架文件放入你的web目录中。

2. 配置你的web服务器

对于Apache服务器,编辑你的.htaccess文件添加如下内容:

  1. RewriteEngine On
  2. RewriteCond %{REQUEST_FILENAME} !-f
  3. RewriteCond %{REQUEST_FILENAME} !-d
  4. RewriteRule ^(.*)$ index.php [QSA,L]

对于Nginx服务器,添加如下内容到你的server声明中:

  1. server {
  2. location / {
  3. try_files $uri $uri/ /index.php;
  4. }
  5. }

3. 创建你的index.php文件(示例)

首先引入这个框架。

  1. require 'flight/Flight.php';

接着定义一个路由并且注册一个函数去处理对应请求。

  1. Flight::route('/', function(){
  2. echo 'hello world!';
  3. });

最后,启动框架。

  1. Flight::start();

路由

Flight中的路由是指将一个URL模式(pattern)匹配到一个回调函数中。

  1. Flight::route('/', function(){
  2. echo 'hello world!';
  3. });

只要能被调用,都可以当做回调函数。所以可以使用一个普通的函数当做回调:

  1. function hello(){
  2. echo 'hello world!';
  3. }
  4. Flight::route('/', 'hello');

也可以是某一个类的方法:

  1. class Greeting {
  2. public static function hello() {
  3. echo 'hello world!';
  4. }
  5. }
  6. Flight::route('/', array('Greeting','hello'));

如果定义了多个路由,路由依照定义它们的顺序进行匹配。第一个匹配到该请求的路由将被调用。

HTTP METHOD路由

在默认不指定的情况下,路由会对相应请求的所有Method(例如:GET POST PUT DELETE…)进行匹配。你可以通过在URL前面加一个方法标识符的方式来响应指定的Method。

  1. Flight::route('GET /', function(){
  2. echo 'I received a GET request.';
  3. });
  4. Flight::route('POST /', function(){
  5. echo 'I received a POST request.';
  6. });

你还可以使用|分隔符来映射多个Method到同一个回调中。

  1. Flight::route('GET|POST /', function(){
  2. echo 'I received either a GET or a POST request.';
  3. });

正则表达式

在路由中你可以使用正则表达式:

  1. Flight::route('/user/[0-9]+', function(){
  2. // 这个将匹配到 /user/1234
  3. });

命名参数

你可以在路由中指定命名参数,它们会被传递到你的回调函数里。

  1. Flight::route('/@name/@id', function($name, $id){
  2. echo "hello, $name ($id)!";
  3. });

你也可以通过使用:分隔符在命名变量中引入正则表达式

  1. Flight::route('/@name/@id:[0-9]{3}', function($name, $id){
  2. // 这个将匹配到 /bob/123
  3. // 但是不会匹配到 /bob/12345
  4. });

可选参数

你可以通过将URL段(segments)包在括号里的方式来指定哪些命名参数是可选的。

  1. Flight::route('/blog(/@year(/@month(/@day)))', function($year, $month, $day){
  2. // 它将匹配如下URLS:
  3. // /blog/2012/12/10
  4. // /blog/2012/12
  5. // /blog/2012
  6. // /blog
  7. });

任何没有被匹配到的可选参数将以NULL值传入。

通配符

匹配只发生在单独的URL段(segments)。如果你想匹配多段,可以使用*通配符。

  1. Flight::route('/blog/*', function(){
  2. // 这个将匹配到 /blog/2000/02/01
  3. });

要将所有的请求路由到单一的回调上,你可以这么做:

  1. Flight::route('*', function(){
  2. // Do something
  3. });

路由的传递

当从一个被匹配到的回调函数中返回true时,路由功能将继续执行,传递到下一个能匹配的路由中。

  1. Flight::route('/user/@name', function($name){
  2. // 检查某些条件
  3. if ($name != "Bob") {
  4. // 延续到下一个路由
  5. return true;
  6. }
  7. });
  8. Flight::route('/user/*', function(){
  9. // 这里会被调用到
  10. });

路由信息

如果你想检视匹配到的路由信息,可以请求将路由对象传递到你的回调函数中:你需要把
route方法的第三个参数设置成true。这个路由对象总是会作为最后一个参数传入你的回调函数。

  1. Flight::route('/', function($route){
  2. // 匹配到的HTTP方法的数组
  3. $route->methods;
  4. // 命名参数数组
  5. $route->params;
  6. // 匹配的正则表达式
  7. $route->regex;
  8. // Contains the contents of any '*' used in the URL pattern
  9. $route->splat;
  10. }, true);

扩展

Fligth被设计成一个可扩展的框架。这个框架带来了一系列的默认方法和组件,但是它允许你
映射你自己的方法,注册你自己的类,甚至可以重写已有的类和方法。

方法的映射

你可以使用map函数去映射你自定义的方法:

  1. // 映射你自己的方法
  2. Flight::map('hello', function($name){
  3. echo "hello $name!";
  4. });
  5. // 调用你的自定义方法
  6. Flight::hello('Bob');

类的注册

你可以使用register函数去注册你自己的类:

  1. // 注册你定义的类
  2. Flight::register('user', 'User');
  3. // 得到你定义的类的一个实例
  4. $user = Flight::user();

register方法允许你向类的构造函数传递参数。所以当你加载自定义类的时候,它将会
预初始化(pre-initialized)。你可以通过一个追加的数组来传递定义的构造函数参数。
这是一个加载数据库连接的例子:

  1. // 注册一个带有构造函数参数的类
  2. Flight::register('db', 'PDO', array('mysql:host=localhost;dbname=test','user','pass'));
  3. // 得到你定义的类的一个实例
  4. // 这里将创建一个带有你定义的参数的对象
  5. //
  6. // new PDO('mysql:host=localhost;dbname=test','user','pass');
  7. //
  8. $db = Flight::db();

如果你传递了额外的回调函数参数,它将会在类构造完之后立即执行。这就允许你为这个新对象去
执行任何的安装过程(set up procedures)。这个回调函数会被传递一个参数,就是这个新对象的实例。

  1. // 这个回调函数将会传递到这个被构造的对象中
  2. Flight::register('db', 'PDO', array('mysql:host=localhost;dbname=test','user','pass'), function($db){
  3. $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
  4. });

默认情况下,每次你加载一个类,你会得到一个共享的实例。如果要得到一个类的新实例,
简单的传递一个false参数就行了。

  1. // 类的共享实例
  2. $shared = Flight::db();
  3. // 类的新实例
  4. $new = Flight::db(false);

需要记住的是,被映射的方法优先于被注册的类。如果你用相同的名字将它们都声明了,那么只有
映射的方法会被调用。

重写(Overriding)

Flight允许你按照自己的需要去重写它的默认功能,而不用修改任何框架的代码。

例如,当Flight的路由功能没有匹配到一个URL时,它会调用notFound方法,发出一个通用的
HTTP 404响应。你可以使用map方法去重写这个行为。

  1. Flight::map('notFound', function(){
  2. // 显示自定义的404页面
  3. include 'errors/404.html';
  4. });

Flight也允许你替换这个框架的核心组件。例如你可以将默认的Router类替换成你自定义的类:

  1. // 注册成你自定义的类
  2. Flight::register('router', 'MyRouter');
  3. // When Flight loads the Router instance, it will load your class
  4. // 当Flight加载Router实例时,将会加载到你自定义的类
  5. $myrouter = Flight::router();

然而框架的方法诸如mapregister是不能够被重写的。如果你尝试这么做的话你会得到一个error。

过滤

Flight允许你在方法调用之前和之后去过滤它。框架里没有任何你需要记住的预定义的钩子。你可以
过滤任何被映射的自定义方法和框架中的方法。

一个过滤器函数是像这样的:

  1. function(&$params, &$output) {
  2. // Filter code
  3. }

通过传入的变量,你可以操作输入参数和/或输出参数。

这样做就可以在一个方法运行之前运行一个过滤器:

  1. Flight::before('start', function(&$params, &$output){
  2. // Do something
  3. });

这样做就可以在一个方法运行之后运行一个过滤器:

  1. Flight::after('start', function(&$params, &$output){
  2. // Do something
  3. });

你可以给任何函数添加任意数量的过滤器。它们将按照声明的顺序依次被调用。

这里是一个过滤器处理的例子:

  1. // 映射一个自定义的方法
  2. Flight::map('hello', function($name){
  3. return "Hello, $name!";
  4. });
  5. // 添加一个前置的过滤器
  6. Flight::before('hello', function(&$params, &$output){
  7. // 操作这里的params
  8. $params[0] = 'Fred';
  9. });
  10. // 添加一个后置的过滤器
  11. Flight::after('hello', function(&$params, &$output){
  12. // 操作这里的output
  13. $output .= " Have a nice day!";
  14. });
  15. // 调用这个自定义方法
  16. echo Flight::hello('Bob');

这个将会输出:

  1. Hello Fred! Have a nice day!

如果你定义了多个过滤器,你可以通过在任意一个过滤器函数中返回false来终结这个过滤器链。

  1. Flight::before('start', function(&$params, &$output){
  2. echo 'one';
  3. });
  4. Flight::before('start', function(&$params, &$output){
  5. echo 'two';
  6. // 如下将会终止这个过滤器链
  7. return false;
  8. });
  9. // 这里将不会得到调用
  10. Flight::before('start', function(&$params, &$output){
  11. echo 'three';
  12. });

记住,核心函数诸如mapregister是不能够被过滤的,因为它们是被直接调用而非动态调用的。

变量

Flight允许你定义变量,使得它能在应用内的任何地方被使用。

  1. // 保存你定义的变量
  2. Flight::set('id', 123);
  3. // 在应用的其他地方使用
  4. $id = Flight::get('id');

去检测一个变量是否被设置了可以这么做:

  1. if (Flight::has('id')) {
  2. // Do something
  3. }

去清除一个变量你可以这么做:

  1. // 清除这个id变量
  2. Flight::clear('id');
  3. // 清除所有的变量
  4. Flight::clear();

Flight框架使用变量的目的还包括了配置。

  1. Flight::set('flight.log_errors', true);

视图

Flight默认提供了一些基础的模板功能。调用带有模板文件和
可选的模板数据的render函数,去显示一个视图模板。

  1. Flight::render('hello.php', array('name' => 'Bob'));

你传进来的模板数据,会被自动的注入到模板当中,并且可以像一个本地变量一样去引用。
模板文件就是简单的PHP文件。如果一个文件名为hello.php的模板文件的内容是这样的:

  1. Hello, '<?php echo $name; ?>'!

输出会是:

  1. Hello, Bob!

你可以使用set函数来手动的设置视图中的变量:

  1. Flight::view()->set('name', 'Bob');

这个name 变量现在在你所有的视图中都是可用的了。所以就可以简化成这样了:

  1. Flight::render('hello');

注意当你在render函数中指定模板名时,你可以去掉这个.php的扩展名。

默认情况下Flight会在views目录下寻找模板文件。你可以通过如下配置的设定来为你的模板
设置另外一个路径。

  1. Flight::set('flight.views.path', '/path/to/views');

布局(Layouts)

对网站来说,拥有一个单独的可交换内容的布局(layout)模板文件是很常见的。要在布局中使用渲染的内容,
你可以给render函数传递一个可选的参数。

  1. Flight::render('header', array('heading' => 'Hello'), 'header_content');
  2. Flight::render('body', array('body' => 'World'), 'body_content');

紧接着你的视图就有了命名为header_contentbody_content的已保存的变量。接下来你就可以
这样渲染你的布局了:

  1. Flight::render('layout', array('title' => 'Home Page'));

如果你的模板文件是这样的:

header.php:

  1. <h1><?php echo $heading; ?></h1>

body.php:

  1. <div><?php echo $body; ?></div>

layout.php:

  1. <html>
  2. <head>
  3. <title><?php echo $title; ?></title>
  4. </head>
  5. <body>
  6. <?php echo $header_content; ?>
  7. <?php echo $body_content; ?>
  8. </body>
  9. </html>

输出会是:

  1. <html>
  2. <head>
  3. <title>Home Page</title>
  4. </head>
  5. <body>
  6. <h1>Hello</h1>
  7. <div>World</div>
  8. </body>
  9. </html>

自定义视图

Flight允许你替换默认的视图引擎,只需简单的注册你自己的视图类即可。这里展示的是在视图中
如何使用Smarty模板引擎:

  1. // 加载Smarty类库
  2. require './Smarty/libs/Smarty.class.php';
  3. // 将Smarty注册成视图类
  4. // 同时传递一个回调函数,在加载过程中配置Smarty
  5. Flight::register('view', 'Smarty', array(), function($smarty){
  6. $smarty->template_dir = './templates/';
  7. $smarty->compile_dir = './templates_c/';
  8. $smarty->config_dir = './config/';
  9. $smarty->cache_dir = './cache/';
  10. });
  11. // 模板中数据的赋值
  12. Flight::view()->assign('name', 'Bob');
  13. // 显示这个模板
  14. Flight::view()->display('hello.tpl');

出于完备性,你还应该重写Flight的默认render方法:

  1. Flight::map('render', function($template, $data){
  2. Flight::view()->assign($data);
  3. Flight::view()->display($template);
  4. });

错误(Error)处理

错误(Errors)和异常(Exceptions)

所有的errors和exceptions都会被Flight捕获,然后传到error方法。该方法默认的行为是
发出一个带有错误信息的通用的HTTP 500 Internal Server Error响应。

出于你自己的需要,你可以重写这个行为:

  1. Flight::map('error', function(Exception $ex){
  2. // 错误处理
  3. echo $ex->getTraceAsString();
  4. });

默认情况下,错误(errors)是不会被记录日志到web服务器的。你可以通过改变配置来允许记录。

  1. Flight::set('flight.log_errors', true);

Not Found

当一个URL没有被找到时,Flight将会调用notFound方法。该方法默认的行为是
发出一个通用的HTTP 404 Not Found响应并带有简单的说明信息。

出于你自己的需要,你可以重写这个行为:

  1. Flight::map('notFound', function(){
  2. // 处理not found
  3. });

重定向(Redirects)

你可以使用redirect方法将当前请求重定向到传入的新URL中。

  1. Flight::redirect('/new/location');

默认情况下Flight会发出一个HTTP 303状态码。你可以选择设置一个自定义的状态码。

  1. Flight::redirect('/new/location', 401);

请求

Flight将HTTP请求封装到一个单独的对象中,你可以这样获取到它:

  1. $request = Flight::request();

request对象提供了如下的属性:

  1. url - 被请求的url
  2. base - The parent subdirectory of the URL
  3. method - 请求的Method (GET, POST, PUT, DELETE)
  4. referrer - 引用(referrer)的 URL
  5. ip - 客户点的IP地址
  6. ajax - 是否是一个ajax请求
  7. scheme - 服务器scheme (http, https)
  8. user_agent - 浏览器信息
  9. type - Content-type
  10. length - Content-length
  11. query - 查询字符串参数(Query string parameters
  12. data - Post数据或者JSON数据
  13. cookies - Cookies数据
  14. files - 上传的文件
  15. secure - Whether the connection is secure
  16. accept - HTTP accept parameters
  17. proxy_ip - 客户端代理ip地址

你可以通过数组或对象的方式来获取query,data,cookiesfiles属性。

也就是说,你可以这样获取到查询字符串参数(query string parameter):

  1. $id = Flight::request()->query['id'];

或者你可以这样做:

  1. $id = Flight::request()->query->id;

请求体原始数据(RAW Request Body)

要获取原始的HTTP请求体数据,举例来说当你正在处理PUT方法的请求时,你可以这么做:

  1. $body = Flight::request()->getBody();

JSON 输入

如果你发送application/json类型的请求并带有数据{"id": 123}时,它将被从data属性中获取到。

  1. $id = Flight::request()->data->id;

HTTP缓存

Flight为HTTP级别的缓存提供了内建的支持。如果满足缓存的条件,Flight将会返回一个
HTTP304 Not Modified响应。当下一次客户端请求相同的资源时,它们会被提示去使用它们
本地的缓存版本。

Last-Modified

你可以使用lastModified方法并传递一个UNIX时间戳去设置一个页面最后被修改的日期和时间。
客户端将继续使用它们的缓存直到last modified的值被改变了。

  1. Flight::route('/news', function(){
  2. Flight::lastModified(1234567890);
  3. echo 'This content will be cached.';
  4. });

ETag

ETag缓存与Last-Modified类似,但你可以对资源指定任意的id。

  1. Flight::route('/news', function(){
  2. Flight::etag('my-unique-id');
  3. echo 'This content will be cached.';
  4. });

需要记住的是,不论调用了lastModified或是etag,都会设置并且检查缓存的值。如果缓存中的值
跟请求的相同,Flight会立即发送一个HTTP 304响应并且停止处理。

停止

你可以通过调用halt方法在任何地方停止这个框架:

  1. Flight::halt();

你也可以指定可选的HTTP状态码和信息:

  1. Flight::halt(200, 'Be right back...');

调用halt将会丢弃在那个点之前的任何的响应内容。如果你想停止这个框架并输出当前的响应,使用stop方法:

  1. Flight::stop();

JSON

Flight对发送JSON和JSONP响应提供了支持。发送一个JSON响应时,你传递的数据将被JSON编码。

  1. Flight::json(array('id' => 123));

对于JSONP请求,你可以选择传递查询参数名(query parameter name)用于定义你的回调函数:

  1. Flight::jsonp(array('id' => 123), 'q');

所以,当使用?q=my_func构造一个GET请求时,你应该会收到这样的输出:

  1. my_func({"id":123});

如果你没有传递查询参数名(query parameter name)的话,它会有一个默认名jsonp

配置

你可以使用set方法去设置配置的值,来自定义Flight的某些行为。

  1. Flight::set('flight.log_errors', true);

下面是所有的可进行设置的配置列表:

  1. flight.base_url - 覆盖该请求的base url。(默认值:null)
  2. flight.handle_errors - 允许Flight处理所有的内部错误。 (默认值:true)
  3. flight.log_errors - web服务器的错误日志文件里记录错误日志。 (默认值:false)
  4. flight.views.path - 包含视图模板文件的目录路径。 (默认值:./views)

框架的方法

Flight框架被设计成易于使用和易于理解的。下面就是这个框架完整的方法集合。它由 是常规静态函数
的核心方法,和被映射的可以被过滤和重写的扩展方法组成。

核心方法

  1. Flight::map($name, $callback) // 创建一个自定的框架方法
  2. Flight::register($name, $class, [$params], [$callback]) //将一个类注册成框架方法
  3. Flight::before($name, $callback) // 添加框架方法的前置过滤器
  4. Flight::after($name, $callback) // 添加框架方法的后置过滤器
  5. Flight::path($path) // 添加类自动加载(autoloading)的路径
  6. Flight::get($key) // 获取某个变量的值
  7. Flight::set($key, $value) // 设置变量的值
  8. Flight::has($key) // 某个变量是否被设值
  9. Flight::clear([$key]) // 清除一个变量
  10. Flight::init() // 初始化框架到默认的设定
  11. Flight::app() // 获取整个应用对象的实例

扩展方法

  1. Flight::start() // 开启框架(接收响应开始工作)
  2. Flight::stop() // 框架停止并且发送返回响应
  3. Flight::halt([$code], [$message]) // 停止框架并返回一个可选的http状态码和信息
  4. Flight::route($pattern, $callback) // 将一个URL匹配到一个回调中
  5. Flight::redirect($url, [$code]) // 重定向到另一个URL
  6. Flight::render($file, [$data], [$key]) // 渲染模板文件
  7. Flight::error($exception) // 发送HTTP 500响应
  8. Flight::notFound() // 发送HTTP 404响应
  9. Flight::etag($id, [$type]) // 运行HTTP Etag缓存
  10. Flight::lastModified($time) // 运行HTTP last modified缓存
  11. Flight::json($data, [$code], [$encode]) // 发送JSON响应
  12. Flight::jsonp($data, [$param], [$code], [$encode]) // 发送JSONP响应

任何通过mapregister添加的自定义方法都可以被过滤。

框架的实例

替代将Flight运行成一个全局的静态类,你可以选择将它运行成一个对象的实例。

  1. require 'flight/autoload.php';
  2. use flight\Engine;
  3. $app = new Engine();
  4. $app->route('/', function(){
  5. echo 'hello world!';
  6. });
  7. $app->start();

也就是取代调用静态方法,你可以调用Engine对象实例里同名的方法。