Switch to a single layer

docs/deploy/docker.mdx

@@ -29,11 +29,14 @@ You should consider deploying using Docker when:
 Bref helps you deploy using Docker images by offering base images that work on AWS Lambda. Here is an example of a Dockerfile you can use:
 
 ```dockerfile filename="Dockerfile"
-FROM bref/php-84-fpm:2
+FROM bref/php-84:3
 
 # Copy the source code in the image
 COPY . /var/task
 
+# In this example we're serving an HTTP application with php-fpm
+ENV BREF_RUNTIME=fpm
+
 # Configure the handler file (the entrypoint that receives all HTTP requests)
 CMD ["public/index.php"]
 ```
@@ -43,14 +46,14 @@ The `CMD` instruction let us specify the entrypoint that will handle all request
 <Callout>
     Always specify the major version of the Bref image you want to use. That avoids breaking changes when a new major version is released.
 
-    For example `bref/php-84-fpm:3` points to Bref v3.
+    For example `bref/php-84:3` points to Bref v3.
 </Callout>
 
-Bref offers the following base images:
+The `ENV BREF_RUNTIME=fpm` let's us specify which [runtime](../runtimes.mdx) to use. As a reminder, Bref offers the following runtimes:
 
-- `bref/php-xx-fpm:3`: PHP-FPM to run HTTP applications
-- `bref/php-xx-console:3`: to run PHP CLI commands
-- `bref/php-xx:3`: to run [PHP functions](../runtimes/function.mdx)
+- `fpm`: [uses PHP-FPM to serve web applications](../runtimes/fpm-runtime.mdx)
+- `function`: [to run PHP code](../runtimes/function.mdx)
+- `console`: [to run CLI commands](../runtimes/console.mdx)
 
 <Callout type="warning">
     The `CMD` instruction in `Dockerfile` must contain a valid JSON array. This is why you must escape any `\` character. This is important for PHP class names, for example when using Laravel Octane:
@@ -65,20 +68,20 @@ Bref offers the following base images:
 You can enable additional PHP extensions by pulling them from [Bref Extra Extensions](https://github.com/brefphp/extra-php-extensions):
 
 ```dockerfile filename="Dockerfile" {3-4}
-FROM bref/php-84-fpm:2
+FROM bref/php-84:3
 
-COPY --from=bref/extra-redis-php-84:1 /opt /opt
-COPY --from=bref/extra-gmp-php-84:1 /opt /opt
+COPY --from=bref/extra-redis-php-84:3 /opt /opt
+COPY --from=bref/extra-gmp-php-84:3 /opt /opt
 
 COPY . /var/task
 
 CMD ["public/index.php"]
 ```
 
 <Callout>
-    Like the Bref images, always specify the major version of the Bref Extra Extensions images: `bref/extra-*:1` points to Bref Extra Extensions v1.
+    Like the Bref images, always specify the major version of the Bref Extra Extensions images: `bref/extra-*:3` points to Bref Extra Extensions v3.
 
-    Note that Bref v2 is compatible with Bref Extra Extensions v1 (yes that's confusing, sorry about that, we will fix that in Bref v3 to have matching versions).
+    Note that Bref v3 is compatible with Bref Extra Extensions v3.
 </Callout>
 
 ## Deployment
@@ -126,6 +129,6 @@ The `/tmp` folder will always be empty on cold starts. Avoid writing content to
 
 ## Docker Registry
 
-AWS Lambda only support AWS ECR as the source location for Docker images.
+AWS Lambda only supports AWS ECR as the source location for Docker images.
 
 AWS Lambda will use the image digest as the unique identifier. This means that even if you overwrite the exact same tag on ECR, your lambda will still run the previous image code until you actually redeploy using the new image.

docs/local-development.mdx

@@ -42,7 +42,7 @@ version: "3.5"
 
 services:
     app:
-        image: bref/php-84-fpm-dev:3
+        image: bref/php-84-dev:3
         ports: [ '8000:8000' ]
         volumes:
             - .:/var/task
@@ -62,7 +62,7 @@ The application will be available at [http://localhost:8000/](http://localhost:8
 
 The `HANDLER` environment variable lets you define which PHP file will be handling all HTTP requests. This should be the same handler that you have defined in `serverless.yml` for your HTTP function.
 
-> Currently, the Docker image support only one PHP handler. If you have multiple HTTP functions in `serverless.yml`, you can duplicate the service in `docker-compose.yml` to have one container per lambda function.
+> Currently, the Docker image supports only one PHP handler. If you have multiple HTTP functions in `serverless.yml`, you can duplicate the service in `docker-compose.yml` to have one container per lambda function.
 
 ### Read-only filesystem
 

docs/local-development/event-driven-functions.mdx

@@ -88,8 +88,8 @@ If you want to run your function in Docker:
 ```bash
 $ 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 and Blackfire in the image):
-$ docker run --rm -it -v $(PWD):/var/task:ro bref/php-84-fpm-dev: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](../local-development.mdx):
@@ -98,7 +98,7 @@ You can also use Docker Compose, like described in [Local development for HTTP a
 version: "3.5"
 services:
     app:
-        image: bref/php-84-fpm-dev:3
+        image: bref/php-84-dev:3
         volumes:
             - .:/var/task
 ```

docs/upgrading/v3.mdx

@@ -23,20 +23,194 @@ Then run `composer update bref/bref --with-all-dependencies`.
 
 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`.
 
+## Container image changes
+
+If you deploy using [container images](../deploy/docker.mdx), you must update your `Dockerfile`.
+
+First, change the major version of the Bref base image:
+
+```diff filename="Dockerfile"
+- FROM bref/php-84-fpm:2
++ FROM bref/php-84-fpm:3
+
+# ...
+```
+
+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`.
+
+You must replace the base image to `bref/php-xx` when needed and define the `BREF_RUNTIME` environment variable:
+
+```diff filename="Dockerfile"
+FROM bref/php-84:3
+
++ ENV BREF_RUNTIME=function
+
+# ...
+```
+
+or
+
+```diff filename="Dockerfile"
+- FROM bref/php-84-fpm:3
++ FROM bref/php-84:3
+
++ ENV BREF_RUNTIME=fpm
+
+# ...
+```
+
+or
+
+```diff filename="Dockerfile"
+- FROM bref/php-84-console:3
++ FROM bref/php-84:3
+
++ ENV BREF_RUNTIME=console
+
+# ...
+```
+
+Separately, if you use the `bref/php-84-fpm-dev` image for local development, you need to update its name and version:
+
+```diff filename="Dockerfile"
+- FROM bref/php-84-fpm-dev:2
++ FROM bref/php-84-dev:3
+
+# ...
+```
+
+The rest works as usual.
+
 ## 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.
 
 ### Changed the AWS account ID for AWS Lambda layers
 
-The AWS account ID where Bref layers are published is different for v3. That lets us keep releasing Bref v2 layers without mixing up layer numbers.
-
-For Bref v3 layers, you need to use `873528684822` as the AWS account number (instead of `534081306603`).
+The AWS account ID where Bref layers are published is different for v3. That lets us keep releasing Bref v2 layers without mixing up layer numbers. If you reference the layers via their full ARN, you must update the Bref AWS account number to `873528684822` (instead of `534081306603`).
 
 ```bash
 # Bref v2 layer
-arn:aws:lambda:eu-west-2:534081306603:layer:php-84:xxx
+arn:aws:lambda:us-east-1:534081306603:layer:php-84:xxx
 
 # Bref v3 layer
-arn:aws:lambda:eu-west-2:873528684822:layer:php-84:xxx
+arn:aws:lambda:us-east-1:873528684822:layer:php-84:xxx
 ```
+
+**If you don't know what that means**, you're likely not concerned by this change.
+
+If you're not sure, search for `534081306603` in your codebase and replace it with the new account ID.
+
+### AWS Lambda layers have been merged into a single layer
+
+If you configure the `runtime` in your functions using the following syntax:
+
+```yml filename="serverless.yml"
+functions:
+    web:
+        # ...
+        runtime: php-84-fpm # or `php-xx` or `php-xx-console`
+```
+
+✅ **you have nothing to do**, your configuration is valid for Bref v3.
+
+However, if you specify AWS Lambda layers explicitly in `serverless.yml` (or through any other deployment method), for example:
+
+```yml filename="serverless.yml"
+functions:
+    web:
+        # ...
+        runtime: provided.al2
+        layers:
+            - ${bref:layer.php-84}
+            # or:
+            - ${bref:layer.php-84-fpm}
+        # or:
+        layers:
+            - 'arn:aws:lambda:us-east-1:534081306603:layer:php-84:21'
+```
+
+Then you must update your configuration.
+
+Under the hood, **all layers have been merged into one**, i.e. `php-xx-fpm` and `php-xx-console` have been merged into `php-xx` to make Bref layers simpler. The runtime is now defined via an environment variable that is automatically injected by Bref when using the `runtime:` syntax.
+
+- **Option 1**: switch to using the simpler `runtime:` syntax.
+
+    Before:
+
+    ```yml filename="serverless.yml"
+    functions:
+        web:
+            # ...
+            runtime: provided.al2
+            layers:
+                - ${bref:layer.php-84}
+                # or:
+                - ${bref:layer.php-84-fpm}
+                # or:
+                - ${bref:layer.php-84-console}
+    ```
+
+    After:
+
+    ```yml filename="serverless.yml"
+    functions:
+        web:
+            # ...
+            runtime: php-84
+            # or:
+            runtime: php-84-fpm
+            # or:
+            runtime: php-84-console
+    ```
+
+    The examples above assume you are using PHP 8.4 (`php-84`) but you can replace `84` with another PHP version.
+
+    If you include additional layers, you can keep them without issues, for example:
+
+    ```yml filename="serverless.yml"
+    functions:
+        web:
+            # ...
+            runtime: php-84-fpm
+            layers:
+                - ${bref-extra:imagick-php-84}
+    ```
+
+- **Option 2**: change the layer names and define the `BREF_RUNTIME` environment variable.
+
+    Before:
+
+    ```yml filename="serverless.yml"
+    functions:
+        web:
+            # ...
+            runtime: provided.al2
+            layers:
+                - ${bref:layer.php-84}
+                # or:
+                - ${bref:layer.php-84-fpm}
+                # or:
+                - ${bref:layer.php-84-console}
+    ```
+
+    After:
+
+    ```yml filename="serverless.yml"
+    functions:
+        web:
+            # ...
+            runtime: provided.al2
+            layers:
+                - ${bref:layer.php-84}
+            environment:
+                # ...
+                BREF_RUNTIME: function # for ${bref:layer.php-xx}
+                # or
+                BREF_RUNTIME: fpm # for ${bref:layer.php-xx-fpm}
+                # or
+                BREF_RUNTIME: console # ${bref:layer.php-xx-console}
+    ```
+
+    The examples above assume you are using PHP 8.4 (`php-84`) but you can replace `84` with another PHP version.
+