Merge pull request #3 from nimbly/3.0

Merge 3.0 into Master

.github/workflows/php.yml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php-version: [8.0, 8.1, 8.2, 8.3]
+        php-version: [8.2, 8.3]
 
     runs-on: ubuntu-latest
 

.gitignore

@@ -2,4 +2,5 @@ vendor/
 build/
 .vscode/
 composer.lock
-.phpunit.result.cache
+.phpunit.result.cache
+test.php

.travis.yml

@@ -0,0 +1,15 @@
+language: php
+php:
+  - 8.0
+  - 8.1
+  - 8.2
+
+install:
+  - composer install
+
+script:
+  - make analyze
+  - make coverage
+
+after_success:
+  - travis_retry php vendor/bin/php-coveralls

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 nimbly.io
+Copyright (c) 2024 nimbly.io
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile

@@ -4,8 +4,5 @@ test:
 coverage:
 	php -d xdebug.mode=coverage vendor/bin/phpunit --coverage-clover=build/logs/clover.xml
 
-mutation:
-	vendor/bin/infection
-
 analyze:
 	vendor/bin/psalm

README.md

@@ -18,7 +18,7 @@ Limber is intended for advanced users who are comfortable setting up their own f
 
 ## Requirements
 
-* PHP 8.0+
+* PHP 8.2+
 * PSR-7 HTTP Message library
 
 ## Installation
@@ -42,9 +42,15 @@ Limber does not ship with a PSR-7 implementation which is required to receive HT
 composer require nimbly/capsule
 ```
 
-### Entry point
+### Sample application
 
-Create your entrypoint (or front controller), for example `index.php`:
+1. Create your entrypoint (or front controller), for example `index.php`, and start by creating a new `Router` instance and attaching your routes to it.
+
+2. Once your routes have been defined, you can create the `Application` instance and pass the router in to it.
+
+3. You can then `dispatch` requests through the application and receive a response back.
+
+4. And finally, you can `send` a response back to the calling client.
 
 ```php
 <?php
@@ -71,12 +77,10 @@ $application->send($response);
 
 ### A note on autowiring support
 
-Limber will invoke your route handlers using reflection based autowiring. The `ServerRequestInterface` instance and any URI path parameters defined in the route will be automatically resolved for you, without the need of a PSR-11 container.
+Limber will invoke your route handlers using reflection based autowiring. The `ServerRequestInterface` instance, URI path parameters defined in the route, and request attributes will be automatically resolved for you, without the need of a PSR-11 container.
 
 However, any domain specific services and classes that are required in your handlers, should be defined in a PSR-11 container instance.
 
-**NOTE:** *Union type autowiring is currently not supported.*
-
 ### Adding PSR-11 container support
 
 Limber is able to autowire your request handlers and middleware with the aid of a PSR-11 container instance. However, Limber *does not ship* with a PSR-11 Container implementation, so you will need to bring your own if you require one. Here are some options:
@@ -119,7 +123,7 @@ You can pass middleware as one or more of the following types:
 * A `class-string` that implements `MiddlewareInterface`
 * A `class-string` that implements `MiddlewareInterface` as an index and an array of key=>value pairs as parameters to be used in dependency injection when autowiring.
 
-Any `class-string` types will be auto wired using the `Container` instance (if any) for dependency injection.
+Any `class-string` types will be autowired using the `Container` instance (if any) for dependency injection.
 
 If auto wiring fails, a `DependencyResolutionException` exception will be thrown.
 
@@ -212,7 +216,7 @@ $application = new Nimbly\Limber\Application(
 
 ## Router
 
-The `Router` builds and collects `Route` instances and provides helper methods to group `Routes` together sharing a common configuration (prefix, namespace, middleware, etc).
+The `Router` builds and collects `Route` instances and provides helper methods to group `Routes` together sharing a common configuration (path prefix, namespace, middleware, etc).
 
 ### Defining routes
 
@@ -226,7 +230,7 @@ $router->patch("/fruits/{id}", "FruitsHandler@update");
 $router->delete("/fruits/{id}", "FruitsHandler@delete");
 ```
 
-A route can respond to any number of HTTP methods by using the `add` method and passing an array the methods as strings.
+A route can respond to any number of HTTP methods by using the `add` method and passing an array of methods as strings.
 
 ```php
 $router->add(["get", "post"], "/fruits", "FruitsHandler@create");
@@ -294,13 +298,13 @@ $router->get("/books/{id:isbn}", "BooksHandler@getByIsbn");
 
 ### Route handlers
 
-Route handlers may either be a `\callable` or a string in the format **Fully\Qualified\Namespace\ClassName@Method** (for example `App\Handlers\v1\BooksHandler@create`).
+Route handlers may either be a `callable` or a string in the format **Fully\Qualified\Namespace\ClassName@Method** (for example `App\Handlers\v1\BooksHandler@create`).
 
 Route handlers *must* return a `ResponseInterface` instance.
 
-Limber uses reflection based autowiring to automatically resolve your route handler's parameters - including the `ServerRequestInterface` instance and any path parameters. This applies for both closure based handlers as well as **Class@Method** based handlers.
+Limber uses reflection based autowiring to automatically resolve your route handlers including constructor and function/method parameters. The `ServerRequestInterface` instance, path parameters, and any attributes attached to the  `ServerRequestInterface` instance will be resolved and injected for you. This applies for both closure based handlers as well as **Class@Method** based handlers.
 
-You may also optionally supply a PSR-11 compliant `ContainerInterface` instance to aid in route handler resolution. By doing this, you can easily have your application specific dependencies resolved and injected into your handlers by Limber. See **PSR-11 Container support** section for more information.
+You may also optionally supply a PSR-11 compliant `ContainerInterface` instance to aid in route handler parameter resolution. By doing this, you can easily have your application specific dependencies resolved and injected into your handlers by Limber. See **PSR-11 Container support** section for more information.
 
 ```php
 // Closure based handler
@@ -313,9 +317,7 @@ $router->get(
 			throw new NotFoundHttpException("Book not found.");
 		}
 
-		return new Response(
-			\json_encode($book)
-		);
+		return new Response(200, \json_encode($book));
 	}
 );
 
@@ -326,13 +328,11 @@ $router->patch("/books/{id:isbn}", "App\Handlers\BooksHandler@update");
 $router->post(
 	"/books",
 	function(ServerRequestInterface $request, InventoryService $inventoryService): ResponseInterface {
-		$book = Book::make($request->getAll());
+		$book = Book::make($request->getParsedBody());
 
 		$inventoryService->add($book);
 
-		return new Response(
-			\json_encode($book)
-		);
+		return new Response(201, \json_encode($book));
 	}
 );
 ```
@@ -387,12 +387,13 @@ $router->post(
 
 You can group routes together using the `group` method and all routes contained will inherit the configuration you have defined.
 
-* `scheme` *string* The HTTP scheme (http or https) to match against.
-* `middleware` *array&lt;string&gt;* or *array&lt;MiddlewareInterface&gt;* or *array&lt;callable&gt;* An array of all middleware classes (fullname space) or actual instances of middleware.
-* `prefix` *string* A string prepended to all URIs when matching the request.
-* `namespace` *string* A string prepended to all string based handlers before instantiating a new class.
-* `hostnames` *string* A host name to be matched against.
-* `attributes` *array&lt;string,mixed&gt;* An array of key=>value pairs representing attributes that will be attached to the `ServerRequestInterface` instance if the route matches.
+* `scheme` (optional) *string* The HTTP scheme (`http` or `https`) to match against. A `null` value will match against any value.
+* `middleware` (optional) *array&lt;string&gt;* or *array&lt;MiddlewareInterface&gt;* or *array&lt;callable&gt;* An array of all middleware classes (fully qualified namespace) or actual instances of middleware.
+* `prefix` (optional) *string* A string prepended to all URIs when matching the request.
+* `namespace` (optional) *string* A string prepended to all string based handlers before instantiating a new class.
+* `hostnames` (optional) *array&lt;string&gt;* An array of hostnames to be matched against.
+* `attributes` (optional) *array&lt;string,mixed&gt;* An array of key=>value pairs representing attributes that will be attached to the `ServerRequestInterface` instance if the route matches.
+* `routes` (required) *callable* A callable that accepts the `Router` instance where you can add additional routes within the group.
 
 ```php
 $router->group(
@@ -440,6 +441,7 @@ $router->group(
 	}
 );
 ```
+
 ## Using with React/Http
 
 Because Limber is PSR-7 compliant, it works very well with [react/http](https://github.com/reactphp/http) to create a standalone HTTP service without the need for an additional HTTP server (nginx, Apache, etc) - great for containerizing your service with minimal dependencies.

composer.json

@@ -4,10 +4,11 @@
     "keywords": ["php", "http", "rest", "api", "framework", "middleware"],
     "type": "library",
     "require": {
-        "php": ">=8.0",
+        "php": "^8.2",
         "psr/http-message": "^1.0",
 		"psr/http-server-middleware": "^1.0",
-        "psr/container": "^1.0||^2.0"
+        "psr/container": "^1.0||^2.0",
+        "nimbly/resolve": "^2.0"
     },
     "license": "MIT",
     "authors": [
@@ -22,15 +23,18 @@
         }
     },
     "require-dev": {
+		"ext-xdebug": "*",
         "phpunit/phpunit": "^9.0",
         "vimeo/psalm": "^5.0",
         "symfony/var-dumper": "^4.2",
         "nimbly/capsule": "^2.0",
-        "nimbly/carton": "^2.0"
+        "nimbly/carton": "^2.0",
+        "fakerphp/faker": "^1.20"
     },
     "autoload-dev": {
         "psr-4": {
-            "Nimbly\\Limber\\Tests\\": "tests/"
+            "Nimbly\\Limber\\Tests\\": "tests/",
+			"Nimbly\\Limber\\Examples\\": "examples/"
         }
     }
 }

phpunit.xml

@@ -1,5 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd" bootstrap="vendor/autoload.php" executionOrder="depends,defects" forceCoversAnnotation="true" beStrictAboutCoversAnnotation="true" beStrictAboutOutputDuringTests="true" beStrictAboutTodoAnnotatedTests="true" colors="true" verbose="true">
+<phpunit
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd"
+	bootstrap="vendor/autoload.php"
+	executionOrder="depends,defects"
+	forceCoversAnnotation="true"
+	beStrictAboutCoversAnnotation="false"
+	beStrictAboutOutputDuringTests="true"
+	beStrictAboutTodoAnnotatedTests="true"
+	colors="true"
+	verbose="true">
   <coverage processUncoveredFiles="true">
     <include>
       <directory suffix=".php">src</directory>