{"id":15916884,"url":"https://github.com/xp-forge/lambda","last_synced_at":"2026-02-22T16:28:46.574Z","repository":{"id":45624409,"uuid":"398353215","full_name":"xp-forge/lambda","owner":"xp-forge","description":"AWS Lambda for the XP Framework","archived":false,"fork":false,"pushed_at":"2025-05-04T17:21:06.000Z","size":218,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-05T16:16:17.411Z","etag":null,"topics":["aws","aws-lambda","lambda","php7","php8","response-streaming","serverless","xp-framework"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xp-forge.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-20T17:27:14.000Z","updated_at":"2025-05-04T17:20:33.000Z","dependencies_parsed_at":"2024-03-01T21:32:09.321Z","dependency_job_id":"74df35a1-2497-4a90-8259-8ac9f0936375","html_url":"https://github.com/xp-forge/lambda","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xp-forge%2Flambda","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xp-forge%2Flambda/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xp-forge%2Flambda/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xp-forge%2Flambda/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xp-forge","download_url":"https://codeload.github.com/xp-forge/lambda/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xp-forge%2Flambda/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259172919,"owners_count":22816552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-lambda","lambda","php7","php8","response-streaming","serverless","xp-framework"],"created_at":"2024-10-06T18:06:15.380Z","updated_at":"2026-02-22T16:28:46.537Z","avatar_url":"https://github.com/xp-forge.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"AWS Lambda for the XP Framework\n========================================================================\n\n[![Build status on GitHub](https://github.com/xp-forge/lambda/workflows/Tests/badge.svg)](https://github.com/xp-forge/lambda/actions)\n[![XP Framework Module](https://raw.githubusercontent.com/xp-framework/web/master/static/xp-framework-badge.png)](https://github.com/xp-framework/core)\n[![BSD Licence](https://raw.githubusercontent.com/xp-framework/web/master/static/licence-bsd.png)](https://github.com/xp-framework/core/blob/master/LICENCE.md)\n[![Requires PHP 7.4+](https://raw.githubusercontent.com/xp-framework/web/master/static/php-7_4plus.svg)](http://php.net/)\n[![Supports PHP 8.0+](https://raw.githubusercontent.com/xp-framework/web/master/static/php-8_0plus.svg)](http://php.net/)\n[![Latest Stable Version](https://poser.pugx.org/xp-forge/lambda/version.svg)](https://packagist.org/packages/xp-forge/lambda)\n\nServerless infrastructure.\n\nExample\n-------\nPut this code in a file called *Greet.class.php*:\n\n```php\nuse com\\amazon\\aws\\lambda\\Handler;\n\nclass Greet extends Handler {\n\n  /** @return callable|com.amazon.aws.lambda.Lambda|com.amazon.aws.lambda.Streaming */\n  public function target() {\n    return fn($event, $context) =\u003e sprintf(\n      'Hello %s from PHP %s via %s @ %s',\n      $event['name'],\n      PHP_VERSION,\n      $context-\u003efunctionName,\n      $context-\u003eregion\n    );\n  }\n}\n```\n\nThe two parameters passed are *$event* (a value [depending on where the lambda was invoked from](https://docs.aws.amazon.com/lambda/latest/dg/lambda-services.html)) and *$context* (a Context instance, see [below](https://github.com/xp-forge/lambda#context)).\n\n### Initialization\n\nIf you need to run any initialization code, you can do so before returning the lambda from *target()*. This code is only run once during the [init phase](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtime-environment.html#runtimes-lifecycle):\n\n```php\nuse com\\amazon\\aws\\lambda\\Handler;\n\nclass Greet extends Handler {\n\n  /** @return callable|com.amazon.aws.lambda.Lambda|com.amazon.aws.lambda.Streaming */\n  public function target() {\n    $default= $this-\u003eenvironment-\u003eproperties('task')-\u003ereadString('greet', 'default');\n\n    return fn($event, $context) =\u003e sprintf(\n      'Hello %s from PHP %s via %s @ %s',\n      $event['name'] ?? $default,\n      PHP_VERSION,\n      $context-\u003efunctionName,\n      $context-\u003eregion\n    );\n  }\n}\n```\n\nThe lambda's environment accessible via *$this-\u003eenvironment* is an Environment instance, see [below](https://github.com/xp-forge/lambda#environment).\n\n### Logging\n\nTo write output to the lambda's log stream, use *trace()*:\n\n```php\nuse com\\amazon\\aws\\lambda\\Handler;\n\nclass Greet extends Handler {\n\n  /** @return callable|com.amazon.aws.lambda.Lambda|com.amazon.aws.lambda.Streaming */\n  public function target() {\n    return function($event, $context) {\n      $this-\u003eenvironment-\u003etrace('Invoked with ', $event);\n\n      return sprintf(/* Shortened for brevity */);\n    };\n  }\n}\n```\n\nAny non-string arguments passed will be converted to string using `util.Objects::stringOf()`. To integrate with [XP logging](https://github.com/xp-framework/logging), pass the environment's writer to the console appender, e.g. by using `$cat= Logging::all()-\u003etoConsole($this-\u003eenvironment-\u003ewriter)`.\n\n### Response streaming\n\nThis library supports AWS Lambda response streaming as [announced by AWS in April 2023](https://aws.amazon.com/de/blogs/compute/introducing-aws-lambda-response-streaming/). To use the stream, return a `function(var, Stream, Context)` from the handler's *target()* method instead of a `function(var, Context)`:\n\n```php\nuse com\\amazon\\aws\\lambda\\{Context, Handler, Stream};\n\nclass Streamed extends Handler {\n\n  public function target(): callable {\n    return function($event, Stream $stream, Context $context) {\n      $stream-\u003euse('text/plain');\n      $stream-\u003ewrite(\"[\".date('r').\"] Hello world...\\n\");\n\n      sleep(1);\n\n      $stream-\u003ewrite(\"[\".date('r').\"] ...from Lambda\\n\");\n      $stream-\u003eend();\n    };\n  }\n}\n```\n\nInvoking this lambda will yield the following:\n\n![Streaming in Terminal](https://github.com/xp-forge/lambda/assets/696742/41785beb-3903-45a0-a2ec-2c7c27c2c7b4)\n\nThe *Stream* interface is defined as follows:\n\n```php\npublic interface com.amazon.aws.lambda.Stream extends io.streams.OutputStream, lang.Closeable {\n  public function transmit(io.Channel|io.streams.InputStream $source, string $mimeType): void\n  public function use(string $mimeType): void\n  public function write(string $bytes): void\n  public function end(): void\n  public function flush(): void\n  public function close(): var\n}\n```\n\nDevelopment\n-----------\nTo run your lambda locally, use the following:\n\n```bash\n$ xp lambda run Greet '{\"name\":\"Timm\"}'\nHello Timm from PHP 8.2.11 via Greet @ test-local-1\n```\n\n*This does not provide a complete lambda environment, and does not have any execution limits imposed on it! To detect this programmatically, use `$this-\u003eenvironment-\u003elocal()`, which will return true.*\n\nIntegration testing\n-------------------\nTo test your lambda inside a local containerized lambda environment, use the *test* command.\n\n```bash\n$ xp lambda test Greet '{\"name\":\"Timm\"}'\nSTART RequestId: 9ff45cda-df9b-1b8c-c21b-5fe27c8f2d24 Version: $LATEST\nEND RequestId: 9ff45cda-df9b-1b8c-c21b-5fe27c8f2d24\nREPORT RequestId: 9ff45cda-df9b-1b8c-c21b-5fe27c8f2d24  Init Duration: 922.19 ms...\n\"Hello Timm from PHP 8.2.11 via test @ us-east-1\"\n```\n\n*This functionality is provided by the [AWS Lambda base images for custom runtimes](https://gallery.ecr.aws/lambda/provided). Although this also runs on your machine, `$this-\u003eenvironment-\u003elocal()` will return false.*\n\nSetup\n-----\nThe first step is to create and publish the runtime layer:\n\n```bash\n$ xp lambda runtime\n$ aws lambda publish-layer-version \\\n  --layer-name lambda-xp-runtime \\\n  --zip-file fileb://./runtime-X.X.X.zip \\\n  --region us-east-1\n```\n\n...and create a role:\n\n```bash\n$ cat \u003e /tmp/trust-policy.json\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [{\n    \"Effect\": \"Allow\",\n    \"Principal\": {\"Service\": \"lambda.amazonaws.com\"},\n    \"Action\": \"sts:AssumeRole\"\n  }]\n}\n$ aws iam create-role \\\n  --role-name InvokeLambda \\\n  --path \"/service-role/\" \\\n  --assume-role-policy-document file:///tmp/trust-policy.json\n```\n\nAfter ensuring your dependencies are up-to-date using composer, create the function:\n\n```bash\n$ xp lambda package Greet.class.php\n$ aws lambda create-function \\\n  --function-name greet \\\n  --handler Greet \\\n  --zip-file fileb://./function.zip \\\n  --runtime provided.al2 \\\n  --role \"arn:aws:iam::XXXXXXXXXXXX:role/service-role/InvokeLambda\" \\\n  --region us-east-1 \\\n  --layers \"arn:aws:lambda:us-east-1:XXXXXXXXXXXX:layer:lambda-xp-runtime:1\"\n```\n\nInvocation\n----------\nTo invoke the function:\n\n```bash\n$ aws lambda invoke \\\n  --cli-binary-format raw-in-base64-out \\\n  --function-name greet \\\n  --payload '{\"name\":\"Timm\"}'\n  response.json\n$ cat response.json\n\"Hello Timm from PHP 8.0.10 via greet @ us-east-1\"\n```\n\nDeploying changes\n-----------------\nAfter having initially created your lambda, you can update its code as follows:\n\n```bash\n$ xp lambda package Greet.class.php\n$ aws lambda update-function-code \\\n  --function-name greet \\\n  --zip-file fileb://./function.zip \\\n  --publish\n```\n\nUpgrading the runtime\n---------------------\nTo upgrade an existing runtime layer, build the new runtime and publish a new version by calling the following to create a new version:\n\n```bash\n$ xp lambda runtime\n$ aws lambda publish-layer-version \\\n  --layer-name lambda-xp-runtime \\\n  --zip-file fileb://./runtime-X.X.X.zip \\\n  --region us-east-1\n```\n\nNow, switch the function over to use this new layer:\n\n```bash\n$ aws lambda update-function-configuration \\\n  --function-name greet \\\n  --layers \"arn:aws:lambda:us-east-1:XXXXXXXXXXXX:layer:lambda-xp-runtime:2\"\n```\n\nUsing other AWS services\n------------------------\nIn order to programmatically use other AWS services use the *ServiceEndpoint* class:\n\n```php\nuse com\\amazon\\aws\\{Credentials, ServiceEndpoint};\nuse com\\amazon\\aws\\lambda\\Handler;\n\nclass WebSockets extends Handler {\n\n  /** @return callable|com.amazon.aws.lambda.Lambda|com.amazon.aws.lambda.Streaming */\n  public function target() {\n    return function($event, $context) {\n\n      // Send message to WebSocket connection\n      $this-\u003eenvironment-\u003eendpoint('execute-api')\n        -\u003ein($context-\u003eregion)\n        -\u003eusing($event['requestContext']['apiId'])\n        -\u003eresource('/{stage}/@connections/{connectionId}', $event['requestContext'])\n        -\u003etransmit(['message' =\u003e 'Reply'])\n      ;\n      return ['statusCode' =\u003e 200];\n    };\n  }\n}\n```\n\nTo test this locally, pass the necessary environment variables via *-e* on the command line:\n\n```bash\n$ xp lambda test -e AWS_ACCESS_KEY_ID=... -e AWS_SECRET_ACCESS_KEY=... WebSockets '{\"requestContext\":...}'\n# ...\n```\n\nContext\n-------\nThe context object passed to the target lambda is defined as follows:\n\n```php\npublic class com.amazon.aws.lambda.Context implements lang.Value {\n  public string $awsRequestId\n  public string $invokedFunctionArn\n  public string $traceId\n  public string $clientContext\n  public string $cognitoIdentity\n  public string $deadline\n  public string $functionName\n  public string $functionVersion\n  public string $memoryLimitInMB\n  public string $logGroupName\n  public string $logStreamName\n  public string $region\n  public int $payloadLength\n\n  public function __construct(array $headers, array $environment)\n\n  public function remainingTime(?float $now): ?float\n  public function toString(): string\n  public function hashCode(): string\n  public function compareTo(var $value): int\n}\n```\n\nEnvironment\n-----------\nThe runtime environment is defined as follows:\n\n```php\npublic class com.amazon.aws.lambda.Environment {\n  public string $root\n  public [:string] $variables\n  public io.streams.StringWriter $writer\n  public util.PropertySource $properties\n\n  public function __construct(string $root, ?io.streams.StringWriter $writer)\n\n  public function taskroot(): io.Path\n  public function path(string $path): io.Path\n  public function tempDir(): io.Path\n  public function local(): bool\n  public function variable(string $name): ?string\n  public function credentials(): com.amazon.aws.Credentials\n  public function trace(var... $args): void\n  public function properties(string $name): util.PropertyAccess\n}\n```\n\nInterfaces\n----------\nInstead of functions, a handler's *target()* method may also return instances implementing the *Lambda* or *Streaming* interfaces:\n\n```php\npublic interface com.amazon.aws.lambda.Lambda {\n  public function process(var $event, com.amazon.aws.lambda.Context $context): var\n}\n\npublic interface com.amazon.aws.lambda.Streaming {\n  public function handle(\n    var $event,\n    com.amazon.aws.lambda.Stream $stream,\n    com.amazon.aws.lambda.Context $context\n  ): void\n}\n```\n\nSee also\n--------\n* [What is AWS Lambda?](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)\n* [AWS Lambda Webservices for the XP Framework](https://github.com/xp-forge/lambda-ws)\n* [AWS Core for the XP Framework](https://github.com/xp-forge/aws)\n* [Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html)\n* [AWS Lambda Custom Runtime for PHP: A Practical Example](https://aws.amazon.com/de/blogs/apn/aws-lambda-custom-runtime-for-php-a-practical-example/)\n* [AWS SDK for PHP](https://docs.aws.amazon.com/sdk-for-php/index.html)\n* [The Serverless LAMP stack - Community Resources](https://github.com/aws-samples/php-examples-for-aws-lambda/blob/master/serverless-php-resources.md)\n* [Configuring a Lambda function to stream responses](https://docs.aws.amazon.com/lambda/latest/dg/configuration-response-streaming.html)\n* [Implementing response streaming in a custom runtime](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-custom.html#runtimes-custom-response-streaming)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxp-forge%2Flambda","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxp-forge%2Flambda","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxp-forge%2Flambda/lists"}