Upgrading to Bref 2.0

Updating dependencies

PHP 8 required

Bref 2.0 now requires PHP 8.0 or greater.

Composer Dependencies

You should update the bref/bref dependency in your application's composer.json file:

-    "bref/bref": "^1.0",
+    "bref/bref": "^2.0",

Then run composer update bref/bref --with-all-dependencies.

If you use the Bref Extra extensions (opens in a new tab), you also need to update the bref/extra-php-extensions package to version ^1.0.

Serverless Framework

If you are using Bref with Serverless Framework (opens in a new tab) (which is the default), Bref 2.0 requires Serverless Framework v3. Serverless Framework 2.x is no longer supported.

To check your Serverless Framework version, run:

serverless --version

If you need to upgrade, read the Serverless Framework documentation (opens in a new tab) (short version: run npm install -g serverless@3).

PHP runtimes

There is a new (simpler) syntax to use Bref's PHP runtimes in serverless.yml:

functions:
    hello:
        # ...
        runtime: php-81
        
        # instead of:
        runtime: provided.al2
        layers:
          - ${bref:layer.php-81}

The bref.sh (opens in a new tab) documentation now uses the simpler runtime: php-81 syntax, but ${bref:layer.php-xxx} variables still work! These variables are not deprecated. There are no breaking changes here.

Bref CLI

The following commands of vendor/bin/bref have changed:

vendor/bin/bref cli is replaced by the simpler serverless bref:cli.

For example:
```
vendor/bin/bref cli mystack-dev-artisan --region=eu-west-1 -- migrate --force
# becomes:
serverless bref:cli --args="migrate --force"
```
No need to provide the function name or the region anymore. Read the Console documentation to learn more. You will also find alternatives if you don't use the serverless CLI.
vendor/bin/bref local is replaced by the simpler serverless bref:local.

For example:
```
vendor/bin/bref local --handler=my-handler.php
# becomes:
serverless bref:local -f hello
```
No need to provide the handler file name anymore, we directly use the function name. The new serverless bref:local command has similar arguments as serverless invoke.

Read the Local Development documentation to learn more. You will also find alternatives if you don't use the serverless CLI.
vendor/bin/bref layers is replaced by the simpler serverless bref:layers.

Layer versions are also available at runtimes.bref.sh (opens in a new tab) if you don't use the serverless CLI.

These changes allowed us to simplify the commands (automatically use the AWS region, credentials and stage from the serverless CLI). It also allowed us to remove the biggest bref/bref Composer dependencies and make the package much lighter.

Development Docker images

The development Docker images have been simplified. You will need to update your docker-compose.yml.

Before (Bref v1):

services:
 
    web:
        image: bref/fpm-dev-gateway
        ports:
            - '8000:80'
        volumes:
            - .:/var/task
        depends_on:
            - php
        environment:
            HANDLER: public/index.php
            DOCUMENT_ROOT: public
 
    app:
        image: bref/php-80-fpm-dev
        volumes:
            - .:/var/task
 
    console:
        image: bref/php-80
        volumes:
            - .:/var/task
        entrypoint: php

After (Bref v2):

services:
    app:
        image: bref/php-80-fpm-dev:2
        ports: [ '8000:8000' ]
        volumes:
            - .:/var/task
        environment:
            HANDLER: public/index.php
            DOCUMENT_ROOT: public

The bref/php-XX-fpm-dev images can now run HTTP applications, console commands as well as event-driven functions too. Read more in web app local development.

The bref/fpm-dev-gateway image is no longer needed, and code running in bref/php-XX-fpm-dev now runs in an environment even closer to production.

Note: In order to be future-proof, we recommend to set the Bref major version in the Docker images. For example, with Bref 2, use bref/php-80-fpm-dev:2 instead of just bref/php-80-fpm-dev.

Smaller breaking changes that might impact you

The changes below should not impact the majority of users. However, if you are using any of these features, you might need to update your code.

Removed `separateVendor: true`

The separateVendor option (in serverless.yml) has been removed.

It allowed to deploy the vendor/ directory separately from the app to reduce the size of the deployment package. It was very buggy (contributed a long time ago and not maintained by anyone) and added a lot of technical debt.

Instead, when hitting the 250MB limit, you are encouraged to deploy via Docker images (opens in a new tab) instead (which have a limit of 10GB).

Removed `Bref\Lambda\SimpleLambdaClient`

The Bref\Lambda\SimpleLambdaClient class has been removed. It was a simple wrapper around the AWS SDK that was used internally in Bref.

If you were using this class in your application, you can use the AWS SDK directly, or the simpler and lighter Async AWS package (opens in a new tab).

Removed `Bref\Websocket\SimpleWebsocketClient`

The Bref\Websocket\SimpleWebsocketClient class has been extracted to a separate package: bref/api-gateway-websocket-client (opens in a new tab).

Changed the AWS account ID for AWS Lambda layers

The AWS account ID where Bref layers are published is different for v2. That lets us keep releasing Bref v1 layers without mixing up layer numbers (e.g. layer 24 being a v2 layer and layer 25 being a v1 layer).

For Bref v2 layers, you need to use 534081306603 as the AWS account number (instead of 209497400698).

# Bref v1 layer
arn:aws:lambda:eu-west-2:209497400698:layer:php-82-fpm:xxx
 
# Bref v2 layer
arn:aws:lambda:eu-west-2:534081306603:layer:php-82-fpm:xxx

Performance Serverless course