iansltx / dialogflow-bridge
A set of middlewares + helpers for responding to Dialogflow web hooks
Requires
- php: >=7.1
- http-interop/http-server-middleware: ^1.0
- psr/container: ^1.0
- psr/http-message: ^1.0
This package is auto-updated.
Last update: 2024-11-06 18:20:52 UTC
README
A middleware + helper objects for responding to Dialogflow webhooks.
Requirements + Installation
To take full advantage of this library, you'll need:
- A PSR-11 (formerly Container Interop) compatible container to pull dependencies from.
- A framework that either uses double-pass middlewares (e.g. Slim 3) or the proposed PSR-15 middleware (e.g. Zend Expressive 2.0+), using PSR-7 requests and responses, to use the middleware component.
To install, use Composer:
composer require iansltx/dialogflow-bridge
Getting Started
The easiest way to integrate this library is by adding it as a route middleware to a supported (micro)framework. For example, with Slim 3:
<?php use iansltx\DialogflowBridge\{Middleware, Router, Question, Answer}; // require Composer autoloader here $app = new Slim\App(); $app->post('/hook', new Middleware\DoublePass(Router::buildFromClosureArray([ 'hello' => function(Question $question, Answer $answer) : Answer { return $answer->withSpeechAndText("Hello {$question->getParam('name', 'world')}!"); } ]))); $app->run();
To see your new app in action, point Dialogflow's web hook configuration at /hook
on wherever you're hosting your app, create an intent with (or without) a name
parameter, set the action name on that intent to hello
, check the box to use
the Web Hook for fulfillment, then call your new intent.
Now, let's break down what just happened:
- Dialogflow called our web hook, which Slim routed to the
DoublePass
middleware. - That middleware handed the request off to the
Router
, which marshaledQuestion
andAnswer
classes. - the
Router
saw that theQuestion
had an action ofhello
, which matched one of the handlers passed to it, so it called the handler, getting anAnswer
back. - The
Router
passed theAnswer
back to the middleware, which updated the HTTPResponse
with the proper JSON payload.
Yu can learn more about each of these components later in this document.
Adding a Fallback
This library comes with a built-in, albeit generic, handler for when the action
on an incoming web hook request doesn't match anything in your route mapping.
The function signature is the same as a normal action handler, and any callable
(a class with __invoke()
, a Closure
, etc.) can be used here. Just pass the
callable as an additional parameter when creating your Router
. Tweaking the
previous example:
<?php use iansltx\DialogflowBridge\{Middleware, Router, Question, Answer}; // require Composer autoloader here $app = new Slim\App(); $app->post('/hook', new Middleware\DoublePass(Router::buildFromClosureArray([ 'hello' => function(Question $question, Answer $answer) : Answer { return $answer->withSpeechAndText("Hello {$question->getParam('name', 'world')}!"); } ], function (Question $question, Answer $answer) : Answer { return $answer->withSpeechAndText("Sorry, I'm not sure what to do here."); }))); $app->run();
As your application gets more copmlex, you'll want to start...
Managing Handler Dependencies
An array of anonymous functions is a quick way to start handling web hook requests,
but you'll probably want to put your handlers in your main application DI container
as your project grows. For this case, you'll want to use Router::build()
instead
of Router::buildFromClosureArray()
. build()
takes three parameters:
- An object that implements the PSR-11
ContainerInterface
(e.g. Slim 3's container) - An array of mappings between action names (as keys) and container keys (as values). This provides a whitelist so incoming requests aren't pulling random services out of the container, and allows you to map multiple action names to a single dependency if you like.
- The optional fallback callable.
Taking the previous example, but assuming we've now moved our "hello" handler into the container as "helloHandler", we'd end up with:
<?php use iansltx\DialogflowBridge\{Middleware, Router, Question, Answer}; // require Composer autoloader here $app = new Slim\App(); $app->post('/hook', new Middleware\DoublePass(Router::build($app->getContainer(), [ 'hello' => 'helloHandler' ], function (Question $question, Answer $answer) : Answer { return $answer->withSpeechAndText("Sorry, I'm not sure what to do here."); }))); $app->run();
As you switch to class-based action handlers, you can (but don't need to) implement
HandlerInterface
to ensure your handler method has the right signature.
More on Middlewares
The DoublePass
class can be used as an actual middleware, rather than as a
Slim route callable, as needed; its third parameter is unused and not typehinted
to allow for this.
If you'd rather use a framework that relies on the proposed PSR-15 middleware
spec, set up an instance of the PSR15
class. In that case you'll need both
a Router
instance (just like DoublePass
) and a callable that, given
something JSON-serializeable as its only parameter, returns a PSR-7
ResponseInterface with the parameter JSON-encoded, plus the proper Content-Type
header. If you're using Zend Diactoros, building the middleware will look like:
$middleware = new Middleware\PSR15($router, function($data) { return new \Zend\Diactoros\JsonResponse($data); });
Objects
This library provides a couple of immutable objects that make interacting with Dialogflow web hooks a bit easier.
Question
Question wraps Dialogflow's web hook request JSON, allowing cleaner access to parameters, contexts, and other aspects of the web hook request. Normally you'll be provided a Question by the router, but you can also build a Question independently:
/** @var \Psr\Http\Message\ServerRequestInterface $request */ $question = Question::fromRequest($request); // from a PSR-7 request /** @var array $data */ $question = new Question($data); // from an array, e.g. by JSON-decoding the web hook request body
See method docblocks in the Question class for more information.
Answer
An Answer can be passed directly into json_decode()
to produce the response body
needed for an Dialogflow web hook call. Normally this will get generated by calling
getBaseAnswer()
on a Question. Doing so informs the Answer of which contexts are
currently set, so they can be dropped if needed. This is the way the router handles
Questions and Answers, but you can also call new Answer()
directly.
See method docblocks in the Answer class for more information.