Functions PHP Runtime
Functions are blocks of code that run on demand without the need to manage any infrastructure. Develop on your local machine, test your code from the command line (using doctl), then deploy to a production namespace or App Platform — no servers required.
Functions supports PHP 8.0 (php:8.0) and PHP 8.2 (php:8.2). Specify the desired runtime and version with the runtime key in your project.yml file, or by using the Runtime dropdown when creating a function through the control panel.
The Functions PHP runtime passes two parameters to your handler function, and expects either no return value or a properly formatted response array.
The entrypoint must be a file named index.php.
A PHP Echo Function
Here is a PHP function that responds with all the event and context information available to it:
<?php
function main(array $event, object $context) : array
{
return ["body" => ["event" => $event, "context" => $context]];
}
This can be useful for getting started with the Functions platform or for debugging.
The runtime expects a function called main in the index.php file to act as the entry point or the handler. This handler function is the only function where the runtime will pass in data and receive responses.
You can set a different function name as the handler using the main key in project.yml.
The main function above takes two parameters, an $event array and a $context object. It returns them as the body of the response array. This data structure is automatically converted to JSON and returned.
Parameters
The handler function is always passed two parameters, $event and $context.
Note
The first parameter, event, is the input event that initiated the function. When this is an HTTP event it’s called a web event.
The second parameter, $context, is data about the function’s execution environment such as memory allocations and time remaining before a timeout.
Both parameters are optional and you may ignore them if your function doesn’t require the information they provide. The parameter list for your handler function should look like one of the following:
(array $event, object $context): Accesses both parameters.(array $event): Accesses only the event parameter.(array $_, object $context): Accesses only the context parameter ($_is a common convention for unused parameters, though you may need to mark it as unused to satisfy your linter or IDE).(): Accesses neither.
Here is a function that uses both parameters to return a personalized Hello world and the function’s version number:
<?php
function main(array $event, object $context) : array
{
$name = $event["name"] ?? "stranger";
$version = $context->{"functionVersion"};
return ["body" => "Hello $name! This is version $version."];
}
If you add this example function to your namespace, you can call the function by pasting its URL in your browser and adding a name field in a query string at the end:
Note
You can get the URL for your function from the control panel interface, or by running the following command on the command line:
doctl serverless function get <function-name> --url
https://<your-function-url>?name=Sammy
Or use curl to send the input as form data in the body of the request:
curl -d 'name=Sammy' <your-function-url>
Either way, the function returns the response body:
Hello Sammy! This is function version 0.0.2.
Event Parameter
The $event parameter is an array. It is structured like the following example:
[
'http' => [
'headers' => [
'accept' => '*/*',
'accept-encoding' => 'gzip',
'user-agent' => 'curl/7.85.0',
'x-forwarded-for' => '203.0.113.11',
'x-forwarded-proto' => 'https',
'x-request-id' => '5df6f6b0d00b58217439c8376fcae23a',
],
'method' => 'POST',
'path' => '',
],
'shark' => 'hammerhead',
]
This example event has had a shark: hammerhead input passed to it. This has been parsed and added as a top-level key to the array.
More details on the information contained in the event parameter is available under the Event Parameter section of the Parameters and Responses reference documentation.
Context Parameter
The $context parameter is an object. It has the following properties:
{
string $activationId;
string $apiHost;
string $apiKey;
int $deadline;
string $functionName;
string $functionVersion;
string $namespace;
string $requestId;
}
Additionally, it has one method, getRemainingTimeInMillis(), which returns the number of milliseconds remaining before the function times out. It typically returns a float value. It returns an int in the rare case where the deadline is reached the precise moment this method is called (so that the remaining number of milliseconds is less than or equal to 0).
More details on the information contained in the context parameter is available under the Context Parameter section of the Parameters and Responses reference documentation.
Returns
To send a response, your function must return a properly formatted response array. More details on the response format can be found in the Returns section of the Parameters and Responses reference documentation.
If your function does not need to send a response, you may return an empty array nothing at all, or omit the return statement entirely.
Here is a response array that returns a string as the response body:
["body" => "Hello world"]
If the body is an array or object, it is automatically serialized as JSON and returned with a Content-Type: application/json header. This function returns the event and context parameters as JSON:
<?php
function main(array $event, object $context) : array
{
return ["body" => ["event" => $event, "context" => $context]];
}
You may also specify the response’s status code and headers. The status code can be a number or a string:
<?php
function main() : array
{
return [
"body" => "Hello world",
"statusCode" => 200,
"headers" => [
"Content-Type" => "text/plain"
]
];
}
Example Functions
Return JSON
If the body is an array or object, it is automatically serialized as JSON and returned with a Content-Type: application/json header.
<?php
function main() : array
{
return ["body" => [["type" => "hammerhead"], ["type" => "mako"]]];
}
Return an Image
To return an image or other media type, set the correct Content-Type header and return a base64-encoded body:
<?php
function main() : array
{
// example 1x1 GIF
$gif = "R0lGODlhAQABAAD/ACwAAAAAAQABAAACADs=";
return [
"statusCode" => "200",
"headers" => [
"Content-Type" => "image/gif"
],
"body" => $gif
];
}
Return an HTTP Redirect
A 302 status code and location header redirects an HTTP client to a new URL:
<?php
function main() : array
{
return [
"statusCode" => "302",
"headers" => [
"location" => "https://example.com"
]
];
}
Return HTML and Set a Cookie
Set cookies with the Set-Cookie header, and use the Content-Type: 'text/html' header to return HTML content:
<?php
function main() : array
{
return [
"statusCode" => "200",
"headers" => [
"Set-Cookie" => "UserID=Sammy; Max-Age=3600; Version=",
"Content-Type" => "text/html"
],
"body" => "<html><body><h3>hello</h3></body></html>"
];
}
More Example Functions
Some more complex example PHP functions are available on GitHub:
Log to the Console
Any text output to stdout and stderr is logged and can be accessed through the doctl command line tool. Use doctl serverless activations logs --follow to follow logs for all functions in the current namespace, or specify a single function with --function.
See the doctl serverless activations logs reference for more information or add the --help flag to the command for help output.
Use Modules and Dependencies
PHP dependencies can be managed with Composer. To deploy a PHP function with package dependencies you need a composer.json file and a build.sh build script to run composer install.
Here is an example PHP function that uses a cowsay package:
<?php
use Cowsayphp\Farm;
function main(array $event): array
{
$name = $event["name"] ?? "stranger";
$cow = Farm::create(\Cowsayphp\Farm\Cow::class);
return [
"body" => $cow->say("Hello $name from PHP!")
];
}
The composer.json file for this function:
{
"require": {
"alrik11es/cowsayphp": "^1.2"
}
}
A build.sh script is also required to install the packages:
#!/bin/bash
set -e
composer install
Make sure the above files are in a properly formatted project directory with an index.php file containing the main() entrypoint, then deploy with doctl serverless deploy <your-project-directory>. You may use the --remote-build flag to run the build remotely.
The runtime automatically takes care of requiring the vendor/autoload.php file, so you do not need to include this in your function.
Include Files in Built Function
To include arbitrary files with your deployed function (for example, config files and templates), place the files in your function directory. By default, all files in the function directory will be included in the deployed function. This can be customized using .ignore and .include files. See the Build Process reference for details.
Here is an example function that reads text content from a file:
Directory structure:
.
├── packages
│ └── <package-name>
│ └── <function-name>
│ ├── index.php
│ └── to_be_included.txt
└── project.yml
The index.php file:
<?php
function main() : array
{
$fileContents = file_get_contents('to_be_included.txt');
return ["body" => "File contents: \"$fileContents\""];
}
The file to include, to_be_included.txt:
Hello, World!
When invoked, the response is:
File contents: "Hello, World!"