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
+78-21Lines changed: 78 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,32 +32,24 @@ Bref aims to make running PHP applications simple.
32
32
33
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 more [how AWS Lambda and Bref work, read more here](/docs/how-it-works).
61
53
62
54
## Use cases
63
55
@@ -73,6 +65,47 @@ Bref aims to support any PHP framework. It comes with deep integrations with Lar
73
65
74
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).
75
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 file systems.
78
+
- Logs must not be written to disk, instead they must be collected to a centralized system (on AWS Lambda logs written to `stderr` are automatically centralized to 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 however 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 200ms to 500ms (or even more on very large applications) to the HTTP response time.
93
+
94
+
If your application cannot tolerate that occasional latency on the p99 metric, then serverless might not be the best fit.
95
+
- AWS Lambda has a limit of ~4MB 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 those). 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 websocket 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: this is however 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 in smaller jobs, or run longer tasks in EC2 or ECS separately.
108
+
76
109
## Maturity matrix
77
110
78
111
The matrix below provides an overview of the "maturity level" for common PHP applications.
@@ -106,7 +139,7 @@ This matrix will be updated as Bref and AWS services evolve over time.
@@ -211,12 +256,24 @@ This matrix will be updated as Bref and AWS services evolve over time.
211
256
212
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 more ready for AWS Lambda and the migration could be simple.
213
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**
268
+
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.
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 1ms), but cold starts can take 200ms 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.
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