README

Rhino 是一个 php 微框架，用于构建快速且可靠的 http 服务、API，并通过易于配置的基于 php 的路由服务来提供静态内容。

在 Packagist 上查找此项目：php-rhino

内容

1. 快速开始
2. 功能教程
3. 安装
4. API 文档

快速开始

要快速开始，只需在您的应用程序的 index.php 文件中包含此框架基础或 lib/ 文件夹中的 rhino.php 文件之一。

然后，您可以调用导出的 rhino() 函数来实例化此框架的主要应用程序，并将返回值分配给一个变量 - 通常命名为 $app。

接下来，使用应用程序对象的实例方法注册中间件和路由处理器。 use() 在此应用程序上注册中间件，而像 get()、post() 和 delete() 这样的方法注册路由处理器，这将导致向客户端返回最终的 http 响应。

最后，必须在所有组件都注册到应用程序对象上之后调用 start() 方法。

<?php

require_once (dirname(__FILE__) . "/lib/rhino.php");

$app = rhino();

$app->use($jsonparse);

$app->post('/', function($req, $res) {
  $name = $req->body['name'];
  $res->send("Hello $name");
});

$app->get('/', function($req, $res) {
  $res->send("Hello, World!");
});

$app->get('/:name', function($req, $res) {
  $res->send("Hello " . $req->params['name']);
});

$app->start();

要立即测试您的应用程序，请在应用程序的根文件夹中打开终端，并输入以下命令以启动 php 开发服务器

php -S localhost:5001 .

打开您的浏览器，转到 localhost:5001/Peter 以查看结果。如果您想测试已注册的 POST 路由，您可以使用外部图形工具（如 Postman）或简单地在终端中使用以下命令通过 cURL 进行测试

echo '{ "name": "Charlie" }' | curl -d @- https://:5001/ --header "Content-Type:application/json"

查看 examples/ 文件夹以获取更多高级的示例应用程序。

功能教程

资源路由中的正则表达式

大多数正则表达式都适用于路由处理器。

<?php

// trigger this route handler as a middleware for all routes starting
// with `/api/`.
$app->use('/api/*', function($req, $res) {
});

// trigger this route handler for any number entered after `/api/`
$app->get('/api/[0-9]+', function($req, $res) {
});

$app->get('/api/*/name/[A-Za-z ]+', function($req, $res) {
});

查询参数

查询参数自动转换为键值对，并存储在请求对象的 query 属性中。

<?php

$app->get('/', function($req, $res) {
  $orderBy = $req->query['orderBy'];
  $offset = $req->query['offset'];
  $limit = $req->query['limit'];
});

路由参数

路由参数在资源路由中用冒号 : 定义。路由参数和客户端在路由参数位置输入的字符串将被转换为键值对，并存储在请求对象的 params 属性中。

<?php

$app->get('/api/users/:id', function($req, $res) {
  $res->send("Retrieving data for user with id: {$req->params['id']}");
});

$app->get('/api/users/:lastname/:firstname', function($req, $res) {
  $lastName = $req->params['lastname'];
  $firstName = $req->params['firstname'];

  $res->send("Loading data for $firstName $lastName");
}

次要路由器

可以从原始应用程序 $app 实例实例化额外的路由器。这些路由器拥有与应用程序实例大多数相同的方法。次要路由器可以挂载在其他路由器或主应用程序上的自定义路径。

次要路由器用于将不同的资源分段到它们自己的文件中，并在以后将它们挂载到公共 URL 资源路径上。

// in users.php
$router = $app->router();

$router->get('/', function($req, $res) {
  // do stuff
});

$router->get('/:id', function($req, $res) {
  // do stuff
});

// in index.php
require_once (dirname(__file__) . '/routes/users.php');

$app->use('/api/users/', $router);

// routes registered on $router are now available on /api/users/...

中间件

中间件是作为请求-响应周期的一部分执行的功能。 use() 方法在给定路径上注册中间件函数。这些中间件函数的定义方式与常规路由处理器类似，但它们在执行完成后不会自动终止请求-响应周期。

<?php
// this middleware is used to check whether the client has the required
// authentication and is executed on all routes of the 'users' resource.

$app->use('/api/users/*', function($req, $res) {
  if (!$req->get('X-Token')) {
    $res->status(401)->send('Access denied. No token provided.');
    $res->end();
  }

  // authenticate some more
});

内置请求验证

要使用内置验证器，您必须在主 index.php 文件中导入 /lib/addons/validation.php。

安装

安装此框架的推荐方法是，将 lib/ 文件夹放置在项目的根目录或 vendor/ 文件夹中，然后在应用程序的主要 index.php 文件中包含主 rhino.php 文件。就这样 - 您就可以开始使用了。

<?php

require_once (dirname(__FILE__) . "/lib/rhino.php");

API 文档

• rhino()
• 应用程序
  • router()
  • start()
• 路由器
  • get()
  • post()
  • put()
  • delete()
  • all()
  • use()
• Request
  • app
  • headers
  • get()
  • body
  • params
  • queryString
  • query
  • originalUrl
  • url
  • method
  • hostname
  • port
• Response
  • app
  • set()
  • send()
  • json()
  • end()
  • status()
  • sendStatus()
  • type()

$jsonparse

rhino()

生成整个应用程序中使用的请求和响应对象，并返回此框架主Application类的新的实例。

@param $options Array - optional parameter mapping of settings (see api docs)
@return Application

应用程序

Application是一个可以注册中间件和路由处理程序，以及挂载其他路由的router。它继承自Router类中的所有方法和属性。

Application类继承了两项额外的功能。一个是通过迭代此应用程序的路由队列来启动应用程序，另一个是生成一个新的router。

start(): void

启动此应用程序。

遍历所有已注册的路由队列集合，匹配路由并执行中间件和响应回调函数。

router(): Router

返回一个新的router。

@return {Router} new router instance generated using this application.

路由器

Router作为一个集合，可以注册路由处理程序、中间件和其他router。

注册到这个router的对象存储在$queue集合中。

在找到所有匹配的路由或请求响应周期终止之前，主集合会遍历这个集合。

此类提供了许多作为实例方法的函数，用于将路由注册到该router。

使用.use()、.get()、.post()、.put()、.delete()和.all()方法将路由注册到router。请参阅API文档中的示例。

use(…$args): void

根据提供的数据类型，将提供的参数注册到该router的路由队列中，作为中间件或router。

可选地可以提供一个URL字符串，以指定目标路由或资源方向。如果没有提供URL字符串，则默认假设为根位置的路由。

@param $args Array - Array of a url string, closure functions or Router.

post, get, put, delete(…$args): void

通过调用`registerRouteHandler()`函数并使用适当的HTTP方法，将提供的参数注册为中间件。

@param $args Array - Array of a url string and closure functions.

all(…$args): void

通过调用`registerRouteHandler()`函数并使用适当的HTTP方法，将提供的参数注册为中间件。

@param $args Array - Array of a url string and closure functions.

Request

Request类包含有关接收到的HTTP请求的所有相关信息，并提供了一个方便地检索HTTP头部值的函数。

$app

此Request所属的Application实例的引用。

$headers

此请求发送的所有HTTP头部的ArrayMap。

get($header): string

返回指定的HTTP请求头部字段。参数头部名称和存储的头部键不区分大小写。

@param $header {string} - name of a http header.
@return {string} return the value of a specific header or null if not set.

$body

此请求的有效负载或请求体的原始内容，表示为字符串。可以通过在所需路由上注册内置的$jsonparse中间件自动将请求体解析为JSON。

$params

路由参数到参数值的映射。

$queryString

包含此请求发送的查询字符串。

$query

查询字符串参数到查询字符串参数值的映射。

$originalUrl

与此Request一起使用的整个原始接收URL。不要修改此URL。

$url

原始URL的副本。此字段可以被程序员或第三方中间件/插件修改并用于应用程序内部路由。

$method

用于发送此请求的HTTP方法。

$hostname

此Request指向的主机名。

$port

此Request指向的端口号。

Response

Response类提供了设置HTTP响应代码、写入HTTP响应流以及通过结束HTTP响应退出请求响应周期的有用方法。

$app

此Request所属的Application实例的引用。

set($header, $value): Response

将HTTP响应头部设置为给定值。此函数在写入HTTP响应体后不能使用。

@param $header {string} http header
@param $value {string} http header value
@return Response - a reference to this response object to allow chaining.

send($body): Response

将给定的字符串写入HTTP响应流。

@param $body {string} text to write to the http response body.
@return Response - a reference to this response object to allow chaining.

json($body): Response

自动将对象、数组或映射转换为JSON格式的字符串，设置HTTP头部的'Content-Type'为'application/json'，并将字符串写入HTTP响应流。

@param $body object - object, array or map
@return Response - a reference to this Response object to allow chaining.

end(): void

通过抛出新的EndResponse异常来结束HTTP响应。当调用此函数时，HTTP输出流会关闭。

status($code): Response

将HTTP状态码设置为指定的值。

@param $code {int} http status code
@return Response - a reference to this response object to allow chaining.

sendStatus($code): Response

将HTTP状态码设置为指定的值，并将常规状态消息写入响应体。

@param $code {int} http status code
@return Response - a reference to this response object to allow chaining.