Added explanation of setup and result processing callbacks. Added Htm…

…l example.
Danack · Sep 4, 2017 · d862b5d · d862b5d
1 parent 71b0b57
commit d862b5d
Show file tree

Hide file tree

Showing 10 changed files with 196 additions and 50 deletions.
diff --git a/example/index.php b/example/index.php
diff --git a/example/lib/Danack/SlimAurynExample/HtmlController.php b/example/lib/Danack/SlimAurynExample/HtmlController.php
@@ -0,0 +1,13 @@
+<?php
+
+namespace Danack\SlimAurynExample;
+
+use Twig_Environment as Twig;
+
+class HtmlController
+{
+    public function getPage(Twig $twig) : string
+    {
+        return $twig->render('string_example.html');
+    }
+}
diff --git a/.../lib/Danack/SlimAurynExample/HomePage.php → ...k/SlimAurynExample/ResponseController.php b/.../lib/Danack/SlimAurynExample/HomePage.php → ...k/SlimAurynExample/ResponseController.php
@@ -5,7 +5,7 @@
 use Danack\Response\HtmlResponse;
 use Twig_Environment as Twig;
 
-class HomePage
+class ResponseController
 {
     public function getHomePage(Twig $twig)
     {

diff --git a/example/public/index.php b/example/public/index.php
@@ -1,3 +1,35 @@
 <?php
 
-require __DIR__ . '/../index.php';
+use Danack\SlimAurynInvoker\SlimAurynInvokerFactory;
+
+error_reporting(E_ALL);
+
+require_once __DIR__ . "/../../vendor/autoload.php";
+require_once __DIR__ . '/../functions.php';
+require_once __DIR__ . '/../injectionParams.php';
+require_once __DIR__ . '/../routes.php';
+
+set_error_handler('saneErrorHandler');
+
+// Setup the Injector
+$injector = new Auryn\Injector();
+$injectionParams = injectionParams();
+$injectionParams->addToInjector($injector);
+$injector->share($injector);
+
+// Add any custom rules you'd like to the injector here, or in
+// the injectionParams.php file.
+
+// Create the app with the container set to use SlimAurynInvoker
+// for the 'foundHandler'.
+$container = new \Slim\Container;
+$container['foundHandler'] = new SlimAurynInvokerFactory($injector);
+$app = new \Slim\App($container);
+
+// Configure any middlewares here.
+
+// Setup the routes for the app
+setupBasicRoutes($app);
+
+// Run!
+$app->run();
diff --git a/example/public/index_html.php b/example/public/index_html.php
@@ -0,0 +1,52 @@
+<?php
+
+use Danack\SlimAurynInvoker\SlimAurynInvokerFactory;
+use Psr\Http\Message\ResponseInterface;
+
+error_reporting(E_ALL);
+
+require_once __DIR__ . "/../../vendor/autoload.php";
+require_once __DIR__ . '/../functions.php';
+require_once __DIR__ . '/../injectionParams.php';
+require_once __DIR__ . '/../routes.php';
+
+set_error_handler('saneErrorHandler');
+
+// Setup the Injector
+$injector = new Auryn\Injector();
+$injectionParams = injectionParams();
+$injectionParams->addToInjector($injector);
+$injector->share($injector);
+
+// Add any custom rules you'd like to the injector here, or in
+// the injectionParams.php file.
+
+// Create a container, so that we can setup
+$container = new \Slim\Container;
+
+// Define a function that writes a string into the response object.
+$convertStringToHtmlResponse = function(string $result, ResponseInterface $response) {
+    $response = $response->withHeader('Content-Type', 'text/html');
+    $response->getBody()->write($result);
+    return $response;
+};
+
+// Create a single result mapper, to convert strings returned from a controller
+// into a Psr 7 response with the content-type set.
+$resultMappers = [
+    'string' => $convertStringToHtmlResponse
+];
+
+$container['foundHandler'] = new SlimAurynInvokerFactory($injector, $resultMappers);
+
+// Create the app with the container set to use SlimAurynInvoker
+// for the 'foundHandler'.
+$app = new \Slim\App($container);
+
+// Configure any middlewares here.
+
+// Setup the routes for the app
+setupHtmlRoutes($app);
+
+// Run!
+$app->run();
diff --git a/example/routes.php b/example/routes.php
@@ -2,10 +2,24 @@
 
 use Slim\App;
 
-function setupRoutes(App $app)
+function setupBasicRoutes(App $app)
 {
     $routes = [
-        ['/', 'GET', 'Danack\SlimAurynExample\HomePage::getHomePage'],
+        ['/', 'GET', 'Danack\SlimAurynExample\ResponseController::getHomePage'],
+    ];
+
+    foreach ($routes as $route) {
+        list($path, $method, $callable) = $route;
+        $app->{$method}($path, $callable);
+    }
+}
+
+
+
+function setupHtmlRoutes(App $app)
+{
+    $routes = [
+        ['/', 'GET', 'Danack\SlimAurynExample\HtmlController::getPage'],
     ];
 
     foreach ($routes as $route) {

diff --git a/example/templates/hompage.html b/example/templates/hompage.html
@@ -1,10 +1,14 @@
-
-
 <html>
 
 <body>
 
+<p>
 This is the homepage test.
+</p>
+<p>
+  This controller returns a stub HtmlResponse, which gets written into the Psr 7 response by the Slim Auryn Invoker library.
+
+</p>
 
 </body>
 

diff --git a/example/templates/string_example.html b/example/templates/string_example.html
@@ -0,0 +1,15 @@
+<html>
+
+<body>
+
+<p>
+This is the string controller test.
+</p>
+
+<p>
+  The controller used for this example is simply returning a string which is being converted into a HTML response by a 'resultMapper' in the SlimAurynInvoker.
+</p>
+
+</body>
+
+</html>
diff --git a/lib/Danack/SlimAurynInvoker/SlimAurynInvoker.php b/lib/Danack/SlimAurynInvoker/SlimAurynInvoker.php
@@ -32,10 +32,17 @@ public function __construct(
         if ($resultMappers !== null) {
             $this->resultMappers = $resultMappers;
         }
-        // Default to using a single StubResponse mapper.
+        // Default to using: i) a StubResponse mapper, ii) if a PSR response is
+        // returned, just pass that back.
         else {
             $this->resultMappers = [
-                StubResponse::class => [StubResponseMapper::class, 'mapToPsr7Response']
+                StubResponse::class => [StubResponseMapper::class, 'mapToPsr7Response'],
+                ResponseInterface::class => function (
+                    ResponseInterface $controllerResult,
+                    ResponseInterface $originalResponse
+                ) {
+                    return $controllerResult;
+                }
             ];
         }
 
@@ -75,19 +82,13 @@ public function __invoke(
             }
         }
 
-        // if the result is a mutated PSR response object, just return that.
-        if ($result instanceof ResponseInterface) {
-            return $result;
-        }
-
         // Unknown result type, throw an exception
         $type = gettype($result);
         if ($type === "object") {
             $type = "object of type ". get_class($result);
         }
         $message = sprintf(
-            'Dispatched function returned [%s] which is not a".
-            "\Psr\Http\Message\ResponseInterface, or any type known to the resultMappers.',
+            'Dispatched function returned [%s] which is not a type known to the resultMappers.',
             $type
         );
         throw new SlimAurynInvokerException($message);

diff --git a/readme.MD b/readme.MD
@@ -76,6 +76,54 @@ By returning a stub response object, it not only remove a lot of tedious, fiddly
 * Manage the details of which headers are sent for which response type in one place, rather than having to alter every controller that returns that type.
 * Test your controllers are returning the correct data type.
 
+
+## Setup and result processing
+
+The steps before and after the controller is dispatched can be controlled by the user. By default the steps are defined as follows: 
+
+### Setting up before the controller is dispatched
+
+By default the SlimAurynInvoker does these actions.
+
+* Shares the request object through the injector, so that controllers can have it as a dependency.
+* Shares the response object through the injector, so that controllers can have it as a dependency.
+* Defines the route parameters as named parameters so that controllers can have the route arguments as dependencies by name.
+* Creates and shares a \Danack\SlimAurynInvoker\RouteParams object to that controllers can have the route pamaters as a dependency by type.
+
+
+### Result processing
+
+By default after dispatching the controller, the SlimAurynInvoker will: 
+
+* If an object of type \Danack\Response\StubResponse was returned by the controller, the SlimAurynInvoker will [map it into the Psr 7 response object](https://github.com/Danack/SlimAurynInvoker/blob/71b0b5760e05e0abbab77aad2f94a6a58625afd9/lib/Danack/Response/StubResponseMapper.php#L19-L29).
+
+* If an object of type Psr 7 Response is returned, SlimAurynInvoker will just pass it back to Slim.
+
+
+### Customising the setup and result processing
+
+If you want to customise either the setup or result processing functionality, you can do that by passing appropriate callables as the $resultMappers and/or $setupFunction into the \Danack\SlimAurynInvoker\SlimAurynInvokerFactory.
+
+
+The resultMapper array should be an array, where the keys are the types that are returned by the controller, and the values are callables, with the signature:
+
+```
+function ($builtResponse, ResponseInterface $response);
+```
+
+A setup callable should have this signature:
+
+```
+function(
+        Injector $injector,
+        ServerRequestInterface $request,
+        ResponseInterface $response,
+        array $routeArguments
+    );
+```
+
+An example that show an alternative resultMapper is in the file ./example/public/index_html.php. It shows how you can configure the SlimAurynInvoker, so that each controller can just return a string, which automatically gets sent as a HTML response.
+
 ## Running the example
 
 There is a simple example app in the example folder, which can be run by using PHP's built-in webserver. You can run it by running this:
@@ -86,6 +134,8 @@ php -S 0.0.0.0:8000 -t example/public
 
 in the root directory of this library, and then going to http://127.0.0.1:8000/ in your browser.
 
+Additionally, there is an example of a controller returning just a string, which is mapped into a HTML response at http://127.0.0.1:8000/index_html.php
+
 
 ## Notes