diff --git a/docs/upgrading/v3.mdx b/docs/upgrading/v3.mdx index cbbf83344..1ad1998b3 100644 --- a/docs/upgrading/v3.mdx +++ b/docs/upgrading/v3.mdx @@ -2,8 +2,12 @@ introduction: Upgrading guide to go from Bref 2.x to Bref 3.0. --- +import { Callout } from 'nextra/components'; + # Upgrading to Bref 3.0 +Read the [Bref 3.0 release announcement](/news/03-bref-3.0) to learn about all the new features and improvements. + ## Updating dependencies ### PHP 8.2 required @@ -12,74 +16,144 @@ Bref 3.0 now requires PHP 8.2 or greater. ### Composer Dependencies -You should update the `bref/bref` dependency in your application's composer.json file: +Update all Bref packages in your `composer.json` file from `^2` to `^3`, for example: -```diff -- "bref/bref": "^2", -+ "bref/bref": "^3", +```json filename="composer.json" +"require": { + "bref/bref": "^3", + "bref/laravel-bridge": "^3", // if you use Laravel + "bref/symfony-bridge": "^3", // if you use Symfony + "bref/extra-php-extensions": "^3" // if you use extra extensions +} ``` -Then run `composer update bref/bref --with-all-dependencies`. + + Only update the versions for the packages you actually have in your project. + -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`. +Then run: -## Container image changes +```bash +composer update --with-all-dependencies +``` -If you deploy using [container images](../deploy/docker.mdx), you must update your `Dockerfile`. +## PHP extension changes -First, change the major version of the Bref base image: +The following improvements in Bref 3.0 let you clean up old configurations. -```diff filename="Dockerfile" -- FROM bref/php-84-fpm:2 -+ FROM bref/php-84-fpm:3 +### PostgreSQL extension is enabled by default -# ... +The PostgreSQL PDO extension (`pdo_pgsql`) is now enabled by default in Bref layers. + +If you had enabled it manually via a `php.ini` file, you can remove that line: + +```diff filename="php/conf.d/php.ini" +-extension=pdo_pgsql ``` -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`. +### Redis extension is now built-in -You must replace the base image to `bref/php-xx` when needed and define the `BREF_RUNTIME` environment variable: +The Redis PHP extension is now included in Bref layers by default. -```diff filename="Dockerfile" -FROM bref/php-84:3 +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`: + +```diff filename="serverless.yml" +functions: + api: + # ... + layers: +- - ${bref-extra:redis-php-84} +``` -+ ENV BREF_RUNTIME=function +And enable the extension via a `php.ini` file in your project (`php/conf.d/php.ini`): -# ... +```diff filename="php/conf.d/php.ini" +extension=redis +``` + +If Redis was the only `bref/extra-php-extensions` extension you were using, you can uninstall the package: + +```bash +composer remove bref/extra-php-extensions ``` -or +## Container image changes + +If you deploy using [container images](../deploy/docker.mdx), you must update your `Dockerfile`. + +**If you don't have a `Dockerfile` in your project, you can skip this section.** + +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`. + +### Option 1: Set BREF_RUNTIME in the Dockerfile + +The simplest upgrade path is to update your Dockerfile to use the unified image and set the runtime: ```diff filename="Dockerfile" -- FROM bref/php-84-fpm:3 +- FROM bref/php-84-fpm:2 + FROM bref/php-84:3 - + ENV BREF_RUNTIME=fpm # ... ``` -or +Replace `fpm` with `function` or `console` depending on your use case. -```diff filename="Dockerfile" -- FROM bref/php-84-console:3 -+ FROM bref/php-84:3 +### Option 2: Use one image for all function types (recommended) -+ ENV BREF_RUNTIME=console +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`. -# ... +**Dockerfile** (single image for everything): + +```dockerfile filename="Dockerfile" +FROM bref/php-84:3 + +# Your application code +COPY . /var/task + +# No BREF_RUNTIME set here! ``` -Separately, if you use the `bref/php-84-fpm-dev` image for local development, you need to update its name and version: +**serverless.yml** (set runtime per function): -```diff filename="Dockerfile" +```yml filename="serverless.yml" +functions: + web: + image: + name: my-app-image + environment: + BREF_RUNTIME: fpm # Web/HTTP function + events: + - httpApi: '*' + + console: + image: + name: my-app-image + environment: + BREF_RUNTIME: console # Console commands + + worker: + image: + name: my-app-image + environment: + BREF_RUNTIME: function # Queue worker + events: + - sqs: + arn: !GetAtt MyQueue.Arn +``` + +This approach lets you build and deploy a single Docker image for all function types, simplifying your deployment pipeline. + +### Local development images + +If you use the `bref/php-84-fpm-dev` image for local development, update it to: + +```diff filename="docker-compose.yml" - FROM bref/php-84-fpm-dev:2 + FROM bref/php-84-dev:3 - -# ... ``` -The rest works as usual. +You can then set `BREF_RUNTIME` environment variable in your `docker-compose.yml` file or in the `Dockerfile` directly. ## Smaller breaking changes that might impact you @@ -214,3 +288,101 @@ Under the hood, **all layers have been merged into one**, i.e. `php-xx-fpm` and The examples above assume you are using PHP 8.4 (`php-84`) but you can replace `84` with another PHP version. +### The `vendor/bin/bref` CLI has been removed + +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. + +We now have better onboarding with improved documentation. Here are the alternatives: + +- **Scaffolding new projects**: Follow the [getting started guide](/docs/setup) to create your `serverless.yml` manually. +- **Layer versions**: Visit [runtimes.bref.sh](https://runtimes.bref.sh/) or run `serverless bref:layers`. +- **Running console commands**: Use `serverless bref:cli` (unchanged from v2). +- **Local development**: Use [Docker-based local development](/docs/local-development). + +### The hooks system has been removed + +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. + +If you were using `Bref::beforeStartup()` or `Bref::beforeInvoke()`, you must migrate to the `BrefEventSubscriber` pattern: + +Before: + +```php +use Bref\Bref; + +Bref::beforeStartup(function () { + // Setup code +}); +``` + +After: + +```php +use Bref\Bref; +use Bref\Listener\BrefEventSubscriber; + +class MyEventSubscriber extends BrefEventSubscriber +{ + public function beforeStartup(): void + { + // Setup code + } +} + +Bref::events()->subscribe(new MyEventSubscriber()); +``` + +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). + +### SOAP extension is now disabled by default + +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. + +If you need the SOAP extension, you can enable it by creating a `php.ini` file in your project: + +```ini filename="php/conf.d/soap.ini" +extension=soap +``` + +And reference it in your `serverless.yml`: + +```yml filename="serverless.yml" +provider: + environment: + BREF_AUTOLOAD_PATH: php/conf.d +``` + +### Laravel version compatibility + +If you are using Laravel with Bref, note that: + +- **Laravel 10, 11, or 12 is required** (Laravel 8 and 9 are no longer supported). +- Update `bref/laravel-bridge` to the latest version. + +The Laravel bridge has been updated to use the new `BrefEventSubscriber` pattern internally, but this change is transparent to users. + +### CloudWatch log formatter enabled by default + +The [Bref Monolog formatter](https://github.com/brefphp/monolog-bridge) is now enabled by default in the Laravel and Symfony bridges. + +**This changes how your logs will look.** Logs now use a hybrid format that combines human-readable text with structured JSON: + +Before (plain text): +``` +[2025-12-05 10:30:45] production.ERROR: Database connection failed +``` + +After (structured format): +``` +ERROR Database connection failed {"message":"Database connection failed","level":"ERROR","context":{...}} +``` + +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). + +**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. + +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. + +--- + +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. diff --git a/website/src/pages/news.mdx b/website/src/pages/news.mdx index 471b4ecb0..a0ca257c5 100644 --- a/website/src/pages/news.mdx +++ b/website/src/pages/news.mdx @@ -9,6 +9,14 @@ import { NextSeo } from 'next-seo'; +## [Bref 3.0 is released 🎉](./news/03-bref-3.0.mdx) + +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. + +Today, we celebrate these achievements and **the release of Bref 3.0** 🎉 + +[▶ Read more](./news/03-bref-3.0.mdx) + ## [Bref 2.0 is released 🎉](./news/02-bref-2.0.md) 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. diff --git a/website/src/pages/news/03-bref-3.0.mdx b/website/src/pages/news/03-bref-3.0.mdx new file mode 100644 index 000000000..c0f127a6b --- /dev/null +++ b/website/src/pages/news/03-bref-3.0.mdx @@ -0,0 +1,228 @@ +import ArticleHeader from '../../components/news/ArticleHeader'; +import { NextSeo } from 'next-seo'; +import Image from 'next/image'; +import cloudScreenshot from './03/cloud-screenshot.png'; + + + +# Bref 3.0 is released 🎉 + + + +Bref 3.0 is here! Since Bref 2.0, we've grown from 10 billion to **40 billion Lambda executions** (aka requests) every month. The package has been installed more than **8 million times**, and we've crossed **4,000 commits** across all Bref repositories. + +Today, we celebrate these achievements and **the release of Bref 3.0** 🎉 + +Let's check out what's new in v3. + +## Bref 3.0 + +Here's a summary, we'll dive into the details below: + +- **24% smaller layers** for faster cold starts. +- **Runtimes rebuilt on Amazon Linux 2023**: upgrade from deprecated Amazon Linux 2. +- **PHP 8.5 support** +- **PostgreSQL extension** is now enabled by default. +- **Redis extension** is now built-in. +- **Unified PHP runtime**: one layer and one container image instead of three. +- **New regions**: `ap-southeast-3` and `me-central-1`. +- **Better CloudWatch logs** with the new Monolog formatter enabled by default. +- **[Bref Cloud](https://bref.sh/cloud)**: a simpler way to deploy Bref applications. + +What did we break? **Almost nothing**, the upgrade should be smooth. Here are the details: + +- PHP 8.2+ is now required (PHP 8.0 and 8.1 support is dropped). +- The `vendor/bin/bref` CLI is removed (it was already 90% removed in v2). +- The SOAP extension is now opt-in (it had very little usage). +- If you deploy using container images, you'll need to update your Dockerfile. + +For a complete list of changes and instructions, check out the [**v3 upgrade guide**](../docs/upgrading/v3.mdx). + +## Faster Lambda cold starts + +The Bref layers for AWS Lambda have been optimized and their size reduced. It leaves more room for your code and should improve cold start times. + +- PHP 8.4: 69MB → 53MB +- PHP 8.3: 65MB → 46MB + +This was achieved through several optimizations: + +- Stripping debug symbols from all libraries and PHP extensions. +- Compiling PHP with size-optimization flags. +- Disabling the rarely-used SOAP extension by default. +- Bundling some PHP extensions directly into the PHP binary. + +## Amazon Linux 2023 + +Bref 3.0 is built on **[Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/ug/what-is-amazon-linux.html)** (AL2023), the latest version of Amazon's Linux distribution for AWS. + +The previous Bref versions were built on **Amazon Linux 2** (AL2), which has been deprecated by AWS. AWS Lambda will continue to support AL2 for some time, but it's recommended to migrate to AL2023 as soon as possible. + +This upgrade brings several benefits: + +- **Performance**: AL2023 is leaner than AL2, with more recent kernel and system libraries. +- **Modern packages**: AL2023 ships with more recent package versions, simplifying the Bref build process. +- **Long-term support**: AL2 will be deprecated in June 2026, while AL2023 will be supported at least until 2029. + +The migration happens automatically when you upgrade to Bref 3.0, no changes are needed on your end. + +## PHP 8.5 support + +Bref 3.0 adds support for **PHP 8.5** (which depended on an AL2023 system upgrade). You can start using it by setting the runtime in your `serverless.yml`: + +```yaml +functions: + api: + handler: public/index.php + runtime: php-85-fpm +``` + +## Redis extension built-in + +The **Redis extension** is now included in Bref layers by default. Redis is one of the most used extensions by Bref users for caching and session storage. + +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`: + +```diff filename="serverless.yml" +functions: + api: + # ... + layers: +- - ${bref-extra:redis-php-84} +``` + +And enable the extension via a `php.ini` file in your project (`php/conf.d/php.ini`): + +```diff filename="php/conf.d/php.ini" +extension=redis +``` + +If Redis was the only `bref/extra-php-extensions` extension you were using, you can uninstall the package: + +```bash +composer remove bref/extra-php-extensions +``` + +## PostgreSQL enabled by default + +The **PostgreSQL PDO extension** is now enabled by default. If you're using PostgreSQL, you no longer need any additional configuration. + +If you had enabled it manually via a `php.ini` file, you can remove that line: + +```diff filename="php/conf.d/php.ini" +-extension=pdo_pgsql +``` + +## Unified PHP runtime + +Bref 3.0 consolidates the three separate layer types (function, FPM, console) into a **single unified layer** per PHP version. This simplification makes maintenance easier and provides a simpler mental model for users. + +**Do you need to change anything?** + +- **If you use `runtime: php-84-fpm` in your `serverless.yml`**: nothing changes, you're all set! +- **If you deploy using container images**: you need to update your `Dockerfile`, ⚠️ read the [upgrade guide](../docs/upgrading/v3.mdx#updating-your-dockerfile-for-bref-30). +- **If you specify layers explicitly**: ⚠️ read the [upgrade guide](../docs/upgrading/v3.mdx#aws-lambda-layers-have-been-merged-into-a-single-layer). + +A single layer/image is how it should have been from the start, and I'm really glad we're getting there now! + +## Better CloudWatch logs + +The [Bref Monolog formatter](https://github.com/brefphp/monolog-bridge) is now **enabled by default** in the Laravel and Symfony bridges. This formatter outputs logs in a format optimized for CloudWatch, making them easier to read and filter. + +Before (plain text): +``` +[2025-12-05 10:30:45] production.ERROR: Database connection failed +``` + +After (structured format): +```json +ERROR Database connection failed {"message":"Database connection failed","level":"ERROR","context":{...}} +``` + +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). + +**Exception handling is also 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. + +That new logging approach also allows reading all the logs of a single request, by filtering via the AWS request ID. + +## New regions + +Bref layers are now available in two additional regions: + +- `ap-southeast-3` (Asia Pacific - Jakarta) +- `me-central-1` (Middle East - UAE) + +## The `vendor/bin/bref` CLI is removed + +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. + +We now have better onboarding with improved documentation and the `serverless` CLI commands. Here are the alternatives: + +- **Scaffolding new projects**: Follow the [getting started guide](https://bref.sh/docs/setup) to create your `serverless.yml` manually. +- **Layer versions**: Visit [runtimes.bref.sh](https://runtimes.bref.sh/) or run `serverless bref:layers`. +- **Running console commands**: Use `serverless bref:cli` (this existed in v2). +- **Local development**: Use [Docker-based local development](https://bref.sh/docs/local-development). + +## Upgrading + +Check out the [**v3 Upgrade Guide**](../docs/upgrading/v3.mdx) for a complete list of changes and instructions to upgrade your projects. + +## Thanks + +A huge thanks to the [Bref contributors](https://github.com/brefphp/bref/graphs/contributors), to the community for supporting the project, and to the open-source sponsors: + +**Premium sponsors:** + +- [Craft CMS](https://craftcms.com/?ref=bref.sh) +- [Voxie](https://voxie.com/?ref=bref) +- [MyBuilder](https://www.mybuilder.com/?ref=bref.sh) + +**Gold sponsors:** + +- [Depot](https://depot.dev/?ref=bref.sh) +- [SecuMailer](https://secumailer.com/?ref=bref.sh) +- [Ecomail](https://ecomail.cz/?ref=bref.sh) +- [Spreaker](https://www.spreaker.com/?ref=bref) +- [Runs On](https://runs-on.com/?ref=bref) +- [Playable](https://playable.com/?ref=bref) + +And [many other personal sponsors](https://github.com/sponsors/mnapoli#sponsors)! + +Thank you all! + +## One more thing + +Check out **[Bref Cloud](https://bref.sh/cloud)** for a simpler way to deploy and monitor your Bref applications! + + + + + + +## That's it! + +Hope you enjoy Bref v3! + +There is a complete [**v3 Upgrade Guide**](../docs/upgrading/v3.mdx) that you can follow. + +Head to the docs to [**get started with Bref**](../), or check out the documentation for [Laravel](../docs/laravel/getting-started.mdx) or [Symfony](../docs/symfony/getting-started.mdx). + +You can also join the community [in Slack](/docs/community.md), post details about your project in [Built with Bref](https://github.com/brefphp/bref/issues/267), or share your experience online and mention [@brefphp](https://twitter.com/brefphp) on Twitter. + +
+ What is Bref and serverless? + Get started with Bref +
diff --git a/website/src/pages/news/03/cloud-screenshot.png b/website/src/pages/news/03/cloud-screenshot.png new file mode 100644 index 000000000..1459766cd Binary files /dev/null and b/website/src/pages/news/03/cloud-screenshot.png differ