README

关于

"http-routes" 是一个http路由器，通过url识别路由并通过控制器或回调响应请求。

版权

Jórdan Almeida (开发者)

亮点

易于与MVC架构集成
无依赖
用户友好的URI
中间件
接受可选和必选参数
简单易用

通过Composer安装

composer jordan/http-routes

开始

创建一个用户可以通过您的网站访问的文件。建议创建一个 "index.php"，因为服务器会在访问网站根目录时自动调用它。

在创建的文件中，启动自动加载，然后创建一个文件，该文件将负责启动 "HttpRoutes\Routes" 和 "HttpRoutes\Bootstrap" 的实例。

//index.php
require_once "/vendor/autoload.php";
require_once "foo/bar/arquivo-rotas-exemplo.php";

//arquivo-rotas-exemplo.php
use HttpRoutes\{Route, Bootstrap};
use HttpRoutes\Exception\BootstrapException;

$route = new Route;


//Insira suas rotas aqui


try {
  //Iniciando a aplicação
  $app = new Bootstrap($route, "http:\\url-base-projeto");

} catch (BootstrapException $e) {
  //Erros relacionados à rota
  http_response_code($e->getCode());
  if ($e->getCode() == 404 | $e->getCode() == 405) {
    //Erros causados pelo usuário
    die($e->getMessage());
  } else {
    //Erros internos
    die("Ocorreu um erro inesperado, lamentamos o ocorrido.<br>Detalhes DEBUG: '{$e->getMessage()}'");
  }
}

方法

以下方法的示例将假设您已经完成了上述步骤。所有方法都必须通过 "HttpRoutes\Route" 实例调用。

$route
->method();

$route
->method1()
->method2('foo', 'bar');

路由方法

创建一个路由

要创建一个路由，只需调用 "set" 方法，第一个参数应填写路由的http方法，第二个参数应填写所需的路径。

注意：路径开头和结尾的斜杠将被忽略；http方法名称将被转换为大写。

->set('get', 'foo');

->set('post', '/bar');

注意：此函数返回 "HttpRoutes\Route\RouteMethods" 实例，该类包含每个路由的单独方法。

路由参数

路由可以接受额外的参数，这些参数可以在请求时由用户填写。这些参数被分类为 "必需" 和 "可选"。

参数应写成花括号 "{}"，其中可选参数应前面加上问号 "{?}"。

注意：必需参数可以后面跟着可选参数，但反之则不太适用。请使用推荐顺序。

->set('get', 'foo/{obrigatório}');//Correto

->set('post', 'foo/{obrigatório}/{?opcional}');//Correto

->set('DELETE', 'foo/{?opcional}/{obrigatório}');//Essa sequência não funciona muito bem

->set('GET', 'foo/{?opcional}/');//Correto

传递给路由的参数将自动传递给负责响应请求的方法。有关详细信息，请参阅 "Callback" 和 "Controller" 部分。

命名一个路由

在需要路由在应用程序的多个地方被调用的场景中，命名一个路由可能很有用。从路由名称可以获取其地址，这允许任何对路由的更改都可以在所有调用它的地方获得，而无需手动更改，因为名称保持不变，只有地址可能发生变化。

->name('Nome-da-rota');

获取命名路由

负责从其名称获取路由的方法将在 "controller" 和 "callback" 方法中可用。

此函数期望两个参数。第一个参数应填写路由名称，第二个参数应填写一个布尔值。默认值为 "true"，方法将返回带有基础URL的路由。例如：http://meu-site/rota；如果为 "false"，则方法将仅返回命名路由。例如：/rota。

注意：如果不存在命名路由，将在 "BootstrapException" 中抛出异常，提示未找到与名称对应的路由。

$getUriByName('Nome-da-rota', true); //O método retornará a rota antecedida da url base. ex: http://meu-site/rota
$getUriByName('Nome-da-rota', false); //O método retornará somente a rota nomeada. ex: /rota

回调

“回调”方法期望传入一个匿名函数作为参数。该函数将在成功响应HTTP请求时执行。

传入的匿名函数需要准备接收一个数组作为第一个参数，该数组将由应用程序的核心传递。目前只有一个名为“getUriByName”的函数，它负责从各自的名称获取路由（有关详细信息，请参阅“获取命名路由”主题）。即使在不使用这些函数的情况下，该参数也是必需的。

->callback(function($functions){
  return "Resposta a ser retornada";
});

->callback(function($functions){
  $getUriByName = $functions['getUriByName'];
  return $getUriByName('Nome-da-rota'); 
});

回调和路由参数

为了获取用户在请求时通过URL传递的参数，只需将一个变量作为匿名函数的第二个参数传递，该变量将被填充为一个关联数组（键/值）。键将代表每个参数的名称，并包含用户在请求时传递的相应值。对于可选参数，如果没有提供值，则键的值将为null（例如：argumento1=NULL）。

->set('get', 'bar/{obrigatório}')
->callback(function($functions, $params){
  return $params['obrigatório'];
});

->set('get', 'bar/{?opcional}')
->callback(function($functions, $params){
  return !is_null($params['opcional']) ? "parâmetro opcional: {$params['opcional']}" : 'nenhum parâmetro opcional foi informado';
});

控制器

在MVC中，控制器负责响应用户的HTTP请求并发送响应。您可以创建用于每个路由或路由组的控制器。

使用Controller方法可以指定控制器及其方法，它们将负责处理此类请求。不必担心，只需提供一个命名空间，应用程序的核心将为您实例化它。

->controller('Controller', 'action', false)//false, Defaut; O nome do controller será antecedido do namespace App\Controller\
->controller('Foo\Bar\Controller', 'action', true)//O nome do controller será interpretado como um namespace completo

控制器类

每个控制器类都必须有一个构造函数，其第一个参数将被一个数组填充，该数组包含应用程序核心生成的函数列表。要访问函数，只需通过函数名称访问数组的索引。目前仅提供“getUriById”函数。

注意：有关“getUriById”函数的更多详细信息，请参阅上面的“获取命名路由”主题。

//Controller.php
namespace App\Controller;

Class Controller{
  public function __construct($functions)
  {

  }

  public function action()
  {
    return "It's work well, dude!";
  }
}

//Controller.php
namespace Foo\Bar;

Class Controller{
  public function __construct($functions)
  {

  }

  public function action()
  {
    return "It's work well, dude!";
  }
}

控制器中的路由参数

路由参数将以数组的形式作为对应于路由的控制器方法的参数传递。为此，方法需要准备好接收这些值。

注意：有关路由参数的更多详细信息，请参阅上面的“路由参数”主题。

//Controller.php
namespace App\Controller;

Class Controller{
  public function action($args)
  {
    echo '<pre>';
    print_r($args);
    echo '</pre>';
  }
}

中间件

中间件由将在控制器或回调之前执行的指令组成，中间件对于数据验证很有用，并且根据结果，应用程序的流程可以保持或终止。

中间件的方法应返回null以表示成功。如果返回了非null值，则应用程序将终止其流程并显示中间件函数的返回值作为响应。

声明中间件

要声明中间件，只需调用“middleware”函数，该函数期望接收一个数组作为第一个参数，其中索引应与中间件类对应，而值是一个包含类中一个或多个方法的数组。可以提供一个可选的第二参数，其中包含中间件的命名空间，默认命名空间是“App\Middleware”。

注意：中间件总是按照定义的顺序执行。

->middleware(['MiddlewareClass' => ['action'] ]);
->middleware(['MiddlewareClass' => ['action'] ], 'App\Mynamespace\\');
->middleware(['MiddlewareClass' => ['action1', 'action2'] ]);
->middleware(['MiddlewareClass1' => ['action1', 'action2'], 'MiddlewareClass2' => ['action1'] ]);

中间件类

需要创建一个包含一个或多个方法的类。每个方法应包含相应的逻辑并返回一个响应。

Class Middleware
{
  public function action()
  {
    //Validando...

    //Se nenhum valor for retornado, a aplicação receberá um valor nulo como resposta e seguirar seu fluxo. É facultativo o uso de "return null".

    //Caso algum valor seja retornado além de nulo, o fluxo da aplicação será encerrado e o retorno será exbido como resposta ao usuário.
  }
}

路由组的方法

路由分组

分组路由可以减少在文件中重复命令，因为可以通过调用“group”方法在路由组中执行相同的函数。

Group方法

要开始一个路由组，只需调用“group”函数。

$route->group()

注意：方法声明后，必须按顺序调用“add”函数，然后可以使用其他方法。

将路由添加到组

要向组中添加一个或多个路由，只需调用“add”方法并传递一个包含路由的数组作为参数。您可以在组内部正常使用路由的所有方法，唯一的例外是当前无法在组内部调用组。

->add([
  $route->set('get', 'foo')->controller('ControllerClass', 'action')->name('foo-route'),
  $route->set('post', 'bar')->controller('ControllerClass', 'action')->name('bar-route')
]);

注意：此函数返回一个包含所有路由组方法的“HttpRoutes\Route\GroupRoutesMethods”实例。

指定所有路由的基础路径

您可以为组中的所有路由指定一个前缀路径，为此请调用“path”方法。

->path('foo/bar/');

控制器

一个路由组可以属于同一个类。控制器的方法应以数组形式按路由在组内的顺序告知。

->controller("ControllerClass", ['action1', 'action2']);

中间件

此函数的使用方式与单个路由的使用方式相同。中间件始终按定义顺序执行，首先是每个路由的单独中间件，最后是组的中间件。

->middleware(['Examples\Bar' => ['action'], 'Examples\Foo' => ['action']]);

jordan / http-routes

维护者

详细信息