{"id":37236401,"url":"https://github.com/polymorphine/routing","last_synced_at":"2026-01-16T04:53:05.482Z","repository":{"id":57043482,"uuid":"344772754","full_name":"polymorphine/routing","owner":"polymorphine","description":"Composite routing library for HTTP applications","archived":false,"fork":false,"pushed_at":"2025-01-28T03:09:44.000Z","size":707,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-03-01T00:17:58.834Z","etag":null,"topics":["http","psr-15","psr-7","routing"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/polymorphine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-05T10:20:03.000Z","updated_at":"2025-01-28T03:09:48.000Z","dependencies_parsed_at":"2025-01-28T04:19:41.105Z","dependency_job_id":"aa253797-c900-4f77-858b-7bcbfbea9b3f","html_url":"https://github.com/polymorphine/routing","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/polymorphine/routing","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polymorphine%2Frouting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polymorphine%2Frouting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polymorphine%2Frouting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polymorphine%2Frouting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polymorphine","download_url":"https://codeload.github.com/polymorphine/routing/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polymorphine%2Frouting/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28420814,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T10:47:48.104Z","status":"ssl_error","status_checked_at":"2026-01-14T10:46:19.031Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["http","psr-15","psr-7","routing"],"created_at":"2026-01-15T04:14:21.751Z","updated_at":"2026-01-15T04:14:22.365Z","avatar_url":"https://github.com/polymorphine.png","language":"PHP","readme":"# Polymorphine/Routing\n[![Latest stable release](https://poser.pugx.org/polymorphine/routing/version)](https://packagist.org/packages/polymorphine/routing)\n[![Build status](https://github.com/polymorphine/routing/workflows/build/badge.svg)](https://github.com/polymorphine/routing/actions)\n[![Coverage status](https://coveralls.io/repos/github/polymorphine/routing/badge.svg?branch=develop)](https://coveralls.io/github/polymorphine/routing?branch=develop)\n[![PHP version](https://img.shields.io/packagist/php-v/polymorphine/routing.svg)](https://packagist.org/packages/polymorphine/routing)\n[![LICENSE](https://img.shields.io/github/license/polymorphine/routing.svg?color=blue)](LICENSE)\n### Composite routing library for HTTP applications\n\n#### Concept feature: *Tree structure routing matching requests and building endpoint urls*\nRouter may consist of individual routes (see [`Route`](src/Route.php) interface) of\nthree main categories:\n* **Splitters** - Switches that branch single route into multiple route paths.\n  `Switch` would be more accurate name, but it's a php keyword and it would require\n  some additional prefix/postfix description.\n* **Gates** - Routes that determine if current request should be forwarded or performs\n  some preprocessing based on request passing through.\n* **Endpoints** - Routes which only responsibility is to take (processed) request and\n  pass it to handler that produces response. Neither routing path continuations nor uri\n  building happens in endpoint routes, but when request uri path is not fully processed\n  then handler method is not called and null (prototype) response is returned.\n  Endpoints are also capable of gathering and returning responses for OPTIONS method\n  requests if this http method was not explicitly routed.\n\nThese routes composed in different ways will create unique routing logic, but since\ncomposition tree may be deep its instantiation using `new` operator may become\nhard to read by looking at large nested structure or its dependencies assembled\ntogether, but instantiated in order that is reversed to execution flow (nested\nstructure instantiated first).\n\n[`Builder`](src/Builder.php) is a part of this package to help with\nthe problem. It uses _fluent interface with expressive method names_ - more concise than\nclass names \u0026 their constructors that would be used in direct composition.\nIt is also more readable due to the fact that builder method calls _resemble execution\npath_ in instantiated tree.\n\n### Installation with [Composer](https://getcomposer.org/)\n```bash\ncomposer require polymorphine/routing\n```\n\n### Routing build example\nDiagram below shows control flow of the request passed to matching endpoint in simplified blog page example.\n\n![Routing diagram](https://user-images.githubusercontent.com/9908030/48569332-aeb2e980-e901-11e8-810e-4e447df49ce6.png)\n\nLet's start with it's routing logic description:\n1. Request is passed to the router (root)\n2. Forwarded request goes through CSRF and (if CSRF guard will allow) Authentication gates (let's assume that\n   there are no other registered user roles than admin)\n3. In ResponseScan request is forwarded sequentially through each route until response other than \"nullResponse\"\n   is returned.\n4. First (default) route will pass request forward only if Authentication marked request as coming from\n   page admin.\n5. If request was forwarded all meaningful endpoints are available, and if user has no authenticated account\n   routes dedicated for unregistered (\"guest\") user are tested.\n6. Of course \"guest\" user may access almost all pages in read-only mode, so we can forward\n   his request to the main tree after guest specific or forbidden options are excluded.\n   Next routes will check if user wants to log in, access logout page (which makes no sense so he is redirected)\n   or gain unauthorized access to `/admin` path. Beside these, all other read-only (`GET`) endpoints should be\n   accessible for guests.\n7. If none of previous routes returned meaningful response `GET` requests are allowed to main endpoints tree.\n8. While some endpoint access makes sense from guest perspective it is pointless from admin's - for example admin\n   trying to log in will be redirected to home page. Guests won't be forwarded here, because this case was\n   already resolved for them.\n\nHere's an example showing how to create this structure using routing builder:\n```php\n/**\n * assume defined:\n * UriInterface        $baseUri\n * ResponseInterface   $nullResponse\n * MiddlewareInterface $csrf\n * MiddlewareInterface $auth\n * callable            $adminGate\n * callable            $notFound\n * callable            $this-\u003eendpoint(string)\n */\n\n$builder = new Builder();\n$root    = $builder-\u003erootNode()-\u003emiddleware($csrf)-\u003emiddleware($auth)-\u003eresponseScan();\n\n$main = $root-\u003edefaultRoute()-\u003ecallbackGate($adminGate)-\u003elink($filteredGuestRoute)-\u003epathSwitch();\n$main-\u003eroot('home')-\u003ecallback($this-\u003eendpoint('HomePage'));\n$admin = $main-\u003eroute('admin')-\u003emethodSwitch();\n$admin-\u003eroute('GET')-\u003ecallback($this-\u003eendpoint('AdminPanel'));\n$admin-\u003eroute('POST')-\u003ecallback($this-\u003eendpoint('ApplySettings'));\n$main-\u003eroute('login')-\u003eredirect('home');\n$main-\u003eroute('logout')-\u003emethod('POST')-\u003ecallback($this-\u003eendpoint('Logout'));\n$articles = $main-\u003eresource('articles')-\u003eid('id');\n$articles-\u003eindex()-\u003ecallback($this-\u003eendpoint('ShowArticles'));\n$articles-\u003eget()-\u003ecallback($this-\u003eendpoint('ShowArticle'));\n$articles-\u003epost()-\u003ecallback($this-\u003eendpoint('AddArticle'));\n$articles-\u003epatch()-\u003ecallback($this-\u003eendpoint('UpdateArticle'));\n$articles-\u003edelete()-\u003ecallback($this-\u003eendpoint('DeleteArticle'));\n$articles-\u003eadd()-\u003ecallback($this-\u003eendpoint('AddArticleForm'));\n$articles-\u003eedit()-\u003ecallback($this-\u003eendpoint('EditArticleForm'));\n\n$root-\u003eroute()-\u003epath('/login')-\u003emethodSwitch([\n    'GET'  =\u003e new CallbackEndpoint($this-\u003eendpoint('LoginPage')),\n    'POST' =\u003e new CallbackEndpoint($this-\u003eendpoint('Login'))\n]);\n$root-\u003eroute()-\u003epath('/logout')-\u003eredirect('home');\n$root-\u003eroute()-\u003epath('/admin')-\u003eredirect('login');\n$root-\u003eroute()-\u003emethod('GET')-\u003ejoinLink($filteredGuestRoute);\n$root-\u003eroute()-\u003ecallback($notFound);\n\n$router = $builder-\u003erouter($baseUri, $nullResponse);\n```\nTests for this example structure can be found in [`ReadmeExampleTests.php`](tests/ReadmeExampleTest.php) - compare one\ncreated as above using builder ([`BuilderTests.php`](tests/ReadmeExampleTest/BuilderTest.php)) and\nequivalent structure composed directly from components ([`CompositionTests.php`](tests/ReadmeExampleTest/CompositionTest.php))\nwhich will be result of calling builder methods.\n \n### Routing components \u0026 builder commands\n\n#### Endpoints\n\nEndpoints are responsible for handling incoming server requests with procedures given by programmer.\nBeside that, endpoints can can handle types of requests that can be resolved in generic way (`OPTIONS`, `HEAD`).\nThere are several ways to define endpoint behaviour:\n\n1. [`CallbackEndpoint`](src/Route/Endpoint/CallbackEndpoint.php) ([`RouteBuilder::callback($callable)`](src/Builder/Node/RouteNode.php#L47))\n  will handle forwarded request using given callback function with following signature:\n    ```php\n    $callable = function (ServerRequestInterface $request): ResponseInterface { ... }\n    ```\n2. [`HandlerEndpoint`](src/Route/Endpoint/HandlerEndpoint.php) ([`RouteBuilder::handler(RequestHandlerInterface $handler)`](src/Builder/Node/RouteNode.php#L59))\n  will handle forwarded request with given class implementing RequestHandlerInterface.\n3. [`RedirectEndpoint`](src/Route/Endpoint/RedirectEndpoint.php) ([`RouteBuilder::redirect(string $routingPath, $code = 301)`](src/Builder/Node/RouteNode.php#L84))\n  will return response redirecting to another endpoint route.\n4. _Mapped endpoint_ ([`RouteBuilder::endpoint(string $id)`](src/Builder/Node/RouteNode.php#L104))\n  will use user defined callback to create endpoint route based on given id string. To define mapping\n  procedure initialise [`Builder`](src/Builder.php) with [`MappedRoutes`](src/Builder/MappedRoutes.php)\n  with defined `$endpoint` parameter (see predefined mapping using PSR's `ContainerInterface` in\n  [`MappedRoutes::withContainerMapping()`](src/Builder/MappedRoutes.php#L56)).\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolymorphine%2Frouting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolymorphine%2Frouting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolymorphine%2Frouting/lists"}