Serverless Runtime

A Symfony Runtime implementation for AWS Lambda. Run a standard Symfony application on Lambda with no code changes to your controllers, services, or templates.

How it works

The Symfony Runtime component decouples your application from how it's executed. This package provides a Runtime that translates API Gateway v2.0 (HTTP API) events into Symfony Request objects and returns the Response as a Lambda-compatible payload. Console commands are supported via a console key in the event payload.

Your application code stays the same whether it runs on a traditional web server or on Lambda.

Installation

composer require likeuntomurphy/serverless-runtime

Usage

Create a bootstrap file in your project root:

#!/opt/php/bin/php
<?php

use App\Kernel;

$_SERVER['APP_RUNTIME'] = Likeuntomurphy\Serverless\Runtime\Runtime::class;

require __DIR__.'/vendor/autoload_runtime.php';

return function (array $context) {
    return new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
};

This is identical to a standard Symfony public/index.php — the only difference is the APP_RUNTIME override.

What it handles

• HTTP requests via API Gateway v2.0 (HTTP API) payloads
• Form submissions with application/x-www-form-urlencoded body parsing
• Cookies from both the cookies array (API Gateway v2.0) and the cookie header
• Base64-encoded bodies are decoded automatically when isBase64Encoded is true
• Multi-value response headers are joined per RFC 9110
• Set-Cookie headers are returned via the API Gateway cookies array
• Console commands via a {"console": "cache:clear"} event payload
• Kernel termination is called after each request for cleanup

Console commands

Invoke any Symfony console command from Lambda:

aws lambda invoke --function-name my-app \
  --payload '{"console": "cache:clear"}' \
  --cli-binary-format raw-in-base64-out \
  /tmp/output.json

The response contains the exit code and output:

{"exitCode": 0, "output": "..."}

Environment variables

Variable	Description
AWS_LAMBDA_RUNTIME_API	Set automatically by Lambda
APP_ENV	Symfony environment (resolved by SymfonyRuntime)
APP_DEBUG	Debug mode (resolved by SymfonyRuntime)
APP_RUNTIME_MODE	Set to web=1 for proper error rendering in Lambda's CLI SAPI
DEFAULT_URI	Fallback host for request generation (e.g. https://example.com)

Architecture

Two classes:

• Runtime extends SymfonyRuntime and overrides getRunner() to return a Runner when the application is a KernelInterface.
• Runner implements RunnerInterface and runs the Lambda event loop: poll for events, translate to Symfony requests, return responses.

For non-kernel applications (e.g. a standalone Console\Application), the runtime delegates to the parent SymfonyRuntime.

Requirements

• PHP >= 8.5
• symfony/runtime ^8.0
• symfony/http-kernel ^8.0
• symfony/http-client ^8.0

License

MIT