You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/index.mdx
+89-32Lines changed: 89 additions & 32 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@ Serverless means using cloud services that manage the servers for us.
10
10
11
11
When running PHP on a server, we must:
12
12
13
-
-setup, configure and maintain that server,
13
+
-set up, configure, and maintain that server,
14
14
- pay a fixed price for the server,
15
15
- scale the server(s) if we get more traffic.
16
16
@@ -20,48 +20,40 @@ When running PHP serverless:
20
20
- We pay only for what we use (per request).
21
21
- Our application scales automatically.
22
22
23
-
**Serverless provides more scalable, affordable and reliable architectures for less effort.**
23
+
**Serverless provides more scalable, affordable, and reliable architectures with less effort.**
24
24
25
25
Serverless includes services like storage as a service, database as a service, message queue as a service, etc. One service in particular is interesting for us developers: *Function as a Service* (FaaS).
26
26
27
-
FaaS is a way to run code where the hosting provider takes care of setting up everything, keeping the application available 24/7, scaling it up and down and we are only charged *while the code is actually executing*.
27
+
FaaS is a way to run code where the hosting provider takes care of setting up everything, keeping the application available 24/7, scaling it up and down, and we are only charged *while the code is actually executing*.
28
28
29
29
## Why Bref?
30
30
31
31
Bref aims to make running PHP applications simple.
32
32
33
-
To reach that goal, Bref takes advantage of serverless technologies. However, while serverless is promising, there are many choices to make, tools to build and best practices to figure out.
33
+
To reach that goal, Bref takes advantage of serverless technologies. However, while serverless is promising, there are many choices to make, tools to build, and best practices to figure out.
34
34
35
-
Bref's approach is to:
36
-
37
-
-**simplify problems by removing choices**
38
-
39
-
*instead of trying to address every need*
40
-
-**provide simple and familiar solutions**
41
-
42
-
*instead of aiming for powerful custom solutions*
43
-
-**empower by sharing knowledge**
44
-
45
-
*instead of hiding too much behind leaky abstractions*
35
+
Bref provides extensive documentation and an entire toolkit to make serverless approachable and easy to use.
46
36
47
37
### What is Bref
48
38
49
-
Bref (which means "brief" in french) comes as an open source Composer package and helps you deploy PHP applications to [AWS](https://aws.amazon.com) and run them on [AWS Lambda](https://aws.amazon.com/lambda/).
39
+
Bref (which means "brief" in French) comes as an open source Composer package and helps you deploy PHP applications to [AWS](https://aws.amazon.com) and run them on [AWS Lambda](https://aws.amazon.com/lambda/). It also makes it easy to use other AWS services (like S3, RDS, SQS…) for file storage, databases, etc.
50
40
51
41
Bref provides:
52
42
53
43
- documentation
54
44
- PHP runtimes for AWS Lambda
55
45
- deployment tooling
56
-
- PHP frameworks integration
46
+
- integrations for Laravel and Symfony
47
+
48
+
The choice of AWS is deliberate: at the moment, AWS is the leading hosting provider, it is ahead in the serverless space in terms of features, performance, and reliability. AWS combines the advantages of being an extremely safe choice for hosting while providing the most advanced serverless solution.
57
49
58
-
The choice of AWS as serverless provider is deliberate: at the moment AWS is the leading hosting provider, it is ahead in the serverless space in terms of features, performance and reliability.
50
+
Bref configures and deploys applications to AWS using [the `serverless` CLI](https://github.com/oss-serverless/serverless). Being the most popular tool, `serverless` comes with a huge community, a lot of examples online, and a simple configuration format.
59
51
60
-
Bref uses [the Serverless framework](https://serverless.com/)to configure and deploy serverless applications. Being the most popular tool, Serverless comes with a huge community, a lot of examples online and a simple configuration format.
52
+
If you want to learn [how AWS Lambda and Bref work, read more here](/docs/how-it-works).
61
53
62
54
## Use cases
63
55
64
-
Bref and AWS Lambda can be used to run many kind of PHP application, for example:
56
+
Bref and AWS Lambda can be used to run many kinds of PHP applications, for example:
65
57
66
58
- APIs
67
59
- websites
@@ -71,7 +63,48 @@ Bref and AWS Lambda can be used to run many kind of PHP application, for example
71
63
72
64
Bref aims to support any PHP framework. It comes with deep integrations with Laravel and Symfony.
73
65
74
-
If you are interested in real-world examples as well as cost analyses head over to the [**Case Studies** page](/docs/case-studies.md).
66
+
If you are interested in real-world examples as well as cost analyses, head over to the [**Case Studies** page](/docs/case-studies.md).
67
+
68
+
## Adapting to serverless
69
+
70
+
> Do PHP applications need to be adapted to run serverless?
71
+
72
+
In general no, but it depends on where you're coming from.
73
+
74
+
Running PHP applications serverless comes with roughly the same constraints as running an application in auto-scaled containers.
75
+
76
+
- The application code is mounted as read-only on disk.
77
+
- Since the application scales horizontally to run in multiple "instances" (like containers), all these instances have independent and ephemeral filesystems.
78
+
- Logs must not be written to disk, instead they must be sent to a centralized system (on AWS Lambda, logs written to `stderr` are automatically centralized in AWS CloudWatch, so this is usually a one-line config change).
79
+
- Sessions must not be written to disk, instead they must be stored in a centralized system (e.g. the database or Redis).
80
+
- Database and cache services (e.g. MySQL and Redis) must not run on the same server/container as PHP; instead, they must run in separate servers or containers (e.g. run databases in AWS RDS, Redis in AWS ElastiCache…).
81
+
- Uploaded files and generated files (e.g. CSV exports, PDF files…) must be stored in a centralized system (e.g. AWS S3).
82
+
- You can use the filesystem as a cache, but each instance of the application will then have a separate cache since the filesystem is not shared.
83
+
84
+
If these sound familiar to you, good news: your application is ready for serverless.
85
+
86
+
If your application is currently not set up like this, good news: preparing for serverless means you are actually preparing for a horizontally scalable application. These points are not "serverless-specific".
87
+
88
+
### Serverless-specific constraints
89
+
90
+
There are still a few serverless-specific constraints to be aware of:
91
+
92
+
- About 0.3% of all requests in production are ["cold starts"](/docs/environment/performances.mdx#cold-starts), i.e. slower requests (AWS Lambda scaling up) that can add 200 ms to 500 ms (or even more on very large applications) to the HTTP response time.
93
+
94
+
If your application cannot tolerate that occasional latency at the p99 metric, then serverless might not be the best fit.
95
+
- AWS Lambda has a limit of ~4 MB for HTTP requests/uploaded files.
96
+
97
+
If your application needs to support uploading larger files, a better option is to update your JavaScript frontend to upload files directly to AWS S3 via S3 pre-signed URLs (Laravel has helpers to generate these URLs for example).
98
+
99
+
- We do not run long-running processes on AWS Lambda, like queue workers or websocket servers.
100
+
101
+
For queue workers, this is actually great: SQS and Lambda integrate natively so that we don't have to run workers (or even think about them). Bref does the rest of the job to integrate natively with Laravel Queues or Symfony Messenger. More on this in the rest of the Bref documentation.
102
+
103
+
For websocket servers, this means we cannot run servers like Ratchet or Laravel Reverb on Lambda. It is possible to run this on the side in an AWS EC2 server, or in a container in ECS, but this is extra setup. An alternative is to use the native API Gateway WebSocket feature; however, this is not well documented in Bref at the moment.
104
+
105
+
- AWS Lambda has a maximum execution time limit of 15 minutes *per invocation*.
106
+
107
+
Note that this limit applies "per invocation", i.e. per HTTP request, per SQS job, per CLI command, per cron task, etc. That does mean you cannot have one job or a PHP script running for more than 15 minutes. If you do, you can either try to split these tasks into smaller jobs, or run longer tasks in EC2 or ECS separately.
75
108
76
109
## Maturity matrix
77
110
@@ -106,7 +139,7 @@ This matrix will be updated as Bref and AWS services evolve over time.
Jobs, cron tasks and batch processes are very good candidates for FaaS. The scaling model of AWS Lambda can lead to very high throughput in queue processing, and the pay-per-use billing model can sometimes result in drastic costs reduction.
237
+
Jobs, cron tasks, and batch processes are very good candidates for FaaS. The scaling model of AWS Lambda can lead to very high throughput in queue processing, and the pay-per-use billing model can sometimes result in drastic cost reductions.
193
238
194
239
Using Bref, it is possible to implement cron jobs and queue workers using PHP. Bref also provides integration with popular queue libraries, like Laravel Queues and Symfony Messenger.
195
240
@@ -199,24 +244,36 @@ This matrix will be updated as Bref and AWS services evolve over time.
199
244
200
245
APIs run on AWS Lambda without problems. Performance is now similar to what you could expect on a traditional VPS.
201
246
202
-
The main difference to account for is that about 0.5% of HTTP requests are cold starts. If your use case requires that _all_ requests are handled below 10ms, serverless might not be a good fit.
247
+
The main difference to account for is that about 0.5% of HTTP requests are cold starts. If your use case requires that _all_ requests are handled in under 10 ms, serverless might not be a good fit.
203
248
204
249
-**Website**
205
250
206
-
Websites run well on AWS Lambda. Assets can be stored in S3 and served via Cloudfront. This is documented in the ["Websites" documentation](/docs/use-cases/websites.mdx). Performance is as good as any server.
251
+
Websites run well on AWS Lambda. Assets can be stored in S3 and served via CloudFront. This is documented in the ["Websites" guide](/docs/use-cases/websites.mdx). Performance is as good as any server.
207
252
208
253
-**Legacy application**
209
254
210
-
Migrating a legacy PHP application to Bref and Lambda can be a challenge. One could expect to rewrite some parts of the code to make the application fit for Lambda (or running in containers in general). For example, file uploads and sessions often need to be adapted to work with the read-only filesystem. Cron tasks, scripts or asynchronous jobs must be made compatible with Lambda and SQS.
255
+
Migrating a legacy PHP application to Bref and Lambda can be a challenge. You can expect to rewrite some parts of the code to make the application fit for Lambda (or running in containers in general). For example, file uploads and sessions often need to be adapted to work with the read-only file system. Cron tasks, scripts, or asynchronous jobs must be made compatible with Lambda and SQS.
256
+
257
+
Not impossible, but definitely not the easiest place to start. As a first step, you can follow the guidelines of [The Twelve-Factor App](https://12factor.net). Note that if your application already runs redundantly on multiple servers, it is much closer to being ready for AWS Lambda and the migration could be simple.
258
+
259
+
-**Event-driven microservices**
260
+
261
+
Serverless is excellent for running event-driven microservice architectures. First of all, being able to standardize and orchestrate the deployment of multiple PHP microservices via a simple `serverless.yml` file and AWS CloudFormation simplifies deployments a lot. Every microservice can deploy in under a minute and easily reference other services or AWS resources. Each microservice then scales independently and in real time without thinking about provisioning or allocating resources, and while keeping costs aligned with usage (not paying for dozens or hundreds of idle containers).
262
+
263
+
On top of that, `serverless.yml` and CloudFormation offer the ability to deeply integrate with other AWS services like SQS, EventBridge, SNS, DynamoDB, and more.
264
+
265
+
Some teams also prefer to deploy everything with Terraform, which is less documented in Bref but doable for those experienced with Terraform.
266
+
267
+
-**Websockets**
211
268
212
-
Not impossible, but definitely not the easiest place to start. As a first step, you can follow the guidelines of [The Twelve-Factor App](https://12factor.net). Note that if your application already runs redundantly on multiple servers, it is much more ready for AWS Lambda and the migration could be simple.
269
+
It is possible to integrate PHP applications with API Gateway WebSocket. This has been done by several Bref users; however, this is currently not documented in Bref directly. On top of that, there is currently no native integration with Laravel Echo.
213
270
214
271
-**Real-time applications**
215
272
216
-
Warm Lambda invocations are very fast (can be as low as 1ms), but cold starts can take 230ms or more. Cold starts are rare on most applications (less than 0.5% of invocations) and can be further mitigated with [provisioned concurrency](https://docs.aws.amazon.com/lambda/latest/dg/provisioned-concurrency.html), but it's unlikely to ensure they will _never_ happen. This makes Lambda a poor choice for real-time applications where latency must be below 100ms for 100% of requests.
273
+
Warm Lambda invocations are very fast (can be as low as 1 ms), but cold starts can take 200 ms or more. Cold starts are rare on most applications (less than 0.5% of invocations) and can be further mitigated with [provisioned concurrency](https://docs.aws.amazon.com/lambda/latest/dg/provisioned-concurrency.html), but it's unlikely you can ensure they will _never_ happen. This makes Lambda a poor choice for real-time applications where latency **must** be below 100 ms for 100% of requests.
217
274
218
275
## Getting started
219
276
220
277
Get started with Bref by reading the [installation documentation](/docs/setup.mdx).
221
278
222
-
Want to know if Bref is a good fit for you? [Let's talk on Zoom](https://calendly.com/bref-enterprise/intro) (30 minutes, yes it's free, I'll answer any questions I can) or find me on [Slack](https://bref.sh/slack).
279
+
Want to know if Bref is a good fit for you? Ask on [Slack](https://bref.sh/slack) in the `#help` channel.
0 commit comments