What is OpenFaaS?

OpenFaaS lets you build and distribute “serverless” functions in a cloud computing environment. The “function” could be simple application logic that you program – or execution of a binary to perform an action. The term serverless is a slight misnomer as you still require a server, or indeed many servers, but by deploying your function into the cloud you don’t have to worry about scaling or managing physical server resources yourself – which is pretty cool.

OpenFaaS works by packaging your function up into a docker container customised to work with OpenFaaS. The OpenFaaS framework stack handles the creation and deployment of the container allowing you to execute your function with a simple command line or http request.

OpenFaaS doesn’t really care how you create your function as long as the container behaves in the way the framework and the function watchdog expects. This means whilst OpenFaaS ships with support for languages like Python and NODE.js it should work with just about anything you throw at it which means you can package up just about anything as a serverless function.

I’m developing with good old PHP so the first thing I did when I decided to take a closer look at OpenFaaS was to google “open faas php” to see how I could create serverless functions written in PHP. My search led me to a php template for OpenFaaS developed by Minh-Quan Tran. The template tells OpenFaaS how to build PHP5 or PHP7 containers to run your PHP code as OpenFaaS functions. After trying out the template there were a couple of issues with it I wanted to address, so I forked it and made a few changes.

If you want to deploy OpenFaaS PHP functions here’s a step by step guide that will get you from Zero to Hero in just a few minutes.

Install the OpenFaaS Stack and CLI

Assuming you already have Docker installed, the first thing you need to do is initialise a Docker swarm and deploy the OpenFaaS stack.

docker swarm init --advertise-addr $(hostname -i)

Change into a suitable working folder and install the OpenFaaS stack by cloning it from github and executing the deploy script.

git clone https://github.com/openfaas/faas && \
  cd faas && \
  ./deploy_stack.sh

Test that the stack is working by invoking the echoit example function that echoes back any input data you send it.

curl 127.0.0.1:8080/function/func_echoit -d 'hello world'

Now that OpenFaaS is working you need to install the OpenFaaS cli framework (faas-cli) that allows you to build, deploy and invoke your own functions easily from the command line.

curl -sL https://cli.openfaas.com | sudo sh

Next install the OpenFaaS PHP template

faas-cli template pull https://github.com/gaiterjones/openfaas-template-php

2017/11/19 09:52:30 Attempting to expand templates from master.zip
2017/11/19 09:52:30 Fetched 2 template(s) :  from https://github.com/gaiterjones/openfaas-template-php
2017/11/19 09:52:30 Cleaning up zip file...

Build and Deploy a PHP OpenFaaS function

Once the template is installed we can test it by creating our first PHP function. The OpenFaaS command line syntax for creating a new function is faas-cli new functionname –lang languagename. The PHP template uses the language name php for PHP7 functions and php5 for PHP5 functions. We will create a PHP7 function called func_php1 using the code in the template.

faas-cli new func_php1 --lang php

Folder: func_php1 created.
  ___                   _____           ____
 / _ \ _ __   ___ _ __ |  ___|_ _  __ _/ ___|
| | | | '_ \ / _ \ '_ \| |_ / _` |/ _` \___ \
| |_| | |_) |  __/ | | |  _| (_| | (_| |___) |
 \___/| .__/ \___|_| |_|_|  \__,_|\__,_|____/
      |_|


Function created in folder: func_php1
Stack file written: func_php1.yml

You will notice a new stack file func_php1.yml and function folder is created. For my tests using an Ubuntu virtual machine I had to edit func_php1.yml and change the hostname localhost to 127.0.0.1 as shown below.

provider:
  name: faas
  gateway: http://127.0.0.1:8080

functions:
  func_php1:
    lang: php
    handler: ./func_php1
    image: func_php1

In the func_php1 folder you will see three files

composer.json
Handler.php
php-extension.sh

Handler.php contains the entrypoint for our OpenFaaS PHP function and looks like this

<?php

class Handler
{
    public function handle(string $_data): void {
        $_version = phpversion();
        echo 'PHP Version : '. $_version ."\n". 'Data : '. $_data. "\n\n";
    }
}

You can see the PHP method Handler::handle() is going to echo the PHP version, and whatever data is supplied to it from STDIN.

Build the service container for the function with

faas-cli build -f func_php1.yml

Once the container has been built deploy it with

faas-cli deploy -f func_php1.yml

Deploying: func_php1.
No existing function to remove
Deployed.
URL: http://127.0.0.1:8080/function/func_php1

200 OK

And that’s it, our PHP OpenFaaS function is ready to test we can invoke it from faas-cli

faas-cli invoke -f func_php1.yml func_php1

Or use curl

curl 127.0.0.1:8080/function/func_php1 -d 'hello world'

PHP Version : 7.1.11
Data : hello world

You can also access all functions via the nifty OpenFaaS UI at http://yourhost/:8080/ui/

Build and Deploy a GEO IP OpenFaaS PHP function

Now let’s deploy a function with a little more functionality…

One API I use a lot is GEOIP2 by MaxMind it’s very useful for getting geographic data from an IP address. So let’s build an OpenFaaS PHP function to do just that.

Create a new PHP7 function called func_geoip

faas-cli new func_geoip --lang php

Before building the function we need to add our PHP code and dependencies. First let’s add the PHP dependencies to the functions composer file by editing func_geoip/composer.json

{
    "name": "function-php7",
    "description": "OpenFaaS GEOIP PHP function",
    "type": "project",
    "license": "MIT",
    "require": {
        "php": "^7.0",
        "maxmind-db/reader": "~1.0",
        "geoip2/geoip2": "~2.0"
    }
}

The geo ip data is read from a free GEOLITE2 database so we need to make that database available to our function. We can add data to our container using the func_geoip/php-extension.sh shell file which is executed when we build the template container.

echo "Installing function dependencies"
cd /usr/local/faas/function
curl -o GeoLite2-City.tar.gz http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.tar.gz
tar -xvzf GeoLite2-City.tar.gz --strip 1

Now add the geo ip lookup code to our PHP Handler class by editing func_geoip/Handler.php

Build and deploy the function

faas-cli build -f func_geoip.yml
faas-cli deploy -f func_geoip.yml

Now we can test it with

curl 127.0.0.1:8080/function/func_geoip -d '128.101.101.101'

The function returns the JSON formatted array of Geo data for the requested IP address

{"ip":"128.101.101.101","country":"United States","isocode":"US","region":"Minnesota","city":"Minneapolis","postcode":"55414","latitude":44.9759,"longitude":-93.2166,"googlemap":"https:\/\/maps.google.com\/?q=44.9759,-93.2166"}

FaaS in Production

We can easily access function data from other PHP applications using php curl to post the input data and return the output array. In production you need to consider how you will secure access to the function using some form of frontend proxy authentication.

Whether you will deploy simple php code as serverless functions in this way depends very much on the type of applications you are developing and the infrastructure available to you. I can
certainly think of a lot of my commonly used PHP library functions and classes that would become very useful deployed as OpenFaaS serverless functions.

References

• OpenFaaS
• OpenFaaS Community
• OpenFaaS CLI
• PHP Template
• Docker Swarm Tutorial

Tested on

• Ubuntu Server 17.10
• Docker 17.09.0-ce

Maintaining servers whether they are physical or virtual is a real pain in the neck, as time goes by you develop apps, you install more and more software and your simple php development platform starts to become quite complex. When it comes to a major OS update e.g. Ubuntu 14LTS to 16LTS where mysql and php versions are changing then keeping all your (now live) websites, blogs and apps running can become a real challenge.

In an ideal world you would have multiple servers designed specifically for the apps they are running, in the real world when we are talking about personal websites, blogs and forums everything ends up running on the same server. The longer you postpone an operating system upgrade the harder it gets to upgrade, and whilst some people live by the ‘if it’s running don’t break it’ theory when developing apps you want to make sure you are staying up to date with best practice and are aware what is being deprecated or no longer supported. Again the longer you ignore updates to PHP the harder it will be to update your PHP apps!

It’s a bit of a catch 22 situation, you need new server hardware, or an operating system but you can’t just upgrade in one go because too many apps will be affected resulting in a lot of downtime whilst you fix all the broken code and you can’t migrate to a new server because you know some of your apps won’t run.

As soon as you build a new server the process starts again and the next upgrade becomes just as challenging.

What is the solution? – containerisation.

containerisation with docker

Docker containers wrap up a piece of software in a complete filesystem that contains everything it needs to run: code, runtime, system tools, system libraries – anything you can install on a server. This guarantees that it will always run the same, regardless of the environment it is running in.

By moving each of my apps and server services into a container customised for the requirements of that app, be it a specific PHP or MySQL version or operating system I containerised (virtualised) all my server applications: php, mail, cloud storage, vpn, webapps, blogs, forums, Magento etc. into new zero administration servers which I wil never have to worry about upgrading!

All the old apps you know are not compatibile with the latest version of PHP (i.e. Magento 1.x) can stay running in a container customised for their requirements. The docker host server can now run a very minimal operating system, ideally with just Docker installed making future upgrades pretty uncomplicated.

Because all your apps are in containers moving to a new server is as simple as moving the container configuration and data files to the new server and starting the containers, you no longer have to worry about upgrade compatibility issues as your application is running in an container image that in theory will never change!

The golden rule to follow is to ensure that you always treat your containers as volatile storage and never store live data in them, or commit configurations that are not included in your configuration files.

By separating your application data into persistent docker volumes located in logically named folders basic housekeeping tasks like log management and backups are now also simplified. With all app data located in data folders, your container (application) data can be easily backed up. Log files are also easy to manage because they are consolidated into Docker’s central logging engine, all your log data can easily be centrally stored and analysed.

In practice Docker just works, the containers start and stop in seconds, and in some cases your apps will run much faster. There is a lot of work in configuring the container to replicate the environment you want, but once your Docker file is written it becomes a good template for future apps.

It’s easy to get carried away containerising everything so you have to monitor the host server resources you are using, I ended up with over 40 running containers which maxed out the RAM in a 4GB Linode resulting in containers crashing because they suddenly ran out of memory. I upgraded to an 8GB Linode where the ram usage now averages at just over 4GB for 40 running containers leaving me room for expansion.

I recommend building your containers using docker compose. Docker compose lets you keep your container configuration in one folder and provides an easy command line interface to start, stop and build containers. Here for example is the docker composer file for my Exim4 mail server container.

Here you see the docker compose file creates two services, Exim4 and Spam Assassin. The file also configures health checks and networking. More about building containers such as this Exim4 mail server with spam assassin will follow in another post.

In part one of the Alexa PHP Hello World example I created a very basic skill and a PHP app to show how to handle Amazon Alexa IntentRequest data and provide a response. In part two I will extend the code to allow us to create interactive prompt and responses.

If you are new to Alex skills and PHP read part one of this Hello World example first.

To demonstrate prompt and responses we will ask Alexa for a “clever quote”, Alexa will give us the quote and ask if we want another. If the user replies yes, Alexa reads another quote and prompts again until all the available quotes have been used.

Alexa Prompt and Response

To allow this prompt and response interaction we simply tell our skill to keep the session open when we require a response, and we store the data we need for the session in the session attributes array.

First let’s modify the Hello World skill interaction model :

{
  "intents": [
    {
      "slots": [
        {
          "name": "command",
          "type": "COMMANDOBJECTS"
        },
        {
          "name": "prompt",
          "type": "PROMPTOBJECTS"
        }
      ],
      "intent": "HelloWorld"
    },
    {
      "intent": "HelpIntent"
    }
  ]
}

Now we have command and prompt slots, with command objects and prompt objects to catch our prompt and response utterances. I have also added two new utterances

HelloWorld for {command}
HelloWorld {prompt}

“Clever” quotes

The clever quotes data is an array of sentences stored in Data::cleverQuotes(). We load the data, and then create a list of random numbers we will use as array keys to get random quotes from the array. The list of random array keys will be stored in the session data.

// clever quotes data
//
$_cleverQuotesData=Data::cleverQuotes();
$_cleverQuotesArrayKeys= range(0, (count($_cleverQuotesData)-1));
shuffle($_cleverQuotesArrayKeys);

• alexa ask hello world for clever quotes

In the HelloWorld php intent class I have added some new code to parse the user request for clever quotes. The response includes the first “clever quote” fetched from the array using the first of our random array key numbers and the prompt to the user – “would you like some more clever quotes“. We also set endsession to false to keep the session open and save the random key data and prompt count data we need for the next session.

// response
//
return array(
	'intent' => array(
		'response' => 'Ok, here comes your first clever quote : '. $_cleverQuotesData[$_cleverQuotesArrayKeys[0]]. ' Would you like some more clever quotes?',
		'card' => array(
			'title' => $_target,
			'text' => $_now->format('H:i:s'). ' '. $_cleverQuotesData[$_cleverQuotesArrayKeys[0]],
			'image' => false
		),											
		'target' => $_target,
		'status' => false,
		'sessionattributes' => array('object' => 'clever quotes','target' => $_target,'prompt' => true, 'count' => 1,'data' => $_cleverQuotesArrayKeys),
		'endsession' => false
	)
);

With the session still open the user has about 8 seconds to reply and we will see the response in the prompt slot. In the same way we parse the command slot data we parse the response slots for the yes or no response from the user.

If the user responded with yes, we extract the data we need from the session to provide the next “clever quote” and then provide the exact same response and session data including an incremented prompt count variable.

If there are no more quotes available we respond appropriately and end the session. Similarly if the user responds with no, we respond and end the session by setting endsession to true.

Alexa Session Data

If you check the logs generated by the php script you will see the session data:

    [session] > Array
        (
            [new] > 
            [sessionId] > SessionId.1-2-3
            [application] > Array
                (
                    [applicationId] > amzn1.ask.skill.1-2-3
                )

            [attributes] > Array
                (
                    [data] > Array
                        (
                            [0] > 0
                            [1] > 1
                            [2] > 5
                            [3] > 3
                            [4] > 7
                            [5] > 4
                            [6] > 10
                            [7] > 6
                            [8] > 2
                            [9] > 8
                            [10] > 9
                        )

                    [count] > 1
                    [prompt] > 1
                    [object] > clever quotes
                    [target] > clever quotes
                )

            [user] > Array
                (
                    [userId] > amzn1.ask.account.123
                )

Custom Help and Launch intent

Alexa has some default built in intents such as STOP, HELP and LAUNCH.

When you say “Alex open skillname” the LAUNCH intent is used. When you say HELP in a skill, the HELP intent is used. When you submit your skill Amazon will check these intents for functionality. To create your own custom LAUNCH and HELP intent responses you must create or edit the example file in AmazonDev/Alexa/Launch and AmazonDev/Alexa/Help.

The filenames should be as follows

launch123.php
help123.php

Where 123 is replaced with the last digits from your skill id, i.e. if your skill id is amzn1.ask.skill.111-222-333-444-555 then the launch and intent filenames should be

launch555.php
help555.php

You should also change the class name of the launch and help classes to the same as the filename (without .php). Now you can customise the launch and help intent for you skill by editing the responses in the help and launch methods.

	public static function help($_alexaRequest=false)
	{
		$_response="Hello, I am happy to Help! To start this skill please say 'Alexa, open Hello World'";
		$_card=false;
		$_endSession=false;
		$_sessionAttributes=false;
		$_outputSSML=false;

		return array(
			'response' => $_response,
			'card' => $_card,
			'endsession' => $_endSession,
			'sessionattributes' => $_sessionAttributes,
			'outputssml' => $_outputSSML
		);

	}

You can see here that it is relatively simple to include prompts and responses in your Alexa skill by controlling and storing data in the skill session.

The example “clever quotes” intent show here is published in the Alexa skill store as “Clever Stuff”.

The updated code for this Hello World and Clever Quotes example is available from github here.

This is kind of a quasi docker in docker because we are not trying to create dockerised containers within a container, rather run a docker app from the docker host within a docker container.

Still with me? Good!

We give our container access to the host docker socket by sharing a volume (in this case docker.sock) with the container

  volumes:    
      - /var/run/docker.sock:/var/run/docker.sock

If we install the docker binaries within the container we can now run docker commands on the host i.e.:

root@53f93be9ebbf:/# docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAME S
53f93be9ebbf trusty_ubuntu "/bin/bash" 18 seconds ago Up 17 seconds...

We are running docker ps as root, the problems start when you try and run docker as another user, for example www-data.

root@53f93be9ebbf:/# sudo -u www-data docker ps
Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get http://%2Fvar%2Frun%2Fdocker.sock/v1.26/containers/json: dial unix /var/run/docker.sock: connect: permission denied

We get a dial unix /var/run/docker.sock: connect: permission denied error.

Even if you add www-data to the docker group the permission problem persists.

If you take a look at /var/run/docker.sock in the container you will see the problem:

root@53f93be9ebbf:/# ls -al /var/run/docker.sock
srw-rw---- 1 root 999 0 Jan 26 08:55 /var/run/docker.sock

The container shows the group permissions for docker.sock (from the host) set to a group with an id of 999, and this group id does not exist in the container. We need to make sure the group id of the docker group in the container matches the group id of the docker group on the host

addgroup --gid 999 docker
usermod -aG docker www-data

The docker group now has the id of 999 and www-data is a member, the permissions in the container for docker.sock now look like this

root@53f93be9ebbf:/# ls -al /var/run/docker.sock
srw-rw---- 1 root docker 0 Jan 26 08:55 /var/run/docker.sock

And we can now execute docker ps as www-data

root@53f93be9ebbf:/# sudo -u www-data docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
53f93be9ebbf trusty_ubuntu "/bin/bash" 11 minutes ago Up 11 minutes ...

Or run a containerised version of ffmpeg

sudo -u www-data docker run jrottenberg/ffmpeg -stats \
 -i http://archive.org/download/thethreeagesbusterkeaton/Buster.Keaton.The.Three.Ages.ogv \
 -loop 0 \
 -final_delay 500 -c:v gif -f gif -ss 00:49:42 -t 5 - > trow_ball.gif

I can now exec docker run within the php code of the container app and run other docker container apps via ajax requests. You can add the group changes and install the docker binaries in the container using the following in your Dockerfile.

# >>> DOCKER IN DOCKER
RUN set -x \
    && cd /tmp \
    && curl -L -o docker-latest.tgz  https://get.docker.com/builds/Linux/x86_64/docker-latest.tgz \
    && gzip -d docker-latest.tgz \
    && tar -xvf docker-latest.tar \
    && mv /tmp/docker/docker /usr/local/bin \
    && rm -rf /tmp/docker docker-latest.tar \
    && addgroup --gid 999 docker \
    && usermod -aG docker www-data

This Christmas (2016) a lot of people in Europe will be unpacking a shiny new Amazon Echo device and enjoying meaningful discussions with Alexa about life, the universe and everything.

If you are a geek like me then you will probably want Alexa to do a bit more than tell you about the weather or play Last Christmas by Wham. I bought my Amazon Echo Dot primarily to use for extremely important Home Automation tasks such as ‘Alexa, switch on the Christmas Tree lights‘.

The developer documentation from Amazon is good but very biased towards node.js. I know absolutely nothing about node.js and some of the online examples seemed overly complex to me. Eventually I found some useable PHP code examples and set about creating my own flexible PHP server side app for handling Alexa requests.

The app I created uses Alexa to send home automation commands via an Internet server to a home based Raspberry Pi server that lets me control Lights and Audio equipment. This is a step by step Hello World example using the same script that shows how relatively simple it is to create an Amazon Alexa App using PHP on your server to handle requests.

Before we start, here is a shopping list of things you will need :

1. Amazon developer account
2. Internet accessible web server (project tested with Apache)
3. SSL Certificate
4. PHP
5. Amazon Echo

1. Install and Test the PHP Application

• Download my example PHP application and extract it to your web server
  • https://github.com/gaiterjones/amazon-alexa-php-hello-world-example
  • preserve the file and folder structure
    • Application
    • Library
    • www
    • autoload.php
  • Your web server needs to be able to serve web pages over SSL.
• create a folder that is writeable by your www server user, i.e. www-admin
  • configure this folder path as amazonCacheFolder in config.php
    • const amazonCacheFolder=’/home/www/amazon/cache/’;
• make the file PAJ/www/AmazonDev/alexa.php web accessible
  • Test that the application is working by browsing to
    • https://www.your.server/youralias/alexa.php?debug
  • Make sure you see
    • PAJ\Application\AmazonDev\AlexaRequest
    • logfolder is writeable
  • note the debug curl information as this will be helpful in testing access to your application.

2. Register a Developer Account

Register and login to Amazon Developer Services at https://developer.amazon.com. You should register with the Amazon account you used to setup your Amazon Echo device. Once you are registered and logged in, click on the Alexa tab, and then the Get Started button for the Alexa Skills Kit and click the Add a New Skill button.

3. Create and Test the Alexa Skill

Skill Information

Amazon calls the process used to interact with the Alexa Voice Service a Skill. We will create a new private skill called Hello World.

• Skill Type
  • choose Custom Interaction Model
• Language
  • Select from drop down
• Name
  • The name of the skill
    • Hello World
• Invocation Name
  • This is the name we will use to activate the skill when talking to Alexa
    • hello world
      • “Alexa, ask hello world to say hello world“
• Click Next

Interaction Model – Skill Builder Beta

The interaction model describes how the user will interact with the voice service. In the context of Alexa, an intent represents an action that fulfills a user’s spoken request. Intents can optionally have arguments called slots. The intent schema is configured as an array in JavaScript Object Notation (JSON) format.

Use the Skill Builder Beta and paste the following skills builder intent json schema into the code section :

Here we have defined our intent name HelloWorld and associated slots.

Some default Intents are added by Amazon

AMAZON.CancelIntent
AMAZON.HelplIntent
AMAZON.StoplIntent

You can think of slots as variables to the intent, we have a slot (variable) named command with possible values contained in the COMMANDOBJECTS intent slot.

Next we configure the sample utterances for the skill. These are what people say to Alexa to invoke the intents configured in the skill.

The sample utterance starts with the intent name HelloWorld, followed by any combination of words a user might use to interact with the skill, and then the slot name that corresponds with this interaction.

When a user interacts with our Alexa Skill

‘Alexa, ask hello world to say hello world’

The voice service try to determine the user intention by matching the spoken words to the configured utterances, invoking the configured intent and matching the slot values to the phrases provided to the slot. In this case it will match ‘hello world‘ to the value configured in the command slot of the HelloWorld intent. This data will be sent to our server for us to process.

Why use slots? By using the amazon voice service to process and match the users spoken words to a configured set of slot variables (object types) we do not have to process the spoken words ourselves, we simply match the slot type to the command or processes we want to execute making it easier to determine user intent.

When you are finished configuring the Skill Builder you must save your configuration by clicking the Save Model button, and then build the model by clicking the Build Model button.

Configuration

Now we will configure how the Skill communicates with our PHP application.

• Select HTTPS
• Select the geographical location closest to your server
• Enter the URL to the Alexa php script on your server
  • https://www.your.server/youralias/alexa.php

Click Next.

SSL Certificate

Assuming your web server has a valid SSL certificate select ‘My development endpoint has a certificate from a trusted certificate authority’.

Click Next.

TEST

We can now test the Skill and server PHP application by using the service simulator.

In the Enter Utterance text box we can type the phrase we would say to invoke the application using our Echo device

Alexa, ask hello world to say hello world

The application will fail with an exception error if you have not yet added your amazon credentials to the config file in PAJ/Application/Amazon/Alexa/config.php. You can see the application id and userid in the service request. Copy these and add them to config.php.

	// AMAZON ALEXA
	const amazonSkillId = 'amzn1.ask.skill.XXX';
	const amazonUserId = 'amzn1.ask.account.XXX';
	const amazonEchoServiceDomain = 'echo-api.amazon.com';
	const amazonCacheFolder='/home/www/amazon/cache';

Run the test again. If the application is working you will see the service response JSON data returned from our PHP application, and the text that would be spoken by the Echo device.

  "response": {
    "outputSpeech": {
      "type": "PlainText",
      "text": "OK, I will now say hello world"
    },

Publishing

The publishing information is used to define how the app will appear to users if it is made public. This includes the category, countries the app will be available in, description, sample phrases and images.

This information will also be displayed in the Alexa mobile app.

You cannot publish your app until you have completed this section. When all sections are complete the Submit for Certification button will be available. Clicking this will begin the certification process where Amazon checks your app for compliance and functionality before publishing it in the Alexa Skills store and making it publicly accessible.

Privacy & Compliance

Complete the privacy and Compliance section and click Save to save the Skill.

4. Test with Amazon Echo device

To use your newly created Hello World skill with your Echo device make sure the skill is visible and enabled in the Alexa app, under Home -> Skills select Your Skills

Now say to Alexa

Alexa, ask hello world to say hello world

Your Echo device will respond with

OK, I will now say hello world

You can also say, ‘Alexa, open hello world‘, this initiates a Launch Request.

Ok, so this is a bit lame, change the output text response by modifying the response text in the HelloWorld.php intent return array.

	return array(
		'intent' => array(
			'response' => 'OK, I will now say something much more meaningful',
			'target' => $_target,
			'status' => false
		)
	);

How the PHP application works

The PHP server side process is relatively straightforward:

• Amazon sends the Alexa request data as an HTTP POST request to alexa.php.
  • alexa.php initiates the wwwApp bootload which injects the following php objects
    • Config
      • config data for the app
    • Security
      • validates the Alexa Request as per the guidelines here.
      •  This includes :
        • Validating the amazon application id
        • Verifying that the Request was Sent by Alexa
          • determine whether the URL meets each of the following criteria:
            • The protocol is equal to https (case insensitive).
            • The hostname is equal to s3.amazonaws.com (case insensitive).
            • The path starts with /echo.api/ (case sensitive).
            • If a port is defined in the URL, the port is equal to 443.
        • Validate the Signature of the Request
        • Validate the Timestamp of the Request
    • Log
      • logging
    • Request
      • parses the alexa post data
    • Data
      • renders the response
      • renders default intent responses
        • STOP, CANCEL, HELP
      • render LaunchRequest response
        • open hello world
      • initiating PAJ\Application\AmazonDev\Alexa\Intent\IntentName()
      • processing the Amazon intent data
        • formulating a text response based on the process data, in this case simply returning the response text for hello world
          • ‘OK, I will now say hello world‘
        • managing session attribute data
      • wrapping the response text and card data into a JSON request and outputting it

If you look at HelloWorld.php in Alexa\Intent you will see how we are parsing the intent data from Amazon, looping through the slot data and performing an action on each slot. In this case looking for the ‘command’ slot, validating the spoken words and then acting on them to formulate a response.

Further customisation

Here you can also see how you can now further customise the application. For example suppose you want to ask alexa to turn the lounge lights on

‘Alexa, ask Home to switch the lounge lights on’

Here my Alexa Skill is called Home, my intent name is Command, and I have configures a slot called switch which contains object types (variables) such as ‘lounge lights on’ and ‘lounge lights off’.

In Alexa/Intent/Command.php I parse the intent data to find the switch slot, verify that the slot value contains either ‘lounge lights on’, or ‘lounge lights off’ and the send the appropriate commands to my home automation system, i.e. FHEM. When the command has been successfully executed I can return the appropriate response.

‘Ok, I have switched the lounge lights on’

Debugging

If the Application is not working as expected check out the logfiles in your cache folder, for each Amazon Alexa request you will see the request, intent and response data logged in a file called helloworld_yyyy-mm-dd.log.

Use the skills tester in the Amazon skill builder to test and debug your skill. To debug further use the example curl command from the debug page. Execute this from a bash terminal to run curl and simulate an alexa request to your application.

Amazon Default Intents

You will notice that Amazon includes some default intents in the interaction model : AMAZON.StopIntent, AMAZON.CancelIntent, AMAZON.HelpIntent. If you want to publish your skill you must also include responses for these default intents. The default response for the Stop and Cancel intent is included in the renderAlexaResponse method. An examples for the Stop intent can be found in the Help folder.

Prompt and Response Dialog

Having completed a basic Alex command skill I will extend this PHP example to allow for prompts and responses in part 2 of this blog post.

Submit for Certification

Alexa Skills built with this project will pass the Amazon certification process. After submitting your skill you will receive a confirmation email from Amazon, and within 24 hours a response to notify you whether your skill has passed certification of not. Once your skill has been certified you cannot make any changes to the skill configuration without revoking it’s published status.

If you publish a skill with this application please let us know in the comments!