Use PHP handlers to respond to events and run code - Function Compute

You can use PHP handlers to respond to received events and execute the corresponding business logic. This topic describes the concepts and structure of PHP handlers and provides examples.

What is a handler?

A handler of a function in Function Compute is the method used to process requests in function code. When a function is invoked, Function Compute uses the handler that you configured to process requests. You can configure a handler for a function by specifying the Handler parameter in the Function Compute console.

Handlers of PHP functions in Function Compute follow the File name.Method name format. For example, if your file name is main.php and your method name is handler, the handler is main.handler.

For more information about the definitions and operations of functions in Function Compute, see Manage functions.

Configurations of handlers must conform to the configuration specifications of Function Compute. The configuration specifications vary based on the handler type.

Handler signature

The following sample code shows a simple handler signature:

<?php

function handler($event, $context) {
  return 'hello world';
}

Parameter description:

handler: the name of the method to process requests. The method corresponds to the value that is specified for the Handler parameter in the Function Compute console. For example, if the value of the Handler parameter for a Function Compute function is index.handler, Function Compute loads the handler method that is defined in index.php and executes the function from handler.
$event: the parameter that is passed when you invoke the function. The value of this parameter is a string. The PHP function directly uses the specified event parameter. You can parse event in the function based on your business requirements. For example, if the input data is a JSON string, you can convert the JSON string to an array.
$context: the context information, such as the request ID and the temporary credentials. The information can be used in your code.

Note

If you want to use HTTP triggers or custom domain names to access functions, obtain request struct before you define HTTP responses. For more information, see Use an HTTP trigger to invoke a function.

Example 1: Parse JSON-formatted parameters

Sample code

When Function Compute passes the JSON-formatted parameters that you configured, you must parse the parameters in the code. The following sample code provides an example on how to parse a JSON-formatted event.

<?php

function handler($event, $context) {
  $v = json_decode($event, true);
  var_dump($v['key1']);
  var_dump($v['key2']);
  var_dump($v['key3']);
  return $v;
}

Before you start

Create a function in a PHP runtime. For more information, see Create a function.

Procedure

Log on to the Function Compute console. In the left-side navigation pane, click Functions.
In the top navigation bar, select a region. On the Functions page, click the function that you want to manage.
On the function details page, click the Code tab. In the code editor, enter the preceding sample code and click Deploy.
Note
In the preceding sample code, the handler is the handler method in index.php. If the handler of your function is different, use the actual handler configurations.
On the Code tab, click the icon next to Test Function, select Configure Test Parameters from the drop-down list, enter the following test parameters, and then click OK.
```
{
  "key1": "value1",
  "key2": "value2",
  "key3": {
    "v1": true,
    "v2": "bye",
    "v3": 1234
  }
}
```
Click Test Function.
After the function is executed, the content in JSON format is returned by the function, and values of key1, key2, and key3 are printed in the log output.

Example 2: Read and write OSS resources by using a temporary AccessKey pair

Sample code

You can use a temporary key pair that is provided by Function Compute to access Object Storage Service (OSS). The following code is used as an example.

<?php

use OSS\OssClient;
use OSS\Core\OssException;

function handler($event, $context) {
    /*
      The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in Function Compute is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. 
      We recommend that you do not save the AccessKey ID and AccessKey secret in your project code. Otherwise, the AccessKey pair may be leaked and the security of all resources in your account may be compromised. 
      In this example, the AccessKey ID and AccessKey secret are obtained from the context. 
    */
    $creds = $context["credentials"];
    $accessKeyId = $creds["accessKeyId"];
    $accessKeySecret = $creds["accessKeySecret"];
    $securityToken = $creds["securityToken"];
    $endpoint = "https://oss-cn-hangzhou-internal.aliyuncs.com";
    $bucket= "randombucket";
    $object = "exampledir/index.php";
    $filePath = "/code/index.php";

    try{
        $ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint, false, $securityToken);
        $ossClient->uploadFile($bucket, $object, $filePath);
    } catch(OssException $e) {
        printf(__FUNCTION__ . ": FAILED\n");
        printf($e->getMessage() . "\n");
        return $e->getMessage();
    }
    return 'hello world';
}

Description:

$creds = $context["credentials"] specifies to obtain the temporary AccessKey pair from $context. This prevents hard encoding of sensitive information such as passwords.
The preceding code indicates that the /code/index.php file is uploaded to the exampledir directory of randombucket in OSS.
Note
Replace endpoint, bucket, object, and filePath with actual values of your resources.

Before you start

Configure a role that has permissions to access OSS for the service. For more information, see Grant Function Compute permissions to access other Alibaba Cloud services.
Create a function in a PHP runtime. For more information, see Create a function.

Procedure

Log on to the Function Compute console. In the left-side navigation pane, click Functions.
In the top navigation bar, select a region. On the Functions page, click the function that you want to manage.
On the function details page, click the Code tab. In the code editor, enter the preceding sample code and click Deploy.
Note
In the preceding sample code, the handler is the handler method in index.php. If the handler of your function is different, use the actual handler configurations.
Click Test Function.
After the function is executed, the execution result hello world is returned.

Example 3: Call external commands

You can use a PHP program to create a fork process to run external commands.

If you want to use non-PHP tools, such as shell scripts and executable files compiled in C++ or Go in your PHP functions, you can package and upload the tools and code together, and then run external commands to use these tools. Common methods for calling external commands include exec, system, and shell_exec.

The following sample code is used to run the ls -halt command on Linux and output details of files in the current directory.

<?php

function handler($event, $context) {
  return shell_exec("ls -halt /code");
}

Example 4: Use an HTTP trigger to invoke a function

Sample code

<?php

function handler($event, $context) {
  $logger = $GLOBALS['fcLogger'];
  $logger->info('hello world');
  $logger->info('receive event: ' . $event);
  
  try {
    $evt = json_decode($event, true);
    if (is_null($evt['body'])) {
      return "The request did not come from an HTTP Trigger, event: " . $event;
    }
    $body = $evt['body'];
    if ($evt['isBase64Encoded']) {
      $body = base64_decode($evt['body']);
    }
    return array(
      "statusCode" => 200,
      'headers' => array("Content-Type" => "text/plain"),
      'isBase64Encoded' => false,
      "body" => $body
    );
  } catch (Exception $e) {
      $logger->error("Caught exception: " . $e->getMessage());
      return "The request did not come from an HTTP Trigger, event: " . $event;
  }
}

Before you start

Use the preceding example to create a function in a PHP runtime and create an HTTP trigger. For more information, see Create a function and Create a trigger.

Procedure

Log on to the Function Compute console. In the left-side navigation pane, click Functions.
In the top navigation bar, select a region. On the Functions page, click the function that you want to manage.
On the function details page, click the Configuration tab. In the left-side navigation pane, click Trigger. On the Trigger page, obtain the public endpoint of the HTTP trigger.
Run the following command in Curl to invoke the function:
```
curl -i "https://http-trigger-demo.cn-shanghai.fcapp.run" -d 'Hello FC!'
```
Important
- If the Authentication Method parameter of the HTTP trigger is set to No Authentication, you can use Postman or Curl to invoke the function. For more information, see Procedure.
- If the Authentication Method parameter of the HTTP trigger is set to Signature Authentication or JWT Authentication, you can use the signature method or JWT authentication method to invoke the function. For more information, see Authentication.

Possible errors

This sample code can be called by using an HTTP trigger or a custom domain name. If you use an API operation but the configured test parameters do not comply with request format requirements of HTTP triggers, an error is reported.

For example, the following response is returned if you invoke the function by clicking Test Function in the Function Compute console after you configure the request parameters as "Hello, FC!".

The request did not come from an HTTP Trigger, event: Hello FC!