PHP Cloud Function Guide

Cloud function is a sub-module of LeanEngine that allows you to run functions on the cloud in response to the requests made by clients. Before you continue, make sure you have read LeanEngine Overview.

When developing your application, you may need to write logic that:

• Are shared by multiple platforms (like iOS, Android, and web) and you wish to write them only once.
• Need to be modified frequently (like the sorting rules of a list) but you don't want to release a new version of client each time you make a change.
• Demand high network traffic or computing power (like producing statistics on a huge table) which you don't want to run on clients.
• Need to be triggered when certain events happen (hooking). For example, when a user deletes an account, you may wish to delete the entries in other tables that are related to this account as well.
• Need to bypass certain restrictions set by ACL.
• Need to be performed routinely. For example, you may wish to clean up inactive accounts every month.

With cloud function, you can deploy these logic written in any language (JavaScript, Python, PHP, or Java) on the cloud and have LeanEngine run them for you.

If you have no idea how to deploy you project to LeanEngine, take a look at LeanEngine Quick Start.

Other Languages

This guide uses PHP as an example, but LeanEngine supports many other languages as well. You can choose the one you are familiar with for development:

• Node.js
• Python
• PHP (current)
• Java

Switching Environments

LeanEngine offers two environments for each app: production environment and staging environment. When calling cloud functions within LeanEngine instances using SDK, no matter explicitly or implicitly (by triggering hooks), the SDK uses the function defined in the same environment as the instance. For example, if beforeDelete hook is defined and an object is deleted with SDK in the staging environment, the beforeDelete hook in the staging environment will be triggered.

When calling cloud functions outside of LeanEngine instances using SDK, no matter explicitly or implicitly, X-LC-Prod is set to be 1 by default, which means that the production environment will be used. For historical reasons, there are some differences between each SDK:

• For Node.js, PHP, and Java SDKs, the production environment will always be used by default.
• For Python SDK, when debugging locally with lean-cli, the staging environment will be used if it exists, otherwise the production environment will be used.
• For Java example projects java-war-getting-started and spring-boot-getting-started, when debugging locally with lean-cli, the staging environment will be used if it exists, otherwise the production environment will be used (same as Python SDK).

You can specify the environment being used with SDK:

[AVCloud setProductionMode:NO]; // Staging environment

AV.setProduction(false); // Staging environment

leancloud.use_production(False) # Staging environment
# Call it before `leancloud.init`

LeanClient::useProduction(false); // Staging environment

AVCloud.setProductionMode(false); // Staging environment

Apps with only trial instances would only have production environments. Please do not attempt to switch to staging environments.

Cloud Functions

In this example, a simple cloud function named hello is defined in src/cloud.php. By doing so, clients running on all platforms will be able to call it and get the return value of it. The computing process of the function is done on the cloud side rather than on the client side, so there will be less burden on the clients.

Now let's look into a more complex example.

Imagine that you have an app that lets users review the movies they have watched. An object containing a single review of a movie may look like this:

{
  "movie": "Despicable Me",
  "stars": 5,
  "comment": "These minions are so cute. I wish they are real and I can have them in my home!"
}

stars is the score given by the user, ranging from 1 to 5. If you want to obtain the average score of Despicable Me, one thing you can do is to have the client search for all the reviews of this movie and calculate the average score on the device. However, this requires all the reviews of this movie to be fetched to the client, which leads to unnecessary network traffic. With cloud function, you can simply have the client pass the name of the movie to the cloud and receive the calculated score only.

Cloud functions accept parameters in JSON objects which we can include the name of the movie in. All the methods defined in LeanStorage PHP SDK can be used on LeanEngine, so we can write the cloud function averageStars like this:

use \LeanCloud\Engine\Cloud;
use \LeanCloud\Query;
use \LeanCloud\CloudException;

Cloud::define("averageStars", function($params, $user) {
    $query = new Query("Review");
    $query->equalTo("movie", $params["movie"]);
    try {
        $reviews = $query->find();
    } catch (CloudException $ex) {
        // Log the error message if the query fails
        error_log($ex->getMessage());
        return 0;
    }
    $sum = 0;
    forEach($reviews as $review) {
        $sum += $review->get("stars");
    }
    if (count($reviews) > 0) {
         return $sum / count($reviews);
    } else {
         return 0;
    }
});

The PHP SDK offers the Cloud::start function which can be used to quickly initialize cloud function services. The example below shows the index.php of a LeanEngine project dedicated to cloud function services:

<?php
use \LeanCloud\Engine\Cloud;
require __DIR__ . '/../vendor/autoload.php';
require __DIR__ . '/../src/cloud.php'; // Contains the definitions of cloud functions
Cloud::start();

Parameters and Return Values

The following parameters can be accessed within a cloud function:

• $params: array: The parameters sent from the client.
• $user: User: The user logged in at the client side (according to the header X-LC-Session).
• $meta: array: Other information about the client, including $meta['remoteAddress'] which is the IP address of the client.

Calling Cloud Functions with SDK

You can call cloud functions with any LeanCloud SDK:

// Construct the dictionary to be passed to the cloud
NSDictionary *dicParameters = [NSDictionary dictionaryWithObject:@"Despicable Me"
                                                          forKey:@"movie"];

// Call averageStars with parameters
[AVCloud callFunctionInBackground:@"averageStars"
                   withParameters:dicParameters
                   block:^(id object, NSError *error) {
                   if(error == nil){
                     // Success; object is the returned value from the cloud function
                   } else {
                     // Error handling
                   }
}];

var paramsJson = {
  movie: "Despicable Me"
};
AV.Cloud.run('averageStars', paramsJson).then(function (data) {
  // Success; data is the returned value from the cloud function
}, function (err) {
  // Error handling
});

from leancloud import cloudfunc

cloudfunc.run('averageStars', movie='Despicable Me')

use \LeanCloud\Engine\Cloud;
$params = array(
    "movie" => "Despicable Me"
);
Cloud::run("averageStars", $params);

// Construct the parameters to be passed to the cloud
Map<String, String> dicParameters = new HashMap<String, String>();
dicParameters.put("movie", "Despicable Me");

// Call averageStars with parameters
AVCloud.callFunctionInBackground("averageStars", dicParameters, new FunctionCallback() {
    public void done(Object object, AVException e) {
        if (e == null) {
            // Success; object is the returned value from the cloud function
        } else {
            // Error handling
        }
    }
});

Calling Cloud Functions with REST API

See LeanEngine REST API Guide.

Calling Cloud Functions on LeanEngine

You can call the cloud functions defined by LeanCloudEngineCloud::define with LeanCloudEngineCloud::run:

try {
    $result = Cloud::run("averageStars", array("movie" => "Despicable Me"));
} catch (\Exception $ex) {
    // Error handling
}

By doing so, a local function call will be triggered without initiating an HTTP request.

Calling Cloud Functions with RPC

By calling cloud functions with RPC, LeanEngine will automatically serialize the HTTP response body and the SDK will get the response in the format of LeanObject:

NSDictionary *dicParameters = [NSDictionary dictionaryWithObject:@"Despicable Me"
                                                          forKey:@"movie"];

[AVCloud rpcFunctionInBackground:@"averageStars"
                  withParameters:parameters
                  block:^(id object, NSError *error) {
                  if(error == nil){
                    // Success
                  }
                  else {
                    // Error handling
                  }
}];

var paramsJson = {
  movie: "Despicable Me"
};

AV.Cloud.rpc('averageStars', paramsJson).then(function (object) {
  // Success
}, function (error) {
  // Error handling
});

from leancloud import cloudfunc

cloudfunc.rpc('averageStars', movie='Despicable Me')

// Construct parameters
Map<String, String> dicParameters = new HashMap<String, String>();
dicParameters.put("movie", "Despicable Me");

AVCloud.rpcFunctionInBackground("averageStars", dicParameters,
  new FunctionCallback<AVObject>() {
    @Override
    public void done(AVObject object, AVException e) {
      Assert.assertNull(e);
    }
  }
);

Error Codes

You can customize error codes for cloud functions in accordance with HTTP status codes.

Cloud::define("errorCode", function($params, $user) {
    User::logIn("not_this_user", "P@ssword");
});

The client will receive { "code": 211, "error": "Could not find the user." } from the function above.

Cloud::define("customErrorCode", function($params, $user) {
    throw new FunctionError("Custom error message.", 123);
});

The client will receive { "code": 123, "error": "Custom error message." } from the function above.

Timeouts

The time limit for a cloud function to be processed is 15 seconds. If the cloud function does not make a response after this, HTTP error 503 will be triggered with error message The request timed out on the server. An error log like WARNING: [pool www] child ... exited on signal 9 (SIGKILL) after ... seconds from start will be printed on the server side.

Hooking

A hook can be automatically triggered when certain events happen (like before or after saving or updating an object). Keep in mind that:

• Importing data on the dashboard will not trigger any hooks.
• Dead loops may be caused if hooks are not defined properly.
• Hooks cannot be applied to _Installation table.

For hooks starting with before (including onLogin), if an exception occurs inside the function, the data operation will be terminated. Therefore, you can reject certain data operations by having functions throw an error. For hooks starting with after (including onVerified), such exception will not terminate the data operation because the operation is already completed before the function is executed.

graph LR
A((save)) -->D{object}
D-->E(new)
E-->|beforeSave|H{error?}
H-->N(No)
N-->B[create new object on the cloud]
B -->|afterSave|C((done))
H-->Y(Yes)
Y-->Z((interrupted))
D-->F(existing)
F-->|beforeUpdate|I{error?}
I-->Y
I-->V(No)
V-->G[update existing object on the cloud]
G-->|afterUpdate|C

graph LR
A((delete))-->|beforeDelete|H{error?}
H-->Y(Yes)
Y-->Z((interrupted))
H-->N(No)
N-->B[delete object on the cloud]
B -->|afterDelete|C((done))

To ensure that hooks are triggered internally by LeanStorage services, our SDK will verify the source of each request. If the verification fails, the error message Hook key check failed will be returned. If you see such error message when debugging locally, make sure you are using our command-line interface for debugging.

beforeSave

You can perform an operation before an object is saved, like data verification and pre-processing. For example, a comment on a movie may be too long to be displayed on the client and needs to be cut off to 140 characters:

Cloud::beforeSave("Review", function($review, $user) {
    $comment = $review->get("comment");
    if ($comment) {
        if (strlen($comment) > 140) {
            // Cut off and add '…' in the end
            $review->set("comment", substr($comment, 0, 140) . "…");
        }
    } else {
        // Return an error without saving the object
        throw new FunctionError("No comment provided!", 101);
    }
});

afterSave

You can perform an operation after an object is saved. For example, to update the total number of comments after a comment is created:

Cloud::afterSave("Comment", function($comment, $user) {
    $query = new Query("Post");
    $post = $query->get($comment->get("post")->getObjectId());
    $post->increment("commentCount");
    try {
        $post->save();
    } catch (CloudException $ex) {
        throw new FunctionError("An error occurred while trying to save the post: " . $ex->getMessage());
    }
});

Or, to add a new field from for each new user:

Cloud::afterSave("_User", function($userObj, $currentUser) {
    $userObj->set("from", "LeanCloud");
    try {
        $userObj->save();
    } catch (CloudException $ex) {
        throw new FunctionError("An error occurred while trying to save the user: " . $ex->getMessage());
    }
});

beforeUpdate

You can perform an operation before an object is updated. You will be able to know which fields are updated, or reject the data operation:

Cloud::beforeUpdate("Review", function($review, $user) {
    // If comment is changed, check its length
    if (in_array("comment", $review->updatedKeys) &&
        strlen($review->get("comment")) > 140) {
        throw new FunctionError("Your comment cannot be longer than 140 characters.");
    }
});

afterUpdate

You can perform an operation after an object is updated. You will be able to know which fields are updated (same as beforeUpdate).

Cloud::afterUpdate("Review", function($review, $user) {
    if (in_array("comment", $review->updatedKeys) &&
        strlen($review->get("comment")) < 5) {
        error_log(review.ObjectId . " seems like a spam: " . comment);
    }
});

Preventing Dead Loops

You might be wondering why we can modify and save the post object in the afterUpdate hook without triggering this hook again. This is because LeanEngine automatically identifies and pre-processes all the LeanObject objects passed in by a hook to prevent the hook to be triggered again.

However, if the following situations happen, you still need to handle them by yourself:

• You called fetch on the LeanObject objects passed in.
• You constructed the LeanObject objects passed in by yourself with methods like LeanObject::create().

To prevent such objects from triggering certain hooks, you can call LeanObject->disableBeforeHook() or LeanObject->disableAfterHook() on them:

Cloud::afterUpdate("Post", function($post, $user) {
    // Directly modifying and saving the object will not trigger afterUpdate
    $post->set('foo', 'bar');
    $post->save();

    // Use disableAfterHook if you called fetch on the object
    $post->fetch();
    $post->disableAfterHook();
    $post->set('foo', 'bar');
    $post->save();

    // Use disableAfterHook if you constructed the object by yourself
    $post = LeanObject::create("Post", $post->getObjectId());
    $post->disableAfterHook();
    $post->save();
});

beforeDelete

You can perform an operation before an object is deleted. For example, before an album is deleted, check if there are any photos in it:

Cloud::beforeDelete("Album", function($album, $user) {
    $query = new Query("Photo");
    $query->equalTo("album", $album);
    try {
        $count = $query->count();
    } catch (CloudException $ex) {
        throw new FunctionError("An error occurred when getting photo count: {$ex->getMessage()}");
    }
    if ($count > 0) {
        // The delete operation will be aborted
        throw new FunctionError("Cannot delete an album if it still has photos in it.");
    }
});

afterDelete

You can perform an operation after an object is deleted. For example, when an album is being deleted, instead of checking if there are any photos left, we directly delete all the photos in it:

Cloud::afterDelete("Album", function($album, $user) {
    $query = new Query("Photo");
    $query->equalTo("album", $album);
    try {
        $photos = $query->find();
        LeanObject::destroyAll($photos);
    } catch (CloudException $ex) {
        throw new FunctionError("An error occurred when getting photo count: {$ex->getMessage()}");
    }
});

onVerified

You can perform an operation after a user's email or phone number is verified:

Cloud::onVerifed("sms", function($user, $meta) {
    error_log("User {$user->getUsername()} is verified by SMS.");
});

The first parameter is the type of verification (sms for phone number and email for email). Keep in mind that you don't have to update fields like emailVerified with this hook since the system automatically updates them.

onLogin

You can perform an operation before a user tries to log in. For example, to prevent blocked users from logging in:

Cloud::onLogin(function($user) {
    error_log("User {$user->getUsername()} is trying to log in.");
    if ($user->get("blocked")) {
        // The user cannot log in if an error is thrown (error 401 will be returned)
        throw new FunctionError("Forbidden");
    }
    // The user will be logged in if the function returns normally
});

Hooks for LeanMessage

See LeanMessage Overview > LeanEngine Hooks for more instructions on the methods introduced below.

_messageReceived

You can perform an operation after a message is delivered to the cloud but before it is delivered to the receiver. For example, to filter out certain keywords from the message:

Cloud::define("_messageReceived", function($params, $user) {
    // params: {
    //     fromPeer: 'Tom',
    //     receipt: false,
    //     groupId: null,
    //     system: null,
    //     content: '{"_lctext":"Hello!","_lctype":-1}',
    //     convId: '5789a33a1b8694ad267d8040',
    //     toPeers: ['Jerry'],
    //     __sign: '1472200796787,a0e99be208c6bce92d516c10ff3f598de8f650b9',
    //     bin: false,
    //     transient: false,
    //     sourceIP: '121.239.62.103',
    //     timestamp: 1472200796764
    // };

    error_log('_messageReceived start');
    $content = json_decode($params["content"], true);
    $text = $content["_lctext"];
    error_log($text);
    $processedContent = preg_replace("selling drugs", "**", $text);
    // Must return the content or an error will be triggered
    return array("content" => $processedContent);
});

_receiversOffline

You can perform an operation if a message is delivered to the receiver but the receiver is offline. For example, to slice the first 32 characters of the message as the title for the push notification:

Cloud::define('_receiversOffline', function($params, $user) {
    error_log('_receiversOffline start');
    // content is the content of the message
    $shortContent = $params["content"];
    if (strlen($shortContent) > 32) {
        $shortContent = substr($shortContent, 0, 32);
    }

    $json = array(
        // Self-increase the number of unread messages
        // Can be set to a fixed number
        "badge" => "Increment",
        "sound" => "default",
        // Using development certificate
        "_profile" => "dev",
        "alert" => shortContent
    );

    $pushMessage = json_encode($json);
    return array(
        "pushMessage" => $pushMessage,
    );
});

_messageSent

You can perform an operation after a message is delivered to the receiver. For example, to print out a log in LeanEngine:

Cloud::define('_messageSent', function($params, $user) {
    error_log('_messageSent start');
    error_log('params:' . json_encode($params));
    return array();

    // _messageSent start
    // params: {
    //   fromPeer: 'Tom',
    //   receipt: false,
    //   onlinePeers: [],
    //   content: '12345678',
    //   convId: '5789a33a1b8694ad267d8040',
    //   msgId: 'fptKnuYYQMGdiSt_Zs7zDA',
    //   __sign: '1472703266575,30e1c9b325410f96c804f737035a0f6a2d86d711',
    //   bin: false,
    //   transient: false,
    //   sourceIP: '114.219.127.186',
    //   offlinePeers: ['Jerry'],
    //   timestamp: 1472703266522
    // }
});

_conversationStart

You can perform an operation after the signature verification (if enabled) of creating a conversation is completed but before the conversation is created. For example, to print out a log in LeanEngine:

Cloud::define('_conversationStart', function($params, $user) {
    error_log('_conversationStart start');
    error_log('params:' . json_encode($params));
    return array();

    // _conversationStart start
    // params: {
    //     initBy: 'Tom',
    //     members: ['Tom', 'Jerry'],
    //     attr: {
    //         name: 'Tom & Jerry'
    //     },
    //     __sign: '1472703266397,b57285517a95028f8b7c34c68f419847a049ef26'
    // }
});

_conversationStarted

You can perform an operation after a conversation is created. For example, to print out a log in LeanEngine:

Cloud::define('_conversationStarted', function($params, $user) {
    error_log('_conversationStarted start');
    error_log('params:' . json_encode($params));
    return array();

    // _conversationStarted start
    // params: {
    //     convId: '5789a33a1b8694ad267d8040',
    //     __sign: '1472723167361,f5ceedde159408002fc4edb96b72aafa14bc60bb'
    // }
});

_conversationAdd

You can perform an operation after the signature verification (if enabled) of adding a member into a conversation is completed but before the member is added. This will be triggered both when the member proactively joins the conversation or is added by another member. Keep in mind that this hook will not be triggered when creating a conversation with clientIds. For example, to print out a log in LeanEngine:

Cloud::define('_conversationAdd', function($params, $user) {
    error_log('_conversationAdd start');
    error_log('params:' . json_encode($params));
    return array();

    // _conversationAdd start
    // params: {
    //     initBy: 'Tom',
    //     members: ['Mary'],
    //     convId: '5789a33a1b8694ad267d8040',
    //     __sign: '1472786231813,a262494c252e82cb7a342a3c62c6d15fffbed5a0'
    // }
});

_conversationRemove

You can perform an operation after the signature verification (if enabled) of removing a member from a conversation is completed but before the member is removed. This will not be triggered when the member proactively quits the conversation. For example, to print out a log in LeanEngine:

Cloud::define('_conversationRemove', function($params, $user) {

    error_log('_conversationRemove start');
    error_log('params:' . json_encode($params));
    error_log('Removed clientId:' . $params['members'][0]);
    return array();

    // _conversationRemove start
    // params: {
    //     initBy: 'Tom',
    //     members: ['Jerry'],
    //     convId: '57c8f3ac92509726c3dadaba',
    //     __sign: '1472787372605,abdf92b1c2fc4c9820bc02304f192dab6473cd38'
    // }
    // Removed clientId: Jerry
});

_conversationUpdate

You can perform an operation before the properties of a conversation (including notifications) are updated. For example, to print out a log in LeanEngine:

Cloud::define('_conversationUpdate', function($params, $user) {
    error_log('_conversationUpdate start');
    error_log('params:' . json_encode($params));
    error_log('name:' . $params['attr']['name']);
    return array();

    // _conversationUpdate start
    // params: {
    //     convId: '57c9208292509726c3dadb4b',
    //     initBy: 'Tom',
    //     attr: {
    //         name: 'Tom and Jerry',
    //         type: 'public'
    //     }
    // }
    // name: Tom and Jerry
});

Error Codes for Hooks

You can define error codes for hooks like beforeSave:

Cloud::beforeSave("Review", function($review, $user) {
   $comment = $review->get("comment");
   if (!$comment) {
       throw new FunctionError(json_encode(array(
           "code" => 123,
           "message" => "An error occurred.",
       )));
   }
});

The client will receive Cloud Code validation failed. Error detail: { "code": 123, "message": "An error occurred." } as the response. You can retrieve the error message by slicing the string.

Timeouts for Hooks

The time limit for a hook to be processed is 3 seconds. If a hook is triggered by another cloud function (like a beforeSave or afterSave triggered by saving an object), the time limit of this hook will be further limited by the time remaining.

For example, if a beforeSave is triggered by a cloud function that has already taken 13 seconds, there will be only 2 seconds left for this hook. See Timeouts.

Scheduled Tasks

You can set up timers to schedule your cloud functions. For example, to clean up temporary data every night, to send push notifications to users every Monday, etc. The timer can be accurate to a second.

The time restrictions applied to ordinary cloud functions also apply to scheduled functions. See Timeouts.

After deploying your program to LeanEngine, go to your app's Dashboard > LeanEngine > Scheduled tasks and click on Create a timer to create a timer for a cloud function. For example, if we have a function named logTimer:

Cloud::define("logTimer", function($params, $user) {
    error_log("This log is printed by logTimer.");
});

After a timer is created, the default status of it will be Disabled. You need to click on Enable to activate the timer. You can see the logs of the timer in Dashboard > LeanEngine > App logs.

You can set up timers with either cron expressions or intervals with seconds as the unit. For example, to run a function on 8:00 every Monday, use 0 0 8 ? * MON as the cron expression.

You can create up to 6 timers for each of the staging environment and the production environment, which means that you can create 12 timers in total.

Error Messages for Scheduled Tasks

The error messages of timers will be output to Dashboard > LeanEngine > App logs. Below are some common errors and the reasons causing them:

• timerAction timed-out and no fallback available
  A function triggered by a timer reached its 15-second time limit for processing. See Handling Timeouts.
• timerAction short-circuited and no fallback available
  A timer is disabled due to frequent timeouts happening to the function it is triggering.

Using Master Key

Since cloud functions are running on the server side, we can assume that requests made by these functions are trustable. Therefore, you can enable global Master Key for all these requests, which will have your program ignore permission settings of classes and those done by ACL so it can access data in the cloud without any restrictions. The code below enables Master Key for your program:

// Often in src/app.php
Client::useMasterKey(true);

See ACL Guide and Using ACL in LeanEngine for more information regarding permission settings with LeanEngine.