Skip to Content
🎉 Bref 3.0 is released. Read more →
DocumentationLocal developmentEvent-driven functions

Local development for functions

It is possible to run event-driven functions locally.

To run HTTP applications (like Laravel or Symfony) locally, read Local development for HTTP applications instead.

Running functions locally

The vendor/bin/bref-local command invokes your PHP functions locally, using PHP installed on your machine. It works whether you deploy with Bref Cloud, the serverless CLI, or another tool. You can provide an event if your function expects one.

For example, given this function:

my-function.php
<?php
 
require __DIR__ . '/vendor/autoload.php';
 
return function ($event) {
    return 'Hello ' . ($event['name'] ?? 'world');
};

You can invoke it with or without event data:

$ vendor/bin/bref-local <handler> <event-data>
 
# For example
$ vendor/bin/bref-local my-function.php
START
END Duration: 1 ms Max Memory Used: 1 MB
 
"Hello world"
 
# With JSON event data
$ vendor/bin/bref-local my-function.php '{"name": "Jane"}'
START
END Duration: 1 ms Max Memory Used: 1 MB
 
"Hello Jane"
 
# With a path to a file containing a JSON event
$ vendor/bin/bref-local --path event.json my-function.php

The result returned by the function is displayed encoded as JSON, after the logs of the invocation.

If your handler is a class retrieved from the Laravel or Symfony container, use the class name as the handler:

$ vendor/bin/bref-local 'App\MyHandler' '{"name": "Jane"}'

On Windows PowerShell, you must escape the “double quote” char if you write JSON directly in the CLI. Example:

$ vendor/bin/bref-local my-function.php '{\"name\": \"Bill\"}'

With the serverless CLI

If you use serverless.yml, the serverless bref:local command is a shortcut that finds the handler from the function name:

serverless.yml
# ...
 
functions:
    hello:
        handler: my-function.php
        runtime: php-84
$ serverless bref:local -f hello
 
# With JSON event data
$ serverless bref:local -f hello --data '{"name": "Jane"}'
 
# With JSON in a file
$ serverless bref:local -f hello --path=event.json

The serverless bref:local command is a simpler alternative to the native serverless invoke local command, which tries to run PHP using Docker with very little success. Use serverless bref:local instead of serverless invoke local.

These commands run using the local PHP installation. If you prefer to use Docker, check out the “With Docker” section below.

With Docker

If you want to run your function in Docker:

$ docker run --rm -it --entrypoint= -v $(pwd):/var/task:ro bref/php-84:3 vendor/bin/bref-local my-function.php
 
# You can also use the `dev` images for a simpler command (and Xdebug in the image):
$ docker run --rm -it -v $(pwd):/var/task:ro bref/php-84-dev:3 vendor/bin/bref-local my-function.php

You can also use Docker Compose, like described in Local development for HTTP applications:

docker-compose.yml
services:
    app:
        image: bref/php-84-dev:3
        volumes:
            - .:/var/task

Then run functions:

$ docker compose run app vendor/bin/bref-local my-function.php

Sample events

Handlers like SqsHandler, S3Handler or EventBridgeHandler expect the event that AWS sends, for example an SQS event must contain Records. Save a sample event in a JSON file, adapt it (message body, bucket name, object key…), and pass it with --path:

$ vendor/bin/bref-local --path events/sqs.json my-function.php
 
# With the serverless CLI
$ serverless bref:local -f worker --path events/sqs.json

Here are short sample events for the most common event sources:

events/sqs.json
{
    "Records": [
        {
            "messageId": "059f36b4-87a3-44ab-83d2-661975830a7d",
            "receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...",
            "body": "{\"orderId\": 1234}",
            "attributes": {
                "ApproximateReceiveCount": "1",
                "SentTimestamp": "1545082649183",
                "SenderId": "AIDAIENQZJOLO23YVJ4VO",
                "ApproximateFirstReceiveTimestamp": "1545082649185"
            },
            "messageAttributes": {},
            "eventSource": "aws:sqs",
            "eventSourceARN": "arn:aws:sqs:us-east-1:123456789012:my-queue",
            "awsRegion": "us-east-1"
        }
    ]
}

For other event sources, or the complete events:

  • the Test tab of a function in the Lambda console has event templates for most event sources,
  • the AWS SAM CLI generates events, for example sam local generate-event s3 put --bucket my-bucket > events/s3.json (run sam local generate-event to list them),
  • Bref’s test fixtures  contain events for every event source supported by Bref, including Kinesis, Kafka and WebSocket events.

API Gateway local development

If you build HTTP applications with PSR-15 handlers and the event-driven function runtime, bref-local is a bit impractical because you need to manually craft HTTP events in JSON.

Instead, you can use the bref/dev-server package to emulate API Gateway locally. Note that bref/dev-server requires symfony/console 6 or lower: it cannot be installed in projects that use symfony/console 7 or greater (for example Laravel 11 and later, or Symfony 7 and later).

Last updated on
Local developmentMonitoring