randomhost/alexa

This is yet another fork of the amazon-alexa-php library by minicodemonkey / jakubsuchy.

Status: This fork is in the process of being rewritten and is considered bleeding edge software. The long term goal is to have a well documented package for working with Amazon's Alexa, making use of common standards such as the PSR-2 coding style.

Requirements

• PHP >= 5.3.0
• curl

Usage

Install via composer:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/randomhost/alexa"
        }
    ],
    "require": {
        "randomhost/alexa": "dev-master"
    }
}

Request

When Amazon Alexa triggers your skill, a HTTP request will be sent to the URL you specified for your app.

You can retrieve the JSON body of the request using standard PHP like so:

$json = file_get_contents('php://input');
if (false === $json) {
    throw new InvalidArgumentException(
        'Invalid call. No request body.'
    );
}

You could also use a framework like Symfony.

The package comes with a Factory which can be used to build the suitable Request object for the incoming HTTP request:

use randomhost\Alexa\Request\Factory as RequestFactory;

$applicationId = 'your-skill-id';

$factory = new RequestFactory();
$request = $factory->getInstanceForData(
    $json,
    $applicationId
);

Factory::getInstanceForData() requires the following parameters to build a Request object:

• $json
  This parameter refers to the raw unmodified HTTP request body. Factory will take care of decoding and validating the data before passing it on to the Request object as needed.
• $applicationId
  This parameter refers to the unique skill ID which Amazon generated for your skill. Amazon requires this skill ID to match the application ID coming with the HTTP request to verify that the request is handled by the appropriate end point.

Factory::getInstanceForData() may throw an InvalidArgumentException in the following cases:

• $json could not be decoded
• $json does not contain all required data
• $json contains invalid or otherwise unsupported data
• $applicationId does not match the ID that came with the request
• suspicious HTTP request data (e.g. HTTP request did not originate from the Amazon cloud)

You can then determine the type of the request with instanceof, e.g.:

use randomhost\Alexa\Request\Type\Launch;
use randomhost\Alexa\Request\Type\Intent;
use randomhost\Alexa\Request\Type\SessionEnded;

switch (true) {
    case ($request instanceof Launch):
        // say "Hi!", start a PHP session, etc.
        break;
        
    case ($request instanceof Intent):
        // do what the user asked for
        break;

    case ($request instanceof SessionEnded):
        // end session, log errors, etc.
        break;
    default:
        // log error
}

Response

You can build an Alexa response with the Response class. You can optionally set a card or a reprompt too.

Here's a few examples.

use randomhost\Alexa\Response;

$response = new Response();
$response
    ->respond('Cooool. I\'ll lower the temperature a bit for you!')
    ->withCard('Temperature decreased by 2 degrees');

use randomhost\Alexa\Response;

$response = new Response();
$response
    ->respond('What is your favorite color?')
    ->reprompt('Please tell me your favorite color');

use randomhost\Alexa\Response;

$response = new Response();
$response
    ->respond('Starting account linking')
    ->withLinkAccount();

To output the response, use Response::render().

header('Content-Type: application/json');
echo json_encode($response->render());
exit;

Note: Make sure that no output is generated by your application before and after rendering the response as that would break the JSON response.