PHPackages                             runtime/bref - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. runtime/bref

ActiveLibrary[Utility & Helpers](/categories/utility)

runtime/bref
============

Bref runtime

1.0.0(6mo ago)19107.9k↓78%1MITPHPPHP >=8.0.5

Since Apr 29Pushed 6mo ago3 watchersCompare

[ Source](https://github.com/php-runtime/bref)[ Packagist](https://packagist.org/packages/runtime/bref)[ GitHub Sponsors](https://github.com/nyholm)[ RSS](/packages/runtime-bref/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (9)Dependencies (10)Versions (10)Used By (0)

Bref Runtime
============

[](#bref-runtime)

Deploy an application with AWS Lambda using Bref.

We support all kinds of applications. See the following sections for details.

1. [Installation and usage](#installation)
2. [Symfony application](#symfony-application)
3. [Laravel application](#laravel-application)
4. [PSR-15 application](#psr-15-application)
5. [Console application](#console-application)
6. [PSR-11 container application](#psr-11-container)
    1. [Invoke handlers locally](#invoke-handlers-locally)
    2. [Simplify serverless.yml](#simplify-serverlessyml)
    3. [Typed handlers](#typed-handlers)
    4. [Symfony Messenger integration](#symfony-messenger-integration)

If you are new to the Symfony Runtime component, read more in the [main readme](https://github.com/php-runtime/runtime).

Installation
------------

[](#installation)

```
composer require runtime/bref

```

To get started, we need a `serverless.yml` file in our projects root. We also use the `./vendor/runtime/bref-layer` plugin. Now we can tell AWS that we want to use a "layer" called `${runtime-bref:php-80}` to run our application on.

Next we need to define the environment variable `APP_RUNTIME` so the Runtime component knows what runtime to use.

```
# serverless.yml
service: my-app-name

plugins:
    - ./vendor/runtime/bref-layer # make(Kernel::class);
};
```

Now you are up and running on AWS Lambda!

See [`runtime/laravel`](https://github.com/php-runtime/laravel) on how to run this locally.

PSR-15 application
------------------

[](#psr-15-application)

You need some extra features from Bref. Install it with

```
composer req bref/bref

```

Bref is using [`nyholm/psr7`](https://github.com/nyholm/psr7) to provide a PSR-7 and PSR-15 experience. See [`runtime/psr-nyholm`](https://github.com/php-runtime/psr-nyholm)how to run your application locally.

The following code is an example PSR-15 application with the Runtime component. If it works locally it will also with on AWS Lambda.

```
// public/index.php

use Nyholm\Psr7\Response;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;

require_once dirname(__DIR__).'/vendor/autoload_runtime.php';

return function () {
    return new class implements RequestHandlerInterface {
        public function handle(ServerRequestInterface $request): ResponseInterface
        {
            $name = $request->getQueryParams()['name'] ?? 'world';

            return new Response(200, [], "Hello $name");
        }
    };
};
```

Console application
-------------------

[](#console-application)

Use the standard Symfony 5.3+ `bin/console`.

```
// bin/console

use App\Kernel;
use Symfony\Bundle\FrameworkBundle\Console\Application;

require_once dirname(__DIR__).'/vendor/autoload_runtime.php';

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

    return new Application($kernel);
};
```

```
# serverless.yml

# ...

functions:
    console:
        handler: bin/console
        timeout: 120
        layers:
           - ${runtime-bref:php-80}
        events:
            - schedule:
                rate: rate(30 minutes)
                input: '"app:invoice:send"'
```

PSR-11 Container
----------------

[](#psr-11-container)

The PSR-11 container is great. It really shines in internal microservices where you dont have to deal with HTTP or security. Your application just call your microservice using an AWS Lambda api client (ie `aws/aws-sdk-php` or `async-aws/lambda`). It is also great for reacting to S3 or SQS events.

The first thing we need is a file that returns a PSR-11 container. See below for an example for Symfony.

```
// bin/container.php

use App\Kernel;

require_once dirname(__DIR__).'/vendor/autoload_runtime.php';

return function (array $context) {
    $kernel =  new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
    $kernel->boot();

    return $kernel->getContainer();
};
```

Now we write a class/service that implements `Bref\Event\Handler`.

```
namespace App\Lambda;

use Bref\Context\Context;
use Bref\Event\Handler;

class HelloWorld implements Handler
{
    public function handle($event, Context $context)
    {
        return 'Hello ' . $event['name'];
    }
}
```

Now we need to update serverless.yml to say "Use bin/container.php to get the container and then load service App\\Lambda\\HelloWorld".

```
# serverless.yml

# ...

functions:
    hello:
        handler: bin/container.php:App\Lambda\HelloWorld
        layers:
            - ${runtime-bref:php-80}
```

When this is deployed it can be invoked by

```
serverless invoke --function hello --data '{"name":"Tobias"}'

```

Invoke handlers locally
-----------------------

[](#invoke-handlers-locally)

Using a service from the container makes the handlers very simple to unit test. However, if you are lazy, you may want to invoke them locally from CLI.

Run the following command to invoke the `App\Lambda\HelloWorld` service.

```
./vendor/bin/bref-local-handler.php ./bin/container.php:App\\Lambda\\HelloWorld

```

If your service expects some event data, add it as a JSON string or a path to a file containing JSON.

```
./vendor/bin/bref-local-handler.php ./bin/container.php:App\\Lambda\\HelloWorld '{"foo":"bar"}'

./vendor/bin/bref-local-handler.php ./bin/container.php:App\\Lambda\\HelloWorld example/input.json

```

### Simplify serverless.yml

[](#simplify-serverlessyml)

The syntax `handler: bin/container.php:App\Lambda\HelloWorld` might be a bit weird to write, but you may add an environment variable called `FALLBACK_CONTAINER_FILE` which includes the file to where we can get the PSR-11 container. This may help the serverless.yml file to read more natually.

```
 # serverless.yml

 provider:
     name: aws
     runtime: provided.al2
     # ...
     environment:
        APP_ENV: prod
        APP_RUNTIME: Runtime\Bref\Runtime
+       FALLBACK_CONTAINER_FILE: bin/container.php
        BREF_LOOP_MAX: 100 # Optional

 functions:
     hello:
-        handler: bin/container.php:App\Lambda\HelloWorld
+        handler: App\Lambda\HelloWorld
         layers:
           - ${runtime-bref:php-80}
```

Typed handlers
--------------

[](#typed-handlers)

To better integrate with different AWS events, one can use "typed handlers". These are classes that implements `Bref\Event\Handler` and provides some helper methods or classes.

To use them, you need to install Bref:

```
composer req bref/bref

```

We use the same PSR-11 configuration from above and write custom handler like:

```
namespace App\Lambda;

use Bref\Context\Context;
use Bref\Event\S3\S3Event;
use Bref\Event\S3\S3Handler;

class S3FileCreated extends S3Handler
{
    public function handleS3(S3Event $event, Context $context): void
    {
        $bucketName = $event->getRecords()[0]->getBucket()->getName();
        $fileName = $event->getRecords()[0]->getObject()->getKey();

        // do something with the file
    }
}
```

```
# serverless.yml

# ...

functions:
    s3_photos:
        handler: bin/container.php:App\Lambda\S3FileCreated
        layers:
            - ${runtime-bref:php-80}
        events:
            - s3:
                  bucket: photos
                  event: s3:ObjectCreated:*
```

Read more about different typed handlers at [Bref's documentation](https://bref.sh/docs/function/handlers.html).

### Symfony Messenger integration

[](#symfony-messenger-integration)

Similar to the typed handlers above, if you use [`bref/symfony-messenger`](https://github.com/brefphp/symfony-messenger)you may also want to define a worker function.

```
# serverless.yml

# ...

functions:
    worker:
        handler: bin/container.php:Bref\Symfony\Messenger\Service\Sqs\SqsConsumer
        timeout: 120
        layers:
            - ${runtime-bref:php-80}
        events:
            - sqs:
                  batchSize: 1 # Only 1 item at a time to simplify error handling
                  arn: !GetAtt workqueue.Arn

resources:
    Resources:
        workqueue:
            Type: "AWS::SQS::Queue"
            Properties:
                QueueName: ${self:service}-workqueue
                VisibilityTimeout: 600
```

###  Health Score

49

—

FairBetter than 94% of packages

Maintenance66

Regular maintenance activity

Popularity37

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity63

Established project with proven stability

 Bus Factor1

Top contributor holds 81.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~211 days

Recently: every ~387 days

Total

9

Last Release

198d ago

Major Versions

0.4.0 → 1.0.02025-12-18

### Community

Maintainers

![](https://www.gravatar.com/avatar/401ccc5eea13c60cf807ae982af00e368e2166e2f26d8eb541dcd881a57385bc?d=identicon)[Nyholm](/maintainers/Nyholm)

---

Top Contributors

[![Nyholm](https://avatars.githubusercontent.com/u/1275206?v=4)](https://github.com/Nyholm "Nyholm (44 commits)")[![GrahamCampbell](https://avatars.githubusercontent.com/u/2829600?v=4)](https://github.com/GrahamCampbell "GrahamCampbell (2 commits)")[![thecaliskan](https://avatars.githubusercontent.com/u/13554944?v=4)](https://github.com/thecaliskan "thecaliskan (2 commits)")[![vhenzl](https://avatars.githubusercontent.com/u/243381?v=4)](https://github.com/vhenzl "vhenzl (2 commits)")[![alexander-schranz](https://avatars.githubusercontent.com/u/1698337?v=4)](https://github.com/alexander-schranz "alexander-schranz (2 commits)")[![dmerchier](https://avatars.githubusercontent.com/u/9839957?v=4)](https://github.com/dmerchier "dmerchier (1 commits)")[![chalasr](https://avatars.githubusercontent.com/u/7502063?v=4)](https://github.com/chalasr "chalasr (1 commits)")

---

Tags

brefbrefphpruntime

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/runtime-bref/health.svg)

```
[![Health](https://phpackages.com/badges/runtime-bref/health.svg)](https://phpackages.com/packages/runtime-bref)
```

###  Alternatives

[bref/bref

Bref is a framework to write and deploy serverless PHP applications on AWS Lambda.

3.4k10.6M67](/packages/bref-bref)[mcp/sdk

Model Context Protocol SDK for Client and Server applications in PHP

1.5k1.5M88](/packages/mcp-sdk)[bref/symfony-bridge

Makes Symfony work on AWS Lambda with Bref

501.9M9](/packages/bref-symfony-bridge)[flarum/core

Delightfully simple forum software.

201.4M2.3k](/packages/flarum-core)[jaxon-php/jaxon-core

Jaxon is an open source PHP library for easily creating Ajax web applications

74149.4k30](/packages/jaxon-php-jaxon-core)[ronasit/laravel-helpers

Provided helpers function and some helper class.

2085.6k31](/packages/ronasit-laravel-helpers)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)