Skip to content

Commit 9b85d98

Browse files
mnapolimnapoli
authored
Merge pull request #2036 from brefphp/release-notes
v3 release notes
2 parents ee89bc3 + e4f32af commit 9b85d98

File tree

4 files changed

+441
-33
lines changed

4 files changed

+441
-33
lines changed

‎docs/upgrading/v3.mdx‎

Lines changed: 205 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,12 @@
22
introduction: Upgrading guide to go from Bref 2.x to Bref 3.0.
33
---
44

5+
import { Callout } from 'nextra/components';
6+
57
# Upgrading to Bref 3.0
68

9+
Read the [Bref 3.0 release announcement](/news/03-bref-3.0) to learn about all the new features and improvements.
10+
711
## Updating dependencies
812

913
### PHP 8.2 required
@@ -12,74 +16,144 @@ Bref 3.0 now requires PHP 8.2 or greater.
1216

1317
### Composer Dependencies
1418

15-
You should update the `bref/bref` dependency in your application's composer.json file:
19+
Update all Bref packages in your `composer.json` file from `^2` to `^3`, for example:
1620

17-
```diff
18-
- "bref/bref": "^2",
19-
+ "bref/bref": "^3",
21+
```json filename="composer.json"
22+
"require": {
23+
"bref/bref": "^3",
24+
"bref/laravel-bridge": "^3", // if you use Laravel
25+
"bref/symfony-bridge": "^3", // if you use Symfony
26+
"bref/extra-php-extensions": "^3" // if you use extra extensions
27+
}
2028
```
2129

22-
Then run `composer update bref/bref --with-all-dependencies`.
30+
<Callout>
31+
Only update the versions for the packages you actually have in your project.
32+
</Callout>
2333

24-
If you use the [Bref Extra extensions](https://github.com/brefphp/extra-php-extensions), you also need to update the `bref/extra-php-extensions` package to version `^3.0`.
34+
Then run:
2535

26-
## Container image changes
36+
```bash
37+
composer update --with-all-dependencies
38+
```
2739

28-
If you deploy using [container images](../deploy/docker.mdx), you must update your `Dockerfile`.
40+
## PHP extension changes
2941

30-
First, change the major version of the Bref base image:
42+
The following improvements in Bref 3.0 let you clean up old configurations.
3143

32-
```diff filename="Dockerfile"
33-
- FROM bref/php-84-fpm:2
34-
+ FROM bref/php-84-fpm:3
44+
### PostgreSQL extension is enabled by default
3545

36-
# ...
46+
The PostgreSQL PDO extension (`pdo_pgsql`) is now enabled by default in Bref layers.
47+
48+
If you had enabled it manually via a `php.ini` file, you can remove that line:
49+
50+
```diff filename="php/conf.d/php.ini"
51+
-extension=pdo_pgsql
3752
```
3853

39-
Since Bref container images have been merged into a single `bref/php-xx` image, the following images don't exist anymore: `bref/php-xx-fpm` and `bref/php-xx-console`.
54+
### Redis extension is now built-in
4055

41-
You must replace the base image to `bref/php-xx` when needed and define the `BREF_RUNTIME` environment variable:
56+
The Redis PHP extension is now included in Bref layers by default.
4257

43-
```diff filename="Dockerfile"
44-
FROM bref/php-84:3
58+
If you were using the Redis extension from [bref/extra-php-extensions](https://github.com/brefphp/extra-php-extensions), remove the layer from your `serverless.yml`:
59+
60+
```diff filename="serverless.yml"
61+
functions:
62+
api:
63+
# ...
64+
layers:
65+
- - ${bref-extra:redis-php-84}
66+
```
4567

46-
+ ENV BREF_RUNTIME=function
68+
And enable the extension via a `php.ini` file in your project (`php/conf.d/php.ini`):
4769

48-
# ...
70+
```diff filename="php/conf.d/php.ini"
71+
extension=redis
72+
```
73+
74+
If Redis was the only `bref/extra-php-extensions` extension you were using, you can uninstall the package:
75+
76+
```bash
77+
composer remove bref/extra-php-extensions
4978
```
5079

51-
or
80+
## Container image changes
81+
82+
If you deploy using [container images](../deploy/docker.mdx), you must update your `Dockerfile`.
83+
84+
**If you don't have a `Dockerfile` in your project, you can skip this section.**
85+
86+
Since Bref container images have been merged into a single `bref/php-xx` image, the following images don't exist anymore: `bref/php-xx-fpm` and `bref/php-xx-console`.
87+
88+
### Option 1: Set BREF_RUNTIME in the Dockerfile
89+
90+
The simplest upgrade path is to update your Dockerfile to use the unified image and set the runtime:
5291

5392
```diff filename="Dockerfile"
54-
- FROM bref/php-84-fpm:3
93+
- FROM bref/php-84-fpm:2
5594
+ FROM bref/php-84:3
56-
5795
+ ENV BREF_RUNTIME=fpm
5896

5997
# ...
6098
```
6199

62-
or
100+
Replace `fpm` with `function` or `console` depending on your use case.
63101

64-
```diff filename="Dockerfile"
65-
- FROM bref/php-84-console:3
66-
+ FROM bref/php-84:3
102+
### Option 2: Use one image for all function types (recommended)
67103

68-
+ ENV BREF_RUNTIME=console
104+
A major benefit of v3 is that you can now use **a single Docker image** for all your functions (web, console, queues, etc.) and set `BREF_RUNTIME` per function in `serverless.yml`.
69105

70-
# ...
106+
**Dockerfile** (single image for everything):
107+
108+
```dockerfile filename="Dockerfile"
109+
FROM bref/php-84:3
110+
111+
# Your application code
112+
COPY . /var/task
113+
114+
# No BREF_RUNTIME set here!
71115
```
72116

73-
Separately, if you use the `bref/php-84-fpm-dev` image for local development, you need to update its name and version:
117+
**serverless.yml** (set runtime per function):
74118

75-
```diff filename="Dockerfile"
119+
```yml filename="serverless.yml"
120+
functions:
121+
web:
122+
image:
123+
name: my-app-image
124+
environment:
125+
BREF_RUNTIME: fpm # Web/HTTP function
126+
events:
127+
- httpApi: '*'
128+
129+
console:
130+
image:
131+
name: my-app-image
132+
environment:
133+
BREF_RUNTIME: console # Console commands
134+
135+
worker:
136+
image:
137+
name: my-app-image
138+
environment:
139+
BREF_RUNTIME: function # Queue worker
140+
events:
141+
- sqs:
142+
arn: !GetAtt MyQueue.Arn
143+
```
144+
145+
This approach lets you build and deploy a single Docker image for all function types, simplifying your deployment pipeline.
146+
147+
### Local development images
148+
149+
If you use the `bref/php-84-fpm-dev` image for local development, update it to:
150+
151+
```diff filename="docker-compose.yml"
76152
- FROM bref/php-84-fpm-dev:2
77153
+ FROM bref/php-84-dev:3
78-
79-
# ...
80154
```
81155

82-
The rest works as usual.
156+
You can then set `BREF_RUNTIME` environment variable in your `docker-compose.yml` file or in the `Dockerfile` directly.
83157

84158
## Smaller breaking changes that might impact you
85159

@@ -214,3 +288,101 @@ Under the hood, **all layers have been merged into one**, i.e. `php-xx-fpm` and
214288

215289
The examples above assume you are using PHP 8.4 (`php-84`) but you can replace `84` with another PHP version.
216290

291+
### The `vendor/bin/bref` CLI has been removed
292+
293+
The `vendor/bin/bref` CLI has been completely removed in Bref 3.0. This is a minor change since the CLI was already 90% removed in Bref 2.0 - only the `bref init` command remained for bootstrapping new projects.
294+
295+
We now have better onboarding with improved documentation. Here are the alternatives:
296+
297+
- **Scaffolding new projects**: Follow the [getting started guide](/docs/setup) to create your `serverless.yml` manually.
298+
- **Layer versions**: Visit [runtimes.bref.sh](https://runtimes.bref.sh/) or run `serverless bref:layers`.
299+
- **Running console commands**: Use `serverless bref:cli` (unchanged from v2).
300+
- **Local development**: Use [Docker-based local development](/docs/local-development).
301+
302+
### The hooks system has been removed
303+
304+
The deprecated hooks system has been removed. This change affects very few users (less than 1%) as it was a low-level API used primarily by framework integrations.
305+
306+
If you were using `Bref::beforeStartup()` or `Bref::beforeInvoke()`, you must migrate to the `BrefEventSubscriber` pattern:
307+
308+
Before:
309+
310+
```php
311+
use Bref\Bref;
312+
313+
Bref::beforeStartup(function () {
314+
// Setup code
315+
});
316+
```
317+
318+
After:
319+
320+
```php
321+
use Bref\Bref;
322+
use Bref\Listener\BrefEventSubscriber;
323+
324+
class MyEventSubscriber extends BrefEventSubscriber
325+
{
326+
public function beforeStartup(): void
327+
{
328+
// Setup code
329+
}
330+
}
331+
332+
Bref::events()->subscribe(new MyEventSubscriber());
333+
```
334+
335+
The `BrefEventSubscriber` class provides additional hooks: `afterStartup()`, `beforeInvoke()`, and `afterInvoke()`. This refactor powers better integrations like the [Laravel bridge](https://github.com/brefphp/laravel-bridge), [X-Ray integration](https://bref.sh/xray), and [Sentry integration](https://bref.sh/sentry).
336+
337+
### SOAP extension is now disabled by default
338+
339+
The SOAP PHP extension is now disabled by default. It had very little usage, and disabling it helped reduce layer sizes to make room for more commonly used extensions.
340+
341+
If you need the SOAP extension, you can enable it by creating a `php.ini` file in your project:
342+
343+
```ini filename="php/conf.d/soap.ini"
344+
extension=soap
345+
```
346+
347+
And reference it in your `serverless.yml`:
348+
349+
```yml filename="serverless.yml"
350+
provider:
351+
environment:
352+
BREF_AUTOLOAD_PATH: php/conf.d
353+
```
354+
355+
### Laravel version compatibility
356+
357+
If you are using Laravel with Bref, note that:
358+
359+
- **Laravel 10, 11, or 12 is required** (Laravel 8 and 9 are no longer supported).
360+
- Update `bref/laravel-bridge` to the latest version.
361+
362+
The Laravel bridge has been updated to use the new `BrefEventSubscriber` pattern internally, but this change is transparent to users.
363+
364+
### CloudWatch log formatter enabled by default
365+
366+
The [Bref Monolog formatter](https://github.com/brefphp/monolog-bridge) is now enabled by default in the Laravel and Symfony bridges.
367+
368+
**This changes how your logs will look.** Logs now use a hybrid format that combines human-readable text with structured JSON:
369+
370+
Before (plain text):
371+
```
372+
[2025-12-05 10:30:45] production.ERROR: Database connection failed
373+
```
374+
375+
After (structured format):
376+
```
377+
ERROR Database connection failed {"message":"Database connection failed","level":"ERROR","context":{...}}
378+
```
379+
380+
This format makes logs easier to read in CloudWatch and enables powerful filtering with CloudWatch Logs Insights (e.g., filter by log level or exception class).
381+
382+
**Exception handling is greatly improved:** Previously, exception stack traces were split across multiple CloudWatch log records (one per line), making them difficult to read and browse. Now, the entire exception (including stack trace) is grouped in a single JSON object, making debugging much easier.
383+
384+
If you prefer the old format, you can disable the formatter in your Laravel or Symfony configuration. See the [Bref Monolog documentation](https://github.com/brefphp/monolog-bridge) for details.
385+
386+
---
387+
388+
That's it! Read the [Bref 3.0 release announcement](/news/03-bref-3.0) to learn more about all the new features and improvements in this release.

‎website/src/pages/news.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,14 @@ import { NextSeo } from 'next-seo';
99
<script async src="https://platform.twitter.com/widgets.js"></script>
1010
</div>
1111

12+
## [Bref 3.0 is released 🎉](./news/03-bref-3.0.mdx)
13+
14+
Bref 3.0 is here! Since Bref 2.0, we've grown from 10 billion to **40 billion Lambda executions** every month. The package has been installed more than **8 million times**, and we've crossed **4,000 commits** across all Bref repositories.
15+
16+
Today, we celebrate these achievements and **the release of Bref 3.0** 🎉
17+
18+
[▶ Read more](./news/03-bref-3.0.mdx)
19+
1220
## [Bref 2.0 is released 🎉](./news/02-bref-2.0.md)
1321

1422
The work on what would be Bref 2.0 started in October 2021, about 1.5 year ago. We went through many different strategies, experiments, rewrites, over **700 commits** to finally land with the stable release.

0 commit comments

Comments
 (0)