An advanced Laravel integration for Bref, including Octane support.

This project is largely based on code from PHP Runtimes, Laravel Vapor and Bref's Laravel Bridge.

Why does this exist and why not just use Laravel Vapor? Vapor is fantastic, easy to use and the better choice for situations, its $399/year pay for itself not having to maintain your own infrastructure.

For Relay's API however we needed something that 1) is open source (Vapor's API is a black box), 2) is secure (Vapor has admin access to databases and environment variables) and 3) doesn't leave us at the mercy of a support team (Vapor has no enterprise support). We also didn't want to be forced to use CloudFront on top of Cloudflare, but that's just nerdy preference.

We needed an open source solution that gives us more fine-grained control and is secure.

Bref + Serverless Framework is exactly that, however Bref's Laravel integration is rather basic, it easily exposes SSM secrets and it doesn't support Laravel Octane.

So we built this.

First, be sure to familiarize yourself with Bref and its guide to Serverless Laravel applications.

Next, install the package and publish the custom Bref runtime:

composer require cachewerk/bref-laravel-bridge php artisan vendor:publish --tag=bref-runtime 

By default the runtime is published to php/ where Bref's PHP configuration resides, but it can be move anywhere.

Next, we need to set up in the AWS_ACCOUNT_ID environment variable in your serverless.yml:

provider: environment: AWS_ACCOUNT_ID: ${aws:accountId}

Then set up your functions:

functions: web: handler: php/runtime.php environment: APP_RUNTIME: octane BREF_LOOP_MAX: 250 layers: - ${bref:layer.php-81} events: - httpApi: '*' queue: handler: php/runtime.php timeout: 59 environment: APP_RUNTIME: queue layers: - ${bref:layer.php-81} events: - sqs: arn: !GetAtt Queue.Arn batchSize: 1 maximumBatchingWindow: 60 cli: handler: php/runtime.php timeout: 720 environment: APP_RUNTIME: cli layers: - ${bref:layer.php-81} - ${bref:layer.console} events: - schedule: rate: rate(1 minute) input: '"schedule:run"'

If you don't want to use Octane, simply remove APP_RUNTIME and BREF_LOOP_MAX from the web function.

To avoid setting secrets as environment variables on your Lambda functions, you can inject them directly into the Lambda runtime:

provider: environment: APP_SSM_PREFIX: /${self:service}-${sls:stage}/ APP_SSM_PARAMETERS: "APP_KEY, DATABASE_URL"

This will inject APP_KEY and DATABASE_URL using your service name and stage, for example from /myapp-staging/APP_KEY.

Finally, deploy your app:

sls deploy --stage=staging 

Check out some more comprehensive examples.

If you want to serve some static assets from your app's public directory, you can use the ServeStaticAssets middleware.

First, publish the configuration:

php artisan vendor:publish --tag=bref-config 

Then define the files you want to serve in bref.assets.

Lastly tell Bref to support binary responses on your web function:

functions: web: handler: php/runtime.php environment: BREF_BINARY_RESPONSES: 1

If you're using PostgreSQL 9.6 or newer, you can take advantage of persistent database sessions.

First set idle_in_transaction_session_timeout either in your RDS database's parameter group, or on a specific database itself.

ALTER DATABASE SET idle_in_transaction_session_timeout = '10000' -- 10 seconds in ms

Lastly, set the OCTANE_PERSIST_DATABASE_SESSIONS environment variable.

functions: web: handler: php/runtime.php environment: APP_RUNTIME: octane BREF_LOOP_MAX: 250 OCTANE_PERSIST_DATABASE_SESSIONS: 1

Just like with Bref, you may execute console commands.

vendor/bin/bref cli <service>-<stage>-cli -- route:list vendor/bin/bref cli example-staging-cli -- route:list 

Similar to the php artisan down command, you may put your app into maintenance mode. All that's required is setting the MAINTENANCE_MODE environment variable:

provider: environment: MAINTENANCE_MODE: ${param:maintenance, null}

You can then quickly put all functions into maintenance without running a full build and CloudFormation deploy:

serverless deploy function --function=web --update-config --param="maintenance=1" serverless deploy function --function=cli --update-config --param="maintenance=1" serverless deploy function --function=queue --update-config --param="maintenance=1" 

To take your app out of maintenance mode, simply omit the parameter:

serverless deploy function --function=web --update-config serverless deploy function --function=cli --update-config serverless deploy function --function=queue --update-config 

One caveat with the --update-config flag is that it doesn't do objects in environment variables in the serverless.yml:

provider: environment: SQS_QUEUE: ${self:service}-${sls:stage} # good SQS_QUEUE: !Ref QueueName # bad SQS_QUEUE: # bad Ref: QueueName