Costumo fazer da seguinte forma:
Collection - A coleção que vai guardar todas as rotas.
Route - A classe que representa uma rota. Você deve fornecer informações como a uri que deseja capturar e verbos http aceitos.
Router - A classe que serve para fazer a ponte entre Route e Collection. É um facilitador para criar rotas dentro da coleção.
DispatcherInterface - A interface que fornece um método a ser executado como o despachante da rota. Preferi fazer uma interface para poder atender a diversas implementações, por exemplo, alguém que quer usar uma biblioteca mais complexa ou que queria simplesmente usar menos recursos.
Então, nesse contexto, teríamos uma estrutura mais ou menos assim:
$router = new Router(new Collection);
// Cria a instância de Route, coloca dentro da Collection
// E retorna Rota recém-criada, para possíveis outra definições
$router->get('/', 'HomeController::getIndex');
$router->get('/login', function () {})->setName('home.login');
// Classe que implementa DispatcherInterface
$router->dispatch(new Dispatcher());
Baseando no contexto apresentado na pergunta, creio que uma interessante seria:
$request = new Request();
// retorna new Response se tudo der certo
$response = $router->dispatch(new RequestDispatcher($request));
$response->send();
Dentro do seu RequestDispatcher
, você poderia aplicar as devidas operações para chamar Controller e Método.
Por exemplo:
class RequestDispatcher implements DispatcherInterface {
public function __construct(Request $request) {
$this->request = $request;
}
public function dispatch(Router $router) {
$route = $router->findByRequest($this->request);
if (! $route) return $this->notFound();
$response = call_user_func($route->callAction(), $route->getParameters());
return $response;
}
}
Ou seja, no seu Dispatcher, você pode adicionar as operações necessárias para procurar a rota dentro da coleção. Quando não for encontrada, você pode invocar uma ação para o laçamento do erro 404. Quando é encontrado, você pode chamar a ação definida para a determinada url e chamá-la, retornando então um Response.
Tentando resumir isso tudo:
O Dispatcher procura pela rota dentro de uma coleção de rotas, que foi criada pelo router. Em seguida, se o Dispatcher encontra a rota, ele converte o retorno da ação da rota (Pode ser um método de um Controller ou uma Closure) para uma Response, que finalmente é enviada para o saída.
Você citou na sua pergunta a respeito de um Handler, que é passado através de um callback.
Creio que você está falando de uma função anônima, que algumas bibliotecas costumam utilizar para "amarrar" uma determinada funcionalidade para uma rota a fim de ser executada no final.
Na minha biblioteca também fiz isso. Posso usar tanto um método de uma classe (o Controller) como uma função anônima. Creio que isso seja muito útil em casos onde a rota não faça sentido apontar para um controller específico, por não ser algo que não tenha "relacionamento" com o restante.
Exemplo:
$router->get('/json/cep/{num}', function ($number) {
$url = sprintf('https://cep.correios.com.br/%s.json', $number);
$dados = json_decode(file_get_contents($url));
// Transforma em JsonResponse
return $dados;
});