Console commands

Bref provides a way to run console commands on AWS Lambda.

This can be used to run PHP scripts, the Symfony Console, as well as Laravel Artisan commands in production.

Configuration

The lambda function used for running console applications must use the php-xx-console runtime. Here is an example serverless.yml:

service: app
provider:
    name: aws
plugins:
    - ./vendor/bref/bref
functions:
    hello:
        handler: bin/console # or 'artisan' for Laravel
        runtime: php-81-console

Behind the scenes, the php-xx-console runtime will deploy a Lambda function configured to use Bref's php-81 AWS Lambda layer plus Bref's console layer (read more about these in the runtimes documentation).

Usage

To run a console command on AWS Lambda, run serverless bref:cli on your computer:

serverless bref:cli --args="<command to run in lambda>"

The bref:cli command will automatically detect which function (in serverless.yml) uses the console runtime and will run the command on that function.

Pass your command arguments and options in the --args flag (shortcut: -a). Remember to escape quotes properly. Some examples:

# Runs the CLI application without arguments and displays the help
$ serverless bref:cli
# ...

$ serverless bref:cli --args="doctrine:migrations:migrate"
Your database will be migrated.
To execute the SQL queries run the command with the `--force` option.

$ serverless bref:cli -a "doctrine:migrations:migrate --force"
Your database has been migrated.

$ serverless bref:cli --stage=prod -a "db:dump --file='/tmp/dump.sql' --verbose"
# ...

# You can use environment variables to configure AWS credentials (e.g. in CI)
$ AWS_ACCESS_KEY_ID=foo AWS_SECRET_ACCESS_KEY=bar serverless bref:cli
# ...

Usage without Serverless Framework

If you do not use serverless.yml but something else, like SAM/AWS CDK/Terraform, you can invoke your console function via the AWS CLI. For example:

aws lambda invoke \
    --function-name <console function name> \
    --region <region> \
    --cli-binary-format raw-in-base64-out \
    --payload '"<command arguments and options>"' \
    <file to store the output>.json

# For example:
aws lambda invoke \
    --function-name myapp-dev-myfunction \
    --region us-east-1 \
    --cli-binary-format raw-in-base64-out \
    --payload '"doctrine:migrations:migrate --force"' \
    response.json

# To extract the command output from the response.json file using jq
# https://stedolan.github.io/jq/
aws lambda invoke \
    --function-name myapp-dev-myfunction \
    --region us-east-1 \
    --cli-binary-format raw-in-base64-out \
    --payload '"doctrine:migrations:migrate --force"' \
    response.json && jq -r .output response.json

Note: The --payload needs to contain a JSON string, that is why it is quoted twice: '"..."'. This is intentional.

The Bref Dashboard also provides a convenient way to run commands via a terminal:

Functions using the "console" runtime are automatically detected, and colors are enabled by default for Laravel Artisan and Symfony Console.

Lambda context

Lambda provides information about the invocation, function, and execution environment via the lambda context.

This context is usually available as a parameter (alongside the event), within the defined handler. However, within the console runtime we do not have direct access to this parameter. To work around that, Bref puts the Lambda context in the $_SERVER['LAMBDA_INVOCATION_CONTEXT'] variable as a JSON-encoded string.

$lambdaContext = json_decode($_SERVER['LAMBDA_INVOCATION_CONTEXT'], true);