Bref Documentation

Bref is an open-source Composer package that enables you to deploy PHP applications to AWS and run them on AWS Lambda. It provides PHP runtimes for AWS Lambda, deployment tooling, and deep integrations for frameworks like Laravel and Symfony.

Key benefits of using Bref and serverless include:

• No server maintenance: AWS manages the underlying infrastructure.
• Pay-per-use: You are only charged while your code is actually executing.
• Automatic scaling: The application scales horizontally to meet traffic demands.

Bref uses the serverless CLI for configuration and deployment.

Bref Cloud provides a unified monitoring interface for serverless PHP applications, including:

• Logs: A simplified UI to view and search CloudWatch logs.
• Metrics: Monitoring of Lambda invocations, duration, errors, and more.
• Traces: Visualization of X-Ray traces to analyze performance, including database queries, HTTP calls, and AWS SDK calls.

Bref Cloud users receive a free Bref X-Ray license to enable performance tracing. To activate it, contact support via bref.cloud/support or Slack.

By default, the Bref bridge moves Laravel's storage and cache directories to /tmp because the rest of the filesystem is read-only in AWS Lambda.

Important Limitation: The /tmp directory is local to each Lambda instance and is not shared. If your application scales up or redeploys, new instances will have an empty cache. For shared state (e.g., data caching, API rate limiting, or locking mechanisms), you must use a centralized store like a database, Redis, or DynamoDB.

Bref provides an advanced Sentry integration for PHP applications running on AWS Lambda. This integration allows you to track issues that occur outside of the standard PHP-FPM lifecycle and provides deep visibility into serverless-specific metrics.

Key capabilities include:

• Advanced error tracking: Capture AWS Lambda errors that occur outside of PHP-FPM, such as timeouts or "response too big" errors.
• Non-HTTP exception tracking: Monitor exceptions in event-driven handlers like SQS, EventBridge, S3, and more.
• Cold start tracking: Monitor cold starts and Bref startup duration within Sentry performance tracing.
• Lambda handler performance: Trace the performance of event-driven PHP Lambda handlers.
• AWS SDK tracking: Measure AWS SDK calls within performance tracing to identify bottlenecks.

Bref is designed to minimize vendor lock-in by providing abstractions that allow PHP code to run similarly to a traditional server environment.

Key features that enable this:

• FPM Runtime: The default runtime runs PHP-FPM exactly like a classic server.
• Console Runtime: Console commands run as usual through the dedicated Console runtime.
• Framework Integrations: Bref provides preconfigured integrations for common needs like file storage and queues (e.g., SQS + Lambda runtime integrations for Symfony Messenger and Laravel Queues).
• Logging: Bref preconfigures logs to be sent to AWS CloudWatch automatically.

The AWS Lambda filesystem is read-only, except for the /tmp directory. Files stored in /tmp are not shared between Lambda instances and can be lost when a Lambda scales down or stops.

Key directories:

• /opt/: Where Lambda runtimes and layers (like Bref) are unzipped.
• /var/task/: Where your application code is unzipped. This directory is limited to 250MB. If you exceed this, deploy via Docker images instead.
• /tmp/: The only writable directory, used for temporary files.