Merge pull request #10 from mindplay-dk/3.0.0

3.0.0

Author: mindplay-dk

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  CI:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        php:
+          - '8.0'
+          - '8.1'
+          - '8.2'
+          - '8.3'
+    steps:
+      - uses: shivammathur/setup-php@2.28.0
+        with:
+          php-version: ${{ matrix.php }}
+      - uses: actions/checkout@v3
+      - run: composer install --no-progress --no-ansi --no-interaction --dev --prefer-dist
+      - run: php test/test.php

.gitignore

@@ -1,3 +1,4 @@
-/.idea
+.*
+!.git*
 /vendor
 /test/build

LICENSE LICENSE.md

@@ -1,3 +1,4 @@
+Copyright (c) 2023, Rasmus Schultz
 Copyright (c) 2015, Vadim Baryshev
 All rights reserved.
 

README.md

@@ -1,16 +1,11 @@
 # mindplay/timber
 
-[![PHP Version](https://img.shields.io/badge/php-7.3%2B-blue.svg)](https://packagist.org/packages/mindplay/timber)
-[![Build Status](https://travis-ci.org/mindplay-dk/timber.svg)](https://travis-ci.org/mindplay-dk/timber)
+[![PHP Version](https://img.shields.io/badge/php-8.0%2B-blue.svg)](https://packagist.org/packages/mindplay/timber)
+[![Build status](https://github.com/mindplay-dk/timber/actions/workflows/ci.yml/badge.svg)
 
-Timber is a request router with regular expression support, high performance, and a
+Timber is a router library with regular expression support, high performance, and a
 developer-friendly, human-readable API.
 
-Originally a fork of [TreeRoute](https://github.com/baryshev/TreeRoute) by
-[Vadim Baryshev](https://github.com/baryshev), the API and feature-set quickly
-grew into something else entirely. What does carry over from the original fork,
-is great performance.
-
 
 ## Installation
 
@@ -19,28 +14,22 @@ Install the latest version with `composer require mindplay/timber`
 
 ## Introduction
 
-The core router system is independent of some other optional features - this includes
-a Dispatcher and a UrlHelper, both of which work great together with the router, but
-the router itself is not dependent on either of these components.
+This package provides a minimal router facility: a place to register path patterns, and
+a means of resolving these to controller names.
 
 
 ## Usage
 
 In the examples below, we assume that handlers (attached using `get()`, `post()`, etc.)
-are controller class-names - the included Dispatcher (see below) uses a class-per-action
-strategy, which may not be everyone's cup of tea, but the point is that, the meaning or
-interpretation of the handler string isn't baked into the router; it's supported by the
-Dispatcher only, and as such, you can easily implement any convention or strategy you
-like, either by doing your own dispatch (without using our Dispatcher) or by extending
-the Dispatcher and overriding the `toCallable()` function.
+are controller class-names - in your application, they might be component IDs for a DI
+container, file-names, or whatever else you like.
 
-Note the use of the magic `::class` constant in the following examples - the library is
-compatible with PHP 5.4, but this syntax is only supported by PHP 5.5 and up.
-
-Basic usage of the router, without Dispatcher, goes a little something like this:
+Basic usage of the router looks like this:
 
 ```PHP
 use mindplay\timber\Router;
+use mindplay\timber\Result;
+use mindplay\timber\Error;
 
 require __DIR__ . '/vendor/autoload.php';
 
@@ -71,28 +60,17 @@ $url = '/news/1';
 
 $result = $router->resolve($method, $url);
 
-if (!$result->error) {
-    $handler = $result->handler;
-    $params = $result->params;
-    // Do something with handler and params
+if ($result instanceof Error) {
+    header("HTTP/1.1 {$result->status} ${result->message}");
+    // ...error response here...
+    return;
 } else {
-    switch ($result->error->code) {
-        case 404 :
-            // Not found handler here
-            break;
-        case 405 :
-            // Method not allowed handler here
-            $allowedMethods = $result->error->allowed;
-            if ($method == 'OPTIONS') {
-                // OPTIONS method handler here
-            }
-            break;
-    }
+    // ...dispatch $result->handler with $result->params...
 }
 ```
 
-If you're building a set of routes under the same parent route, you can continue routing
-from by keeping a temporary reference to a parent route - for example:
+If you're building a set of routes under the same parent route, you can continue building
+from a parent route - for example:
 
 ```PHP
 $admin = $router->route('admin')->get(AdminMenu::class);
@@ -103,8 +81,7 @@ $admin->route('groups')->get(AdminGroupList::class);
 
 This example will route `/admin` to `AdminMenu`, and `/admin/users` to `AdminUserList`, etc.
 
-Continuing from a parent route avoids the overhead of repeatedly parsing the same parent path,
-and also enables modular reuse of route definitions - for example:
+This also feature enables modular reuse of route definitions - for example:
 
 ```PHP
 $build_comment_routes = function (Route $parent) {
@@ -120,43 +97,6 @@ This example creates two identical sets of routes for displaying and posting com
 different parent routes.
 
 
-### Dispatch
-
-We also provide a [Dispatcher](src/Dispatcher.php) class and [Controller](src/Controller.php)
-interface, following a simple convention of handler names being class-names, and a
-class-per-action strategy:
-
-```PHP
-use mindplay\timber\Router;
-use mindplay\timber\Controller;
-use mindplay\timber\Dispatcher;
-
-class ShowNews implements Controller
-{
-    public function run($id) {
-        // load and display news article...
-    }
-}
-
-$router = new Router();
-$router->route('news/<id:int>', ShowNews::class);
-
-$dispatcher = new Dispatcher($router);
-
-$dispatcher->run('GET', '/news');
-```
-
-The named parameter in this example will be converted to an integer and provided
-to the `run()` method.
-
-
-### URL Creation
-
-In addition, we provide a [base class for URL creation helpers](src/UrlHelper.php) -
-this has no direct relationship with the router as such, it's provided for
-convenience, to support our overall strategy of creating testable URL helpers.
-
-
 ## Optimization
 
 You can save and restore the defined routes:
@@ -218,3 +158,10 @@ after some discussion, we decided URL creation provides only a small benefit, gu
 is consistent with defined patterns; but also, we value the freedom to fully customize URL creation on a
 case-by-case basis using simpler code (as per [case 3](https://gist.github.com/mindplay-dk/feb4768dbb118c651ba0#file-router-3-php))
 and as such the absence of URL creation can actually be seen as a benefit.
+
+## Acknowledgements
+
+Timber started as a fork of [TreeRoute](https://github.com/baryshev/TreeRoute) by
+[Vadim Baryshev](https://github.com/baryshev), the API and feature-set quickly
+grew into something else entirely. What does carry over from the original fork,
+is great performance.

UPGRADING.md

@@ -0,0 +1,30 @@
+## Upgrade Notes
+
+### `2.x` to `3.x`
+
+Version 3 doesn't really attempt to be backwards compatible - I haven't been actively
+using PHP for some years, so this release is a revived and modernized package for PHP 8,
+with a smaller scope.
+
+Earlier versions of this package came with a Dispatcher and a URL builder, both of which
+have been removed from version `3.0.0` of this package:
+
+- The Dispatcher had no real connection with the Router itself, and was more like a
+  proof of concept than a full-blown implementation - if you wish to upgrade to `3.0.0`,
+  you can copy the dispatcher from the
+  [old version](https://github.com/mindplay-dk/timber/blob/6defdfaea55bb59171b54a9abcf388e836e18e66/src/Dispatcher.php)
+  and use this as a basis for your own dispatcher.
+
+- The URL builder also had no direct connection with the Router, as has been removed -
+  you can find third-party packages on Packagist specifically for this purpose.
+
+Major breaking changes:
+
+- `Router::resolve()` now returns a union type of either `Result` or `Error`.
+- `Registry` is now called `PatternRegistry`, and `Symbol` is called `Pattern`.
+
+Minor breaking changes:
+
+- Static type-hints were added.
+
+Other than that, what remains is more or less the same.

composer.json

@@ -7,23 +7,19 @@
     ],
     "license": "BSD-3-Clause",
     "authors": [
-        {
-            "name": "Vadim Baryshev",
-            "email": "vadimbaryshev@gmail.com"
-        },
         {
             "name": "Rasmus Schultz",
             "email": "rasmus@mindplay.dk"
         }
     ],
     "require": {
-        "php": "^7.3 || ^8.0"
+        "php": "^8.0"
     },
     "require-dev": {
-        "mindplay/testies": "^1.0"
+        "mindplay/testies": "^1.1.2"
     },
-    "suggest": {
-        "ext-intl": "provides better/faster support for slug-creation in URL helpers"
+    "scripts": {
+        "test": "php test/test.php"
     },
     "autoload": {
         "psr-4": {