From fd8f93758bf08841c5e018bdd45a0654fd60736a Mon Sep 17 00:00:00 2001 From: Serge Kvashnin <75180587+serge-kvashnin@users.noreply.github.com> Date: Tue, 7 May 2024 21:45:43 +0200 Subject: [PATCH] Docs. --- .github/workflows/docs.yml | 37 ++++++ .gitignore | 3 + README.md | 132 +-------------------- docs/config/_default/hugo.toml | 73 ++++++++++++ docs/config/_default/languages.toml | 9 ++ docs/config/_default/markup.toml | 33 ++++++ docs/config/_default/menus/menus.en.toml | 22 ++++ docs/config/_default/module.toml | 88 ++++++++++++++ docs/config/_default/params.toml | 137 ++++++++++++++++++++++ docs/content/_index.md | 30 +++++ docs/content/license.md | 34 ++++++ docs/content/usage/_index.md | 15 +++ docs/content/usage/definition.md | 81 +++++++++++++ {doc => docs/content/usage}/pathfinder.md | 16 ++- docs/content/usage/quick-start.md | 74 ++++++++++++ docs/public/.gitkeep | 0 16 files changed, 650 insertions(+), 134 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/config/_default/hugo.toml create mode 100644 docs/config/_default/languages.toml create mode 100644 docs/config/_default/markup.toml create mode 100644 docs/config/_default/menus/menus.en.toml create mode 100644 docs/config/_default/module.toml create mode 100644 docs/config/_default/params.toml create mode 100644 docs/content/_index.md create mode 100644 docs/content/license.md create mode 100644 docs/content/usage/_index.md create mode 100644 docs/content/usage/definition.md rename {doc => docs/content/usage}/pathfinder.md (91%) create mode 100644 docs/content/usage/quick-start.md create mode 100644 docs/public/.gitkeep diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..e15850d --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,37 @@ +name: Build Documentation + +on: workflow_dispatch + +jobs: + build-docs: + runs-on: ubuntu-latest + permissions: + contents: read + packages: read + deployments: write + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Login to GH Packages + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Pull builder image + run: docker pull ghcr.io/norvica/docs:v0.1.0 + + - name: Build Documentation + run: | + docker run --rm -v $(pwd)/docs/content:/app/content -v $(pwd)/docs/config/_default:/app/config/_default -v $(pwd)/docs/public:/app/public -e HUGO_ENVIRONMENT=production -e HUGO_ENV=production ghcr.io/norvica/docs:v0.1.0 npm run build -- --gc --minify --baseURL "https://router.norvica.dev" + + - name: Publish + uses: cloudflare/pages-action@v1 + with: + apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} + accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} + projectName: ${{ secrets.CLOUDFLARE_PROJECT_NAME }} + directory: $(pwd)/docs/public diff --git a/.gitignore b/.gitignore index a7dfead..6e7bde7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ composer.lock .phpunit.result.cache vendor +# docs +docs/public/* +!docs/public/.gitkeep diff --git a/README.md b/README.md index 11715f4..7194701 100644 --- a/README.md +++ b/README.md @@ -3,138 +3,10 @@ [![Latest Stable Version](https://poser.pugx.org/norvica/pathfinder/v/stable.png)](https://packagist.org/packages/norvica/pathfinder) [![Checks](https://github.com/norvica/pathfinder/actions/workflows/checks.yml/badge.svg)](https://github.com/norvica/pathfinder/actions/workflows/checks.yml) -**Pathfinder** is a lean and extremely fast PHP router built on the [Trie](https://en.wikipedia.org/wiki/Trie) (or +**Pathfinder** is a lean and fast PHP router built on the [Trie](https://en.wikipedia.org/wiki/Trie) (or prefix tree) search algorithm. Its design enables quick lookups and is optimized for high performance. -## Install - -```bash -composer require norvica/pathfinder -``` - -## Use - -If you'd like to use the lower-level `Pathfinder` class directly, please refer to the -[appropriate documentation section](./doc/pathfinder.md#use). The `Router` class provides a convenient wrapper and performs -matching against PSR-7 `ServerRequestInterface` objects. - -If you'd like to use a more low level class `Pathfinder` please refer to an -[appropriate documentation section](./doc/pathfinder.md#use). `Router` class provides a convenience wrapper and is matching -against PSR-7 `ServerRequestInterface`. - -To get started, create a `Router` instance, define your routes, and then match your incoming request: - -```php -use Norvica\Pathfinder\Router; - -// Create a Pathfinder instance -$router = new Router(); - -// Define your routes using closures -$definitions = static function(Router $router) { - $router->route('POST', '/orders', OrderPostController::class); - $router->route('GET', '/orders/{id}', [OrderGetController::class, '__invoke']); -}; - -// Load your route definitions -$definitions($router); - -// NOTICE: This is an example of request instantiation. -// Use the library of your choice that instantiates PSR-7 request -// (e.g. https://github.com/guzzle/psr7). -$request = ServerRequest::fromGlobals(); - -// Handling a request -try { - $route = $router->match($request); - $handler = $route->handler(); - $parameters = $route->parameters(); - // [...] execute matched handler -} catch (\Norvica\Pathfinder\Exception\NotFound $e) { - // [...] handle 404 -} catch (\Norvica\Pathfinder\Exception\MethodNotAllowed $e) { - // [...] handle 405 -} -``` - -## Routes Definition - -### Basic Route - -A basic route is a simple, static path: - -```php -$router->route('GET', '/orders', OrderListController::class); -``` - -### Parameterized Route - -To include parameters like a username or ID in the URL: - -```php -$router->route('GET', '/orders/{id}', OrderGetController::class); -``` - -### Regular Expression Constraints - -You can add regex constraints to your parameters: - -```php -$router->route('GET', '/orders/{id:[0-9]+}', OrderGetController::class); -``` - -### Optional Parameters - -You can define routes with optional segments: - -```php -$router->route('GET', '/articles/{id:[0-9]+}[/{slug}]', ArticleGetController::class); -``` - -### Complex Routes - -You can also define more complex routes with multiple parameters: - -```php -$router->route('GET', '/course/{year:[0-9]{4}}/{subject:[a-z]+}/{code:[0-9a-f]{4}}', CourseGetController::class); -``` - -### Enumerated Parameters - -For when you have a specific set of acceptable parameter values: - -```php -$router->route('GET', '/{language:en|de}/profile', ProfileGetController::class); -``` - -### Shortcuts - -For convenience, `Router` offers shortcut methods for common HTTP request methods. - -```php -$router->get('/orders', 'get_orders_handler'); -$router->post('/orders', 'post_orders_handler'); -$router->put('/orders/{id}', 'put_order_handler'); -$router->patch('/orders/{id}', 'patch_order_handler'); -$router->delete('/orders/{id}', 'delete_order_handler'); -// ... -``` - -You can use these shortcut methods just like you would use the route method, but without the need to specify the HTTP -method as the first argument. - -> [!IMPORTANT] -> The router only facilitates matching `HEAD` requests to `GET` routes when a specific `HEAD` handler is not found. -> Developers must explicitly ensure that `HEAD` method calls always return -> [empty response bodies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD). - -## Tests - -Run the PHPUnit tests to ensure that the package is functioning as expected: - -```bash -./vendor/bin/phpunit --testdox -``` +Read more on [https://router.norvica.dev](https://router.norvica.dev) ## References diff --git a/docs/config/_default/hugo.toml b/docs/config/_default/hugo.toml new file mode 100644 index 0000000..61b426f --- /dev/null +++ b/docs/config/_default/hugo.toml @@ -0,0 +1,73 @@ +title = "Pathfinder" +baseurl = "/" +canonifyURLs = false +disableAliases = true +disableHugoGeneratorInject = true + disableKinds = ["taxonomy", "term"] +enableEmoji = true +enableGitInfo = false +enableRobotsTXT = true +languageCode = "en-US" +paginate = 10 +rssLimit = 10 +summarylength = 20 # 70 (default) + +# Multilingual +defaultContentLanguage = "en" +disableLanguages = [] +defaultContentLanguageInSubdir = false + +copyRight = "Copyright (c) 2024" + +[build.buildStats] + enable = true + +[outputs] + home = ["HTML", "searchIndex"] + section = ["HTML", "SITEMAP"] + +[outputFormats.searchIndex] + mediaType = "application/json" + baseName = "search-index" + isPlainText = true + notAlternative = true + +# Add output format for section sitemap.xml +[outputFormats.SITEMAP] + mediaType = "application/xml" + baseName = "sitemap" + isHTML = false + isPlainText = true + noUgly = true + rel = "sitemap" + +[sitemap] + changefreq = "monthly" + filename = "sitemap.xml" + priority = 0.5 + +[caches] + [caches.getjson] + dir = ":cacheDir/:project" + maxAge = -1 # "30m" + +#[permalinks] +# docs = "/:sections[1:]/:slug/" + +[minify.tdewolff.html] + keepWhitespace = false + +[related] + threshold = 80 + includeNewer = true + toLower = false + [[related.indices]] + name = "date" + weight = 10 + +[imaging] + anchor = "Center" + bgColor = "#ffffff" + hint = "photo" + quality = 85 + resampleFilter = "Lanczos" diff --git a/docs/config/_default/languages.toml b/docs/config/_default/languages.toml new file mode 100644 index 0000000..3df504d --- /dev/null +++ b/docs/config/_default/languages.toml @@ -0,0 +1,9 @@ +[en] + languageName = "English" + contentDir = "content/en" + weight = 10 + [en.params] + languageISO = "EN" + languageTag = "en-US" + footer = 'Doks ' + alertText = '' diff --git a/docs/config/_default/markup.toml b/docs/config/_default/markup.toml new file mode 100644 index 0000000..6eaba1e --- /dev/null +++ b/docs/config/_default/markup.toml @@ -0,0 +1,33 @@ +defaultMarkdownHandler = "goldmark" + +[goldmark] + [goldmark.extensions] + linkify = false + [goldmark.parser] + autoHeadingID = true + autoHeadingIDType = "github" + [goldmark.parser.attribute] + block = true + title = true + [goldmark.renderer] + unsafe = true + +[highlight] + anchorLineNos = false + codeFences = true + guessSyntax = false + hl_Lines = '' + hl_inline = false + lineAnchors = '' + lineNoStart = 1 + lineNos = false + lineNumbersInTable = false + noClasses = false + noHl = false + style = 'monokai' + tabWidth = 2 + +[tableOfContents] + endLevel = 3 + ordered = false + startLevel = 2 diff --git a/docs/config/_default/menus/menus.en.toml b/docs/config/_default/menus/menus.en.toml new file mode 100644 index 0000000..f0ba5a2 --- /dev/null +++ b/docs/config/_default/menus/menus.en.toml @@ -0,0 +1,22 @@ +[[main]] + name = "Docs" + url = "/usage/quick-start/" + weight = 10 + +[[main]] + name = "Issues" + url = "https://github.com/norvica/pathfinder/issues" + post = '' + weight = 20 + +[[social]] + name = "GitHub" + pre = '' + url = "https://github.com/norvica/pathfinder" + post = '' + weight = 30 + +[[footer]] + name = "MIT License" + url = "/license/" + weight = 10 diff --git a/docs/config/_default/module.toml b/docs/config/_default/module.toml new file mode 100644 index 0000000..7ac78e3 --- /dev/null +++ b/docs/config/_default/module.toml @@ -0,0 +1,88 @@ +# mounts +## archetypes +[[mounts]] + source = "node_modules/@hyas/doks-core/archetypes" + target = "archetypes" + +[[mounts]] + source = "archetypes" + target = "archetypes" + +## assets +[[mounts]] + source = "node_modules/@hyas/core/assets" + target = "assets" + # excludeFiles = ["scss/app.scss", "js/app.js"] + +[[mounts]] + source = "node_modules/@hyas/images/assets" + target = "assets" + +[[mounts]] + source = "node_modules/@hyas/doks-core/assets" + target = "assets" + +[[mounts]] + source = "node_modules/@tabler/icons/icons" + target = "assets/svgs/tabler-icons" + +[[mounts]] + source = "assets" + target = "assets" + +## content +[[mounts]] + source = "content" + target = "content" + +## data +[[mounts]] + source = "node_modules/@hyas/doks-core/data" + target = "data" + +[[mounts]] + source = "data" + target = "data" + +## i18n +[[mounts]] + source = "node_modules/@hyas/doks-core/i18n" + target = "i18n" + +[[mounts]] + source = "i18n" + target = "i18n" + +## layouts +[[mounts]] + source = "node_modules/@hyas/core/layouts" + target = "layouts" + +[[mounts]] + source = "node_modules/@hyas/seo/layouts" + target = "layouts" + +[[mounts]] + source = "node_modules/@hyas/images/layouts" + target = "layouts" + +[[mounts]] + source = "node_modules/@hyas/doks-core/layouts" + target = "layouts" + +[[mounts]] + source = "node_modules/@hyas/inline-svg/layouts" + target = "layouts" + +[[mounts]] + source = "layouts" + target = "layouts" + +## static +[[mounts]] + source = "node_modules/@hyas/doks-core/static" + target = "static" + +[[mounts]] + source = "static" + target = "static" diff --git a/docs/config/_default/params.toml b/docs/config/_default/params.toml new file mode 100644 index 0000000..09c0647 --- /dev/null +++ b/docs/config/_default/params.toml @@ -0,0 +1,137 @@ +# Hugo +title = "Norvica Pathfinder" +description = "Lean and fast PHP router" +images = ["cover.png"] + +# mainSections +mainSections = ["content"] + +brand = "Norvica" + +# Doks (@hyas/doks-core) +[doks] + # Color mode + colorMode = "auto" # auto (default), light or dark + colorModeToggler = true # true (default) or false (this setting is only relevant when colorMode = auto) + + # Navbar + navbarSticky = true # true (default) or false + containerBreakpoint = "lg" # "", "sm", "md", "lg" (default), "xl", "xxl", or "fluid" + + ## Button + navBarButton = false # false (default) or true + navBarButtonUrl = "/usage/quick-start/" + navBarButtonText = "Get Started" + + # FlexSearch + flexSearch = true # true (default) or false + searchExclKinds = [] # list of page kinds to exclude from search indexing (e.g. ["home", "taxonomy", "term"] ) + searchExclTypes = [] # list of content types to exclude from search indexing (e.g. ["blog", "docs", "legal", "contributors", "categories"]) + showSearch = [] # [] (all pages, default) or homepage (optionally) and list of sections (e.g. ["homepage", "blog", "guides"]) + indexSummary = false # true or false (default); whether to index only the `.Summary` instead of the full `.Content`; limits the respective JSON field size and thus increases loading time + + ## Search results + showDate = false # false (default) or true + showSummary = true # true (default) or false + searchLimit = 99 # 0 (no limit, default) or natural number + + # Global alert + alert = false # false (default) or true + alertDismissable = true # true (default) or false + + # Bootstrap + bootstrapJavascript = false # false (default) or true + + # Nav + sectionNav = ["usage"] # ["docs"] (default) or list of sections (e.g. ["docs", "guides"]) + toTopButton = true # false (default) or true + breadcrumbTrail = false # false (default) or true + headlineHash = true # true (default) or false + scrollSpy = true # true (default) or false + + # Multilingual + multilingualMode = false # false (default) or true + showMissingLanguages = true # whether or not to show untranslated languages in the language menu; true (default) or false + + # Versioning + docsVersioning = false # false (default) or true + docsVersion = "0.2" + + # UX + headerBar = false # true (default) or false + backgroundDots = true # true (default) or false + + # Homepage + sectionFooter = false # false (default) or true + + # Blog + relatedPosts = false # false (default) or true + imageList = true # true (default) or false + imageSingle = true # true (default) or false + + # Repository + editPage = false # false (default) or true + lastMod = false # false (default) or true + repoHost = "GitHub" # GitHub (default), Gitea, GitLab, Bitbucket, or BitbucketServer + docsRepo = "https://github.com/norvica/pathfinder" + docsRepoBranch = "main" # main (default), master, or + docsRepoSubPath = "" # "" (none, default) or + + # SCSS colors + # backGround = "yellowgreen" + ## Dark theme + # textDark = "#dee2e6" # "#dee2e6" (default), "#dee2e6" (orignal), or custom color + # accentDark = "#5d2f86" # "#5d2f86" (default), "#5d2f86" (original), or custom color + ## Light theme + # textLight = "#1d2d35" # "#1d2d35" (default), "#1d2d35" (orignal), or custom color + # accentLight = "#8ed6fb" # "#8ed6fb" (default), "#8ed6fb" (orignal), or custom color + + # [doks.menu] + # [doks.menu.section] + # auto = true # true (default) or false + # collapsibleSidebar = true # true (default) or false + +# Debug +[render_hooks.image] + errorLevel = 'ignore' # ignore (default), warning, or error (fails the build) + +[render_hooks.link] + errorLevel = 'ignore' # ignore (default), warning, or error (fails the build) + highlightBroken = false # true or false (default) + +# Images (@hyas/images) +[hyas_images] + [hyas_images.defaults] + decoding = "async" # sync, async, or auto (default) + fetchpriority = "auto" # high, low, or auto (default) + loading = "lazy" # eager or lazy (default) + widths = [480, 576, 768, 1025, 1200, 1440] # [640, 768, 1024, 1366, 1600, 1920] for example + sizes = "auto" # 100vw (default), 75vw, or auto for example + process = "" # "fill 1600x900" or "fill 2100x900" for example + lqip = "16x webp q20" # "16x webp q20" or "21x webp q20" for example + +# Inline SVG (@hyas/inline-svg) +[inline_svg] + iconSetDir = "tabler-icons" # "tabler-icons" (default) + +# SEO (@hyas/seo) +[seo] + [seo.title] + separator = " | " + suffix = "" + [seo.favicons] + sizes = [] + icon = "favicon.png" # favicon.png (default) + svgIcon = "favicon.svg" # favicon.svg (default) +# maskIcon = "mask-icon.svg" # mask-icon.svg (default) +# maskIconColor = "white" # white (default) + [seo.schemas] + type = "Organization" # Organization (default) or Person + logo = "favicon-512x512.png" # Logo of Organization — favicon-512x512.png (default) + name = "Norvica" # Name of Organization or Person + sameAs = [] # E.g. ["https://github.com/gethyas/hyas", "https://fosstodon.org/@hyas"] + images = ["cover.png"] # ["cover.png"] (default) + #article = [] # Article sections + #newsArticle = [] # NewsArticle sections + #blogPosting = ["blog"] # BlogPosting sections + #product = [] # Product sections diff --git a/docs/content/_index.md b/docs/content/_index.md new file mode 100644 index 0000000..dc3b32c --- /dev/null +++ b/docs/content/_index.md @@ -0,0 +1,30 @@ +--- +title : "Pathfinder" +description: "" +lead: "Lean and fast PHP router" +date: 2024-05-06T19:33:08+02:00 +lastmod: 2024-05-06T19:33:08+02:00 +draft: false +seo: + title: "Lean and fast PHP router" # custom title (optional) + description: "" # custom description (recommended) + canonical: "" # custom canonical URL (optional) + noindex: false # false (default) or true +--- + +## Define and Match Routes + +Provides a flexible way to define and match routes in your PHP projects. + +```php +$router = new Router(); + +$router->route('POST', '/orders', [OrderController::class, 'post']); +$router->route('GET', '/orders/{id}', [OrderController::class, 'get']); + +$request = ServerRequest::fromGlobals(); + +$route = $router->match($request); +``` + +[Learn more →](/usage/quick-start/) diff --git a/docs/content/license.md b/docs/content/license.md new file mode 100644 index 0000000..4ad66de --- /dev/null +++ b/docs/content/license.md @@ -0,0 +1,34 @@ +--- +title: "MIT License" +description: "" +summary: "" +date: 2024-04-21T19:54:40+02:00 +lastmod: 2024-04-21T19:54:40+02:00 +draft: false +type: "legal" +seo: + title: "" # custom title (optional) + description: "" # custom description (recommended) + canonical: "" # custom canonical URL (optional) + noindex: false # false (default) or true +--- + +Copyright (c) Siarhei Kvashnin. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is furnished +to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/docs/content/usage/_index.md b/docs/content/usage/_index.md new file mode 100644 index 0000000..69c6ea1 --- /dev/null +++ b/docs/content/usage/_index.md @@ -0,0 +1,15 @@ +--- +title: "Usage" +description: "" +summary: "" +date: 2024-04-21T15:23:29+00:00 +lastmod: 2024-04-21T15:23:29+00:00 +draft: false +weight: 100 +toc: true +seo: + title: "" # custom title (optional) + description: "" # custom description (recommended) + canonical: "" # custom canonical URL (optional) + noindex: false # false (default) or true +--- diff --git a/docs/content/usage/definition.md b/docs/content/usage/definition.md new file mode 100644 index 0000000..f109320 --- /dev/null +++ b/docs/content/usage/definition.md @@ -0,0 +1,81 @@ +--- +title: "Routes Definition" +description: "" +date: 2024-05-06T19:33:08+02:00 +lastmod: 2024-05-06T19:33:08+02:00 +draft: false +seo: + title: "" # custom title (optional) + description: "" # custom description (recommended) + canonical: "" # custom canonical URL (optional) + noindex: false # false (default) or true +--- + +## Basic Route + +A basic route is a simple, static path: + +```php +$router->route('GET', '/orders', OrderListController::class); +``` + +## Parameterized Route + +To include parameters like a username or ID in the URL: + +```php +$router->route('GET', '/orders/{id}', OrderGetController::class); +``` + +## Regular Expression Constraints + +You can add regex constraints to your parameters: + +```php +$router->route('GET', '/orders/{id:[0-9]+}', OrderGetController::class); +``` + +## Optional Parameters + +You can define routes with optional segments: + +```php +$router->route('GET', '/articles/{id:[0-9]+}[/{slug}]', ArticleGetController::class); +``` + +## Complex Routes + +You can also define more complex routes with multiple parameters: + +```php +$router->route('GET', '/course/{year:[0-9]{4}}/{subject:[a-z]+}/{code:[0-9a-f]{4}}', CourseGetController::class); +``` + +## Enumerated Parameters + +For when you have a specific set of acceptable parameter values: + +```php +$router->route('GET', '/{language:en|de}/profile', ProfileGetController::class); +``` + +## Shortcuts + +For convenience, `Router` offers shortcut methods for common HTTP request methods. + +```php +$router->get('/orders', 'get_orders_handler'); +$router->post('/orders', 'post_orders_handler'); +$router->put('/orders/{id}', 'put_order_handler'); +$router->patch('/orders/{id}', 'patch_order_handler'); +$router->delete('/orders/{id}', 'delete_order_handler'); +// ... +``` + +You can use these shortcut methods just like you would use the route method, but without the need to specify the HTTP +method as the first argument. + +{{< callout context="note" icon="alert-triangle" >}} +The router only facilitates matching `HEAD` requests to `GET` routes when a specific `HEAD` handler is not found. +Developers must explicitly ensure that `HEAD` method calls always return [empty response bodies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD). +{{< /callout >}} diff --git a/doc/pathfinder.md b/docs/content/usage/pathfinder.md similarity index 91% rename from doc/pathfinder.md rename to docs/content/usage/pathfinder.md index 66aef8b..9b78b39 100644 --- a/doc/pathfinder.md +++ b/docs/content/usage/pathfinder.md @@ -1,7 +1,15 @@ -# Utilizing Pathfinder Class - -This part of the documentation describes the usage of the `Pathfinder` class. If you'd prefer to use the convenient `Router` -wrapper, please refer to the [appropriate documentation section](../README.md#use). +--- +title: "Using Pathfinder Directly" +description: "" +date: 2024-05-06T19:33:08+02:00 +lastmod: 2024-05-06T19:33:08+02:00 +draft: false +seo: + title: "" # custom title (optional) + description: "" # custom description (recommended) + canonical: "" # custom canonical URL (optional) + noindex: false # false (default) or true +--- ## Use diff --git a/docs/content/usage/quick-start.md b/docs/content/usage/quick-start.md new file mode 100644 index 0000000..c3e6eea --- /dev/null +++ b/docs/content/usage/quick-start.md @@ -0,0 +1,74 @@ +--- +title: "Quick Start" +description: "" +summary: "" +date: 2024-05-06T20:45:42+02:00 +lastmod: 2024-05-06T20:45:42+02:00 +draft: false +weight: 110 +toc: true +seo: + title: "" # custom title (optional) + description: "" # custom description (recommended) + canonical: "" # custom canonical URL (optional) + noindex: false # false (default) or true +--- + +**Pathfinder** is a lean and fast PHP router built on the [Trie](https://en.wikipedia.org/wiki/Trie) (or +prefix tree) search algorithm. Its design enables quick lookups and is optimized for high performance. + +Requires **PHP 8.1+**. + +## Install + +This library is installed using Composer. If you don't have Composer, you can get it from +[getcomposer.org](https://getcomposer.org). + +In your project's root directory, run the following command: + +```bash +composer require norvica/pathfinder +``` + +## Use + +{{< callout context="note" icon="info-circle" >}} +If you'd like to use the lower-level `Pathfinder` class directly, please refer to the +[appropriate documentation section](/usage/pathfinder). The `Router` class provides a convenient +wrapper and performs matching against PSR-7 `ServerRequestInterface` objects. +{{< /callout >}} + +To get started, create a `Router` instance, define your routes, and then match your incoming request: + +```php +use Norvica\Pathfinder\Router; + +// Create a Pathfinder instance +$router = new Router(); + +// Define your routes using closures +$definitions = static function(Router $router) { + $router->route('POST', '/orders', OrderPostController::class); + $router->route('GET', '/orders/{id}', [OrderGetController::class, '__invoke']); +}; + +// Load your route definitions +$definitions($router); + +// NOTICE: This is an example of request instantiation. +// Use the library of your choice that instantiates PSR-7 request +// (e.g. https://github.com/guzzle/psr7). +$request = ServerRequest::fromGlobals(); + +// Handling a request +try { + $route = $router->match($request); + $handler = $route->handler(); + $parameters = $route->parameters(); + // [...] execute matched handler +} catch (\Norvica\Pathfinder\Exception\NotFound $e) { + // [...] handle 404 +} catch (\Norvica\Pathfinder\Exception\MethodNotAllowed $e) { + // [...] handle 405 +} +``` diff --git a/docs/public/.gitkeep b/docs/public/.gitkeep new file mode 100644 index 0000000..e69de29