Using Serverless Framework with OpenWhisk PHP

Serverless Framework is a toolkit to help you mange and deploy a serverless application. (Personally, I’m not a fan of the name as the word “Serverless” already has a meaning in the same space!) It’s a useful tool and supports all the major providers, though AWS Lambda seems to be first-among-equals. The OpenWhisk plugin for Serverless is maintained by the rather excellent James Thomas, so if you have any questions, ping him!

As I build more complex PHP based OpenWhisk applications, I thought I’d explore how Serverless makes this easier.

Installing Serverless & the OpenWhisk plugin

We can install Serverless with this npm command:

$ npm install -g serverless serverless-openwhisk

We can then interact with Serverless using the serverless cli tool. If serverless is too much to type, there’s an sls alias too.

You also need to ensure that you have an IBM Cloud Functions account. Make sure that you also download and set up the bx CLI tool with the cloud-functions plugin as documented here.

Make sure you run this command:

bx wsk api list

This will ensure that the ~/.wskprops file is up-to-date; it contains the relevant API keys that are used by Serverless when deploying.

Create a project

To create a project, we can do:

$ sls create --template openwhisk-php --path ow-php-hello
$ cd ow-php-hello
$ npm install

This generates our project which has a few files files in it. The important ones are:

• serverless.yml – The Serverless configuration file
• handler.php – The PHP file containing our action code

serverless.yml

If we strip out the comments, there’s not too much to this file:

service: ow-php-hello

provider:
  name: openwhisk
  runtime: php

functions:
  hello:
    handler: handler.hello

plugins:
  - serverless-openwhisk

The docs provide the full details of what can go in there, but most importantly for us we can see that there’s a list of functions where one called hello is defined to have a hander of handler.hello. This maps to the hello() function in handler.php.

handler.php

This PHP file contains a pretty standard hello-world OpenWhisk PHP action:

<?php
function hello(array $args) : array
{
    $name = $args["name"] ?? "stranger";
    $greeting = "Hello $name!";
    echo $greeting;
    return ["greeting" => $greeting];
}

Deploying and running our project

As you may imagine given that Serverless‘s raison d’être is to manage serverless application deployments, deploying is a one-liner:

$ sls deploy

It whirs and clicks for a bit and then you get an output that contains lots of lines. One interesting part is this:

actions:
ow-php-hello-dev-hello

We can see that we have deployed an action called ow-php-hello-dev-hello which is made up of the project name (ow-php-hello), the stage (dev) and our function name (hello).

Invoking our action

We can use the standard command line to invoke our action:

bx wsk action invoke -r ow-php-hello-dev-hello
{
    "greeting": "Hello stranger!"
}

Alternatively Serverless provides an mechanism that means we don’t have to remember the prefix:

$ sls invoke -f hello
{
    "greeting": "Hello stranger!"
}

Web actions

To web enable our action (which is really useful for web hooks), we need to set it up as a Web Action. To do this, we have to change the configuration file and also our action code.

Firstly, we modify the serverless.yml file. Update the hello function like this:

functions:
  hello:
    handler: handler.hello
    annotations:
      web-export: true

For web actions, we also need to modify the return statement in handler.php so that it looks like this:

    return [
        "body" => [
            "greeting" => $greeting,
        ],
    ];

When you run sls deploy this time, you’ll notice output similar to this:

endpoints (web actions):
https://openwhisk.eu-gb.bluemix.net/api/v1/web/19FT_demo/default/ow-php-hello-dev-hello

This is the URL to our web action, so we can now use an HTTP client such as curl or Postman to invoke our action:

$ curl https://openwhisk.eu-gb.bluemix.net/api/v1/web/19FT_demo/default/ow-php-hello-dev-hello

{
  "greeting": "Hello stranger!"
}

Fin

Even for a single action, Serverless makes it easier to deploy and manage it. As we add more actions to our project, this will become more apparent. The OpenWhisk Plugin for Serverless makes it really easy to write bigger PHP serverless applications.

As a final note, if you want to remove the entire project from OpenWhisk, use sls remove.