Response mapping

Author: maxbeckers

README.md

@@ -1,2 +1,76 @@
-# Amazon alexa php library
-This library is a helper for google actions with php.
+# Google actions php library
+This library is a helper for google actions with php.
+
+## Install via composer
+Require the package with composer:
+```
+composer require maxbeckers/google-actions-php
+```
+
+## Usage
+Handle the request: 
+- map request data to request object
+- validate request
+- handle request data
+- create response
+- send response
+
+### Map request data to request object
+Map needed request headers and request body to `Request`.
+```php
+use MaxBeckers\GoogleActions\Request\Request;
+...
+$requestBody  = file_get_contents('php://input');
+$googleRequest = Request::fromGoogleRequest($requestBody);
+```
+### Validate request
+The `RequestValidator` will handle the google request validation.
+```php
+use MaxBeckers\GoogleActions\Validation\RequestValidator;
+...
+$validator = new RequestValidator();
+$validator->validate($googleRequest);
+```
+### Register request handlers
+For different requests it's helpful to create different RequestHandlers.
+```php
+use MaxBeckers\GoogleActions\RequestHandler\RequestHandlerRegistry;
+...
+$requestHandlerRegistry = new RequestHandlerRegistry();
+$requestHandlerRegistry->addHandler($myRequestHandler);
+```
+### Use registry to handle request
+```php
+use MaxBeckers\GoogleActions\RequestHandler\RequestHandlerRegistry;
+...
+$requestHandler = $requestHandlerRegistry->getSupportingHandler($googleRequest);
+$response       = $requestHandler->handleRequest($googleRequest);
+```
+### Render response
+```php
+header('Content-Type: application/json');
+echo json_encode($response);
+exit();
+```
+### Create a new request handler
+The new request handler must extend `AbstractRequestHandler`.
+First implement the abstract `supportsRequest`-method.
+```php
+public function supportsRequest(Request $request): bool
+{
+    return true; // check request data
+}
+```
+Then implement the `handleRequest`-method. For simple responses there is a `ResponseHelper`.
+```php
+use MaxBeckers\GoogleActions\Helper\ResponseHelper;
+...
+/** @var ResponseHelper */
+private $responseHelper;
+...
+public function handleRequest(Request $request): Response
+{
+    // todo set needed response data
+    return $responseHelper->respond('Success :)');
+}
+```

composer.json

@@ -5,6 +5,7 @@
   "keywords": [
     "google",
     "actions",
+    "home",
     "php"
   ],
   "license": "MIT",

examples/Handlers/SimpleRequestHandler.php

@@ -0,0 +1,36 @@
+<?php
+
+use MaxBeckers\GoogleActions\Helper\ResponseHelper;
+use MaxBeckers\GoogleActions\Request\Request;
+use MaxBeckers\GoogleActions\RequestHandler\AbstractRequestHandler;
+use MaxBeckers\GoogleActions\Response\Response;
+
+/**
+ * Just a simple example request handler.
+ *
+ * @author Maximilian Beckers <[email protected]>
+ */
+class SimpleRequestHandler extends AbstractRequestHandler
+{
+    /**
+     * @var ResponseHelper
+     */
+    private $responseHelper;
+
+    /**
+     * {@inheritdoc}
+     */
+    public function supportsRequest(Request $request): bool
+    {
+        // support all  requests, should not be done.
+        return true;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function handleRequest(Request $request): Response
+    {
+        return $this->responseHelper->respond('Success :)');
+    }
+}

examples/simple-request.php

@@ -1,16 +1,26 @@
 <?php
 
 use MaxBeckers\GoogleActions\Request\Request;
-use MaxBeckers\GoogleActions\Response\Response;
+use MaxBeckers\GoogleActions\RequestHandler\RequestHandlerRegistry;
+use MaxBeckers\GoogleActions\Validation\RequestValidator;
 
 require '../vendor/autoload.php';
+require 'Handlers/SimpleRequestHandler.php';
 
 $requestBody = file_get_contents('php://input');
 if ($requestBody) {
-    $alexaRequest = Request::fromGoogleRequest($requestBody);
+    $googleRequest = Request::fromGoogleRequest($requestBody);
 
-    // todo generate response
-    $response = new Response();
+    // Request validation
+    $validator = new RequestValidator();
+    $validator->validate($googleRequest);
+
+    // add handlers to registry
+    $mySimpleRequestHandler = new SimpleRequestHandler();
+    $requestHandlerRegistry = new RequestHandlerRegistry();
+    $requestHandlerRegistry->addHandler($mySimpleRequestHandler);
+
+    $response = $requestHandlerRegistry->getSupportingHandler($googleRequest)->handleRequest($googleRequest);
     // render response
     header('Content-Type: application/json');
     echo json_encode($response);

src/Exception/InvalidRequestException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace MaxBeckers\GoogleActions\Exception;
+
+/**
+ * @author Maximilian Beckers <[email protected]>
+ */
+class InvalidRequestException extends \Exception
+{
+}

src/Exception/MissingRequestHandlerException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace MaxBeckers\GoogleActions\Exception;
+
+/**
+ * @author Maximilian Beckers <[email protected]>
+ */
+class MissingRequestHandlerException extends \Exception
+{
+}

src/Helper/ResponseHelper.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace MaxBeckers\GoogleActions\Helper;
+
+use MaxBeckers\GoogleActions\Response\ExpectedIntent;
+use MaxBeckers\GoogleActions\Response\InputPrompt;
+use MaxBeckers\GoogleActions\Response\Item;
+use MaxBeckers\GoogleActions\Response\Response;
+use MaxBeckers\GoogleActions\Response\ExpectedInput;
+use MaxBeckers\GoogleActions\Response\RichResponse;
+use MaxBeckers\GoogleActions\Response\SimpleResponse;
+
+/**
+ * @author Maximilian Beckers <[email protected]>
+ */
+class ResponseHelper
+{
+
+    /**
+     * @var Response
+     */
+    public $response;
+
+    /**
+     * ResponseHelper constructor creates a new response object.
+     */
+    public function __construct()
+    {
+        $this->response = new Response();
+    }
+
+    /**
+     * @param string $text
+     *
+     * @return Response
+     */
+    public function respond(string $text): Response
+    {
+        $simpleResponse                 = new SimpleResponse();
+        $simpleResponse->textToSpeech   = $text;
+        $simpleResponse->displayText    = $text;
+        $item                           = new Item();
+        $item->simpleResponse           = $simpleResponse;
+        $richInitialPrompt              = new RichResponse();
+        $richInitialPrompt->items[]     = $item;
+        $inputPrompt                    = new InputPrompt();
+        $inputPrompt->richInitialPrompt = $richInitialPrompt;
+
+        $intent         = new ExpectedIntent();
+        $intent->intent = ExpectedIntent::TYPE_TEXT;
+
+        $expectedInput                    = new ExpectedInput();
+        $expectedInput->inputPrompt       = $inputPrompt;
+        $expectedInput->possibleIntents[] = $intent;
+
+        $this->response->expectedInputs[] = $expectedInput;
+
+        return $this->response;
+    }
+}

src/RequestHandler/AbstractRequestHandler.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace MaxBeckers\GoogleActions\RequestHandler;
+
+use MaxBeckers\GoogleActions\Request\Request;
+use MaxBeckers\GoogleActions\Response\Response;
+
+/**
+ * @author Maximilian Beckers <[email protected]>
+ */
+abstract class AbstractRequestHandler
+{
+    /**
+     * Check if the request handler can handle given request.
+     *
+     * @param Request $request
+     *
+     * @return bool
+     */
+    public abstract function supportsRequest(Request $request): bool;
+
+    /**
+     * Handle the given request end return a response object.
+     *
+     * @param Request $request
+     *
+     * @return Response
+     */
+    public abstract function handleRequest(Request $request): Response;
+}

src/RequestHandler/RequestHandlerRegistry.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace MaxBeckers\GoogleActions\RequestHandler;
+
+use MaxBeckers\GoogleActions\Exception\MissingRequestHandlerException;
+use MaxBeckers\GoogleActions\Request\Request;
+
+/**
+ * @author Maximilian Beckers <[email protected]>
+ */
+class RequestHandlerRegistry
+{
+    /**
+     * @var AbstractRequestHandler[]
+     */
+    private $requestHandlers = [];
+
+    /**
+     * @param Request $request
+     *
+     * @throws MissingRequestHandlerException
+     *
+     * @return AbstractRequestHandler
+     */
+    public function getSupportingHandler(Request $request): AbstractRequestHandler
+    {
+        foreach ($this->requestHandlers as $requestHandler) {
+            if ($requestHandler->supportsRequest($request)) {
+                return $requestHandler;
+            }
+        }
+
+        throw new MissingRequestHandlerException();
+    }
+
+    /**
+     * @param AbstractRequestHandler $handler
+     */
+    public function addHandler(AbstractRequestHandler $handler)
+    {
+        $this->requestHandlers[] = $handler;
+    }
+}

src/Response/Action.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace MaxBeckers\GoogleActions\Response;
+
+/**
+ * @author Maximilian Beckers <[email protected]>
+ */
+class Action
+{
+    const TYPE_UNKNOWN          = 'UNKNOWN';
+    const TYPE_VIEW_DETAILS     = 'VIEW_DETAILS';
+    const TYPE_MODIFY           = 'MODIFY';
+    const TYPE_CANCEL           = 'CANCEL';
+    const TYPE_RETURN           = 'RETURN';
+    const TYPE_EXCHANGE         = 'EXCHANGE';
+    const TYPE_EMAIL            = 'EMAIL';
+    const TYPE_CALL             = 'CALL';
+    const TYPE_REORDER          = 'REORDER';
+    const TYPE_REVIEW           = 'REVIEW';
+    const TYPE_CUSTOMER_SERVICE = 'CUSTOMER_SERVICE';
+
+    /**
+     * @var string|null
+     */
+    public $type;
+
+    /**
+     * @var Button|null
+     */
+    public $button;
+}

src/Response/BasicCard.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace MaxBeckers\GoogleActions\Response;
+
+/**
+ * @author Maximilian Beckers <[email protected]>
+ */
+class BasicCard
+{
+    /**
+     * @var string|null
+     */
+    public $title;
+
+    /**
+     * @var string|null
+     */
+    public $subtitle;
+
+    /**
+     * @var string|null
+     */
+    public $formattedText;
+
+    /**
+     * @var Image|null
+     */
+    public $image;
+
+    /**
+     * @var Button[]
+     */
+    public $buttons = [];
+}