AWS CDK constructs for PHP on AWS Lambda

The Bref  CDK constructs let you deploy serverless PHP applications on AWS Lambda using the AWS CDK.

By default, Bref deploys using the Serverless Framework. Using the AWS CDK is an alternative, but be aware that this is an advanced topic. If you are lost, follow the Bref documentation instead.

Installation

Install the package  with NPM:

npm install @bref.sh/constructs

Usage

Simple example to deploy an HTTP application:

import { Construct } from 'constructs';
import { App, CfnOutput, Stack, StackProps } from 'aws-cdk-lib';
import { HttpApi } from 'aws-cdk-lib/aws-apigatewayv2';
import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
import { PhpFpmFunction } from '@bref.sh/constructs';
 
class MyStack extends Stack {
    constructor(scope: Construct, id: string, props?: StackProps) {
        super(scope, id, props);
 
        const web = new PhpFpmFunction(this, 'Web', {
            handler: 'public/index.php',
        });
 
        // Send all HTTP requests to the function
        const api = new HttpApi(this, 'Api', {
            defaultIntegration: new HttpLambdaIntegration('WebIntegration', web),
        });
        new CfnOutput(this, 'Url', { value: api.url! });
    }
}
 
const app = new App();
new MyStack(app, 'my-app', {
    env: {
        // The region must be set explicitly
        region: 'eu-west-1',
    },
});

PhpFpmFunction only creates the Lambda function: it must be exposed over HTTP, here with an HTTP API. Alternatively, a Lambda function URL works too:

import { FunctionUrlAuthType } from 'aws-cdk-lib/aws-lambda';
 
const url = web.addFunctionUrl({ authType: FunctionUrlAuthType.NONE });
new CfnOutput(this, 'Url', { value: url.url });

The region of the stack must be set explicitly (env.region): Bref uses it to pick the Lambda layers of that region.

Install the dependencies (composer install --no-dev) before deploying: the code is zipped from the current directory. Then deploy with the AWS CDK CLI:

# Once per AWS account and region
npx cdk bootstrap
 
npx cdk deploy

Options

All constructs accept the options of the AWS CDK Function construct, plus phpVersion. For example:

import { Architecture, LayerVersion } from 'aws-cdk-lib/aws-lambda';
 
new PhpFpmFunction(this, 'Web', {
    handler: 'public/index.php',
    phpVersion: '8.5',
    // Run on ARM processors: Bref picks the ARM layers
    architecture: Architecture.ARM_64,
    // Extra layers, for example extra PHP extensions, are added after the PHP layer
    layers: [
        LayerVersion.fromLayerVersionArn(this, 'Redis', '<layer ARN>'),
    ],
});

• phpVersion: 8.2, 8.3, 8.4 (default) or 8.5.
• architecture: Architecture.X86_64 (default) or Architecture.ARM_64.
• layers: extra layers, like extra PHP extensions. Use the ARN of the layer for the same region, PHP version and architecture as the function.

Constructs

Functions

PhpFpmFunction

This construct deploys a PHP function with the PHP-FPM runtime.

new PhpFpmFunction(this, 'MyFunction', {
    handler: 'public/index.php',
});

It inherits from the AWS CDK Function construct with these options set by default:

• handler: index.php by default
• runtime: provided.al2023
• code: the code is automatically zipped from the current directory.
• layers: the Bref layer is automatically added.
• memorySize: 1024
• timeout: 28 (seconds)

The code is automatically zipped from the current directory. You can override this behavior by setting the code property:

import { packagePhpCode } from '@bref.sh/constructs';
 
new PhpFpmFunction(this, 'MyFunction', {
    code: packagePhpCode('custom-path', {
        exclude: ['docs'],
    }),
});

The following paths are always excluded: .git, .idea, cdk.out, node_modules, .bref, .serverless, tests.

The construct also adds the following options:

• phpVersion (default: 8.4): the PHP version to use (8.2, 8.3, 8.4 or 8.5).

PhpFunction

This construct deploys a PHP function with the “event-driven function” runtime.

new PhpFunction(this, 'MyFunction', {
    handler: 'my-handler.php',
});

It inherits from the AWS CDK Function construct with these options set by default:

• runtime: provided.al2023
• code: the code is automatically zipped from the current directory.
• layers: the Bref layer is automatically added.
• memorySize: 1024
• timeout: 6 (seconds)

The code is automatically zipped from the current directory. You can override this behavior by setting the code property:

import { packagePhpCode } from '@bref.sh/constructs';
 
new PhpFunction(this, 'MyFunction', {
    // ...
    code: packagePhpCode('custom-path', {
        exclude: ['docs'],
    }),
});

The following paths are always excluded: .git, .idea, cdk.out, node_modules, .bref, .serverless, tests.

The construct also adds the following options:

• phpVersion (default: 8.4): the PHP version to use (8.2, 8.3, 8.4 or 8.5).

ConsoleFunction

This construct deploys a PHP function with the “console” runtime.

new ConsoleFunction(this, 'Artisan', {
    handler: 'artisan',
});

It inherits from the AWS CDK Function construct with these options set by default:

• runtime: provided.al2023
• code: the code is automatically zipped from the current directory.
• layers: the Bref layer is automatically added.
• memorySize: 1024
• timeout: 6 (seconds)

The code is automatically zipped from the current directory. You can override this behavior by setting the code property:

import { packagePhpCode } from '@bref.sh/constructs';
 
new ConsoleFunction(this, 'Artisan', {
    // ...
    code: packagePhpCode('custom-path', {
        exclude: ['docs'],
    }),
});

The following paths are always excluded: .git, .idea, cdk.out, node_modules, .bref, .serverless, tests.

The construct also adds the following options:

• phpVersion (default: 8.4): the PHP version to use (8.2, 8.3, 8.4 or 8.5).