phel-lang / router
A Phel router based on symfony routing component
Requires
- php: >=8.2
- phel-lang/phel-lang: >=0.15
- symfony/routing: ^6.4 || ^7.0
README
A data driver router for Phel.
- Based on Symfony Routing
- Inspired by reitit
- Fast
Installation
composer require phel-lang/router
Route syntax
Routes are defined as vectors. The first element is the path of the route. This element is followed an optional map for route data and an optional vector of child routes. The paths of a route can have path parameters.
Examples
Simple route:
["/ping"]
Two routes:
[["/ping"]
["/pong"]]
Routes with data:
[["/ping" {:name ::ping}]
["/pong" {:name ::pong}]]
Routes with path parameters:
[["/users/{user-id}"]
["/api/{version}/ping]]
Routes with path parameter validation:
["/users/{user-id<\d+>}"]
Routes with catch all parameters:
["/public/{path<.*>}"]
Nested routes:
["/api"
["/admin" {:middware [admin-middleware-fn]}
["" {:name ::admin}]
["/db" {name ::db}]]
["/ping" {:name ::ping}]]
Same routes flattened:
[["/api/admin" {:middleware [admin-middleware-fn] :name ::admin}]
["/api/admin/db" {:middleware [admin-middleware-fn] :name ::db}]
["/api/ping" {:name ::ping}]]
Router
Given a vector of routes a router can be create. Phel router offers two option to create a router. The first is a dynamic router that is evaluated with every new request:
(ns my-app
(:require phel\router :as r))
(def router
(r/router
["/api"
["/ping" {:name ::ping}]
["/user/{id}" {:name ::user}]]))
The second router is a compiled router. This router is evaluated during compile time (macro) and is therefore very fast. The drawback is that routes can not be created dynamically during the execution of a request.
(ns my-app
(:require phel\router :as r))
(def router
(r/compiled-router
["/api"
["/ping" {:name ::ping}]
["/user/{id}" {:name ::user}]]))
Path based routing
To match a route given a path the phel\router/match-by-path
function can be used. It takes a router and a path as arguments and returns a map or nil
.
(r/match-by-path router "/api/user/10")
# Evaluates to
# {:template "/api/user/{id}"
# :data {:name ::user
# :path "/api/user/10"
# :path-params {:id "10"}}}
(r/match-by-path router "/hello") # Evaluates to nil
Name based routing
All routes that have :name
route data can be matched by name using the phel\router/match-by-name
function. It takes a router and the name of route and returns a map or nil
.
(r/match-by-name router ::ping)
# Evaluates to
# {:template "/api/ping"
# :data {:name ::ping}}
(r/match-by-name router ::foo) # Evaluates to nil
Generate path
It is also possible to generate a path for a give route and it's path parameters. The function phel\router/generate
takes a router, the name of the route and a map of router parameters. It returns either the generate path as string or throws an exception if the route can not be found ore path parameters are missing.
(r/generate router ::ping {}) # Evaluates to "/api/ping"
(r/generate router ::user {:id 10}) # Evaluates to "/api/user/10"
(r/generate router ::user {:id 10 :foo "bar"}) # Evaluates to "/api/user/10?foo=bar"
(r/generate router ::user {}) # Throws Symfony\Component\Routing\Exception\MissingMandatoryParametersException
(r/generate router ::foo {}) # Throws Symfony\Component\Routing\Exception\RouteNotFoundException
Handler
Each route can have a handler functions that can are execute when a route matches the current path. A handler function is a function that takes as argument as phel\http/request
and returns a phel\http/response
.
# request -> response
(fn [request]
(h/response-from-map {:status 200 :body "ok"}))
A handler can be placed either at the top level of the route data using the :handler
keyword or under a specific method (:get
, :head
, :patch
, :delete
, :options
, :post
, :put
or :trace
). The top level handler is used if a request method based handler is not found.
[["/all" {:handler handler-fn}]
["/ping" {:name ::ping
:get {:handler handler-fn}
:post {:handler handler-fn}}]]
To process a request the router must be wrapped in the phel\router/handler
method. This method returns a function that accepts a phel\http/request
and returns a phel\http/response
.
(ns my-app
(:require phel\router :as r)
(:require phel\http :as h))
(defn handler [req]
(h/response-from-map {:status 200 :body "ok"}))
(def app
(r/handler
(r/router
[["/all" {:handler handler}]
["/ping" {:name ::ping
:get {:handler handler}
:post {:handler handler}}]])))
(app (h/request-from-map {:method "DELETE" :uri "/all"}))
# Evaluates to (h/response-from-map {:status 200 :body "ok"})
(app (h/request-from-map {:method "GET" :uri "/ping"}))
# Evaluates to (h/response-from-map {:status 200 :body "ok"})
(app (h/request-from-map {:method "PUT" :uri "/ping"}))
# Evaluates to (h/response-from-map {:status 404 :body "Not found"})
Middleware
Each router can have multiple middleware functions. A middleware function is a function that takes a handler function and a phel\http/request
and returns a phel\http/response
.
# handler -> request -> response
(fn [handler request] (handler request))
A middleware can be placed either at the top level of the route data using the :middleware
keyword or under a specific method (:get
, :head
, :patch
, :delete
, :options
, :post
, :put
or :trace
).
(ns my-app
(:require phel\router :as r)
(:require phel\http :as h))
(defn handler [req]
(h/response-from-map
{:status 200
:body (push (get-in req [:attributes :my-middleware]) :handler)}))
(defn my-middleware [name]
(fn [handler request]
(handler
(update-in
request
[:attributes :my-middleware]
(fn [x]
(if (nil? x)
[name]
(push x name)))))))
(def app
(r/handler
(r/router
["/api" {:middleware [(my-middleware :api)]}
["/ping" {:handler handler}]
["/admin" {:middleware [(my-middleware :admin)]}
["/db" {:middleware [(my-middleware :db)]
:delete {:middleware [(my-middleware :delete)]
:handler handler}}]]])))
(app (h/request-from-map {:method "DELETE" :uri "/api/ping"}))
# Evaluates to (h/response-from-map {:status 200 :body [:api :handler]})
(app (h/request-from-map {:method "DELETE" :uri "/api/admin/db"}))
# Evaluates to (h/response-from-map {:status 200 :body [:api :admin :db :delete :handler]})