Comparison between this bridge and the CacheWerk bridge

[mnapoli]

Hi!

We've been discussing with @tillkruss and @georgeboot the possibility of replacing this Laravel bridge (current repo) with https://github.com/cachewerk/bref-laravel-bridge.

Indeed, the Cachewerk bridge provides more features and solves some design issues that I'd love to correct. One of these is the SQS integration: this bridge adapts Laravel to use SQS the AWS-way. I am now convinced we need to adapt SQS to be used the Laravel-way (use Laravel Queues features like failed messages, retries, etc.).

However the 2 bridges are very different, so I'll try listing the differences, and see what we want to do about each of those. That will help us set expectations and move forward.

I'll update this top description as we discuss here and in Slack (#laravel channel). Feel free to open 1 thread below per topic.

Configure logs to stderr

Replace the stack log driver with stderr.

• Bref bridge: ✅
• CacheWerk bridge: ✅

Do we want this: yes

Formats logs to JSON

Sets logging.channels.stderr.formatter to JSON.

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: ?

Move the compiled views directory to /tmp

And auto-create the directory if it doesn't exist.

• Bref bridge: ✅
• CacheWerk bridge: ✅

Do we want this: yes

Configure Laravel Mix URL

Set the app.mix_url config option.

• Bref bridge: ✅ (sets it from MIX_ASSET_URL)
• CacheWerk bridge: ✅ (sets it from app.asset_url)

Do we want this: yes, but which approach?

Configure HTTP proxies

Set the trustedproxy.proxies config option.

• Bref bridge: ✅
• CacheWerk bridge: ✅

Do we want this: yes

Configure the session driver

Replace the session.driver option from file to cookie.

• Bref bridge: ✅
• CacheWerk bridge: ✅

Do we want this: yes

Move the cache storage directory to /tmp

Set the cache.stores.file.path to /tmp.

• Bref bridge: ✅
• CacheWerk bridge: ✅

Do we want this: yes

Configure the default filesystem from local to S3

Replace the filesystems.default option from local to s3.

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: ?

Configure AWS credentials (from env vars) for DynamoDB, SQS, and S3

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: yes

That's awesome!

Maintenance mode

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: yes

Serve static assets from Lambda

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: ?

Auto-create serverless.yml

• Bref bridge: ✅
• CacheWerk bridge: ❌

Do we want this: ?

PHP-FPM support

• Bref bridge: ✅
• CacheWerk bridge: ❌ (runs via the function layer)

Do we want this: ?

Octane support

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: yes

CLI handler

• Bref bridge: artisan
• CacheWerk bridge: php/runtime.php with custom code

Documentation for "Persistent database sessions"

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: yes

Automatically load secrets from SSM

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: ?

Automatically cache config on cold start

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: yes

That is a brilliant feature!

Automatically add X-Request-ID to logs

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: ?

Configure the scheduler to run in Lambda

The scheduler is configured to run in serverless.yml by default.

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: yes

Full Laravel Queue feature support

For example: configure retries and delays in Laravel Queues instead of SQS, store failed messages where?

• Bref bridge: ❌
• CacheWerk bridge: ?

Do we want this: yes

[mnapoli]

Formats logs to JSON

Sets logging.channels.stderr.formatter to JSON.

• Bref bridge: ❌
• CacheWerk bridge: ✅

Very interesting, I'm curious if it makes logs harder to read for new users? Do you have any experience to share with this, and the reasoning behind the feature?

[tillkruss]

It's just how Monolog logs by default I think.

[mnapoli]

Configure Laravel Mix URL

Set the app.mix_url config option.

• Bref bridge: ✅ (sets it from MIX_ASSET_URL)
• CacheWerk bridge: ✅ (sets it from app.asset_url)

Do we want this: yes

Which behavior is preferable? How is app.asset_url set?

[georgeboot]

The mix one is specific to Laravel mix, while asset url is generic between mix, vite and more.

[buddhaCode]

I opt for the CacheWerk way. I stumbled across this point and cost me some time to figure out (see brefphp/bref#1046). Using the app.asset_url config is a more intuitive way.

[mnapoli]

👍 thanks for the feedback!

Also Mix has been replaced by Vite, so it makes sense to go that route!

[mnapoli]

Configure the default filesystem from local to S3

Replace the filesystems.default option from local to s3.

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: ?

I'm wondering about the consequences of automatically reconfiguring this -> any negative consequence to expect? Users would be surprised maybe?

Also they need to create the S3 bucket, should we create it automatically in the template serverless.yml? Maybe not 🤔

[tillkruss]

It could be disabled by default yeah.

[georgeboot]

Yeah I'd say this should be opt-in by the user.

Maybe add a template for it in the docs.

[mnapoli]

Maintenance mode

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: yes

However I wonder if we can't use Laravel's native maintenance mode handlers? That would avoid having to implement anything, including the 503 responses. Any reason not to?

[mnapoli]

Response by @georgeboot

Laravel enables it via a file. Could use that, but then you have to deploy to enable/disable it. I find this approach much more sleek.

Right, but what I'm wondering is: could we use the official Laravel code but make it work via the env variable somehow?

The current code takes the env var and stores the value in a file: https://github.com/cachewerk/bref-laravel-bridge/blob/427266546eb52eddb80b6cfb890584da4b909c1b/src/MaintenanceMode.php#L19-L25

Could we use the existing Laravel class and write the file it uses directly (based on the value of the env var): https://github.com/laravel/framework/blob/b9203fca96960ef9cd8860cb4ec99d1279353a8d/src/Illuminate/Foundation/FileBasedMaintenanceMode.php#L62

Or maybe even: look at the env var and call FileBasedMaintenanceMode::activate() based on the value? Not sure how much I'm making sense.

[tillkruss]

My focus was a fast on/off mechanism, because full deploys are slow. Open to improvements of course.

[georgeboot]

Users only actually use maintenance mode when it's easy and quick to enable / disable. @tillkruss found a very nice solution for that.

I have never seen anyone committing their 'down' to vcs, so I don't think it really matters where it reads from.

Would be amazing if artisan down would actually work though.

[tillkruss]

💯

[mnapoli]

Serve static assets from Lambda

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: ?

I'm not sure that feature makes sense since assets are supposed to be served from S3. Any reason for this?

[tillkruss]

I should be optional probably. I figured since /favicon.ico and /robots.txt requests may happen regardless and get redirected to S3, I might as well serve these tiny files via PHP and put them behind Cloudflare to the responses are cached.

[georgeboot]

If you actually have a favicon etc, you probably have a meta tag. Are services still randomly attempting /favicon.ico these days?

It doesn't cost a lot to have the feature, other than that binary responses need to be enabled, which somewhat reduces response payload size due to base64.

I know Vapor let's you set a x-vapor-base64 header on the response, which will tell the event handler to base64 the response.

Maybe that would be a nice feature for the bridge/Bref as well?

[tillkruss]

You're right, it's cheap to support since it's opt-in.

That be neat to base64 responses only when needed ❤️

[mnapoli]

Auto-create serverless.yml

• Bref bridge: ✅
• CacheWerk bridge: ❌

Do we want this: I'd say yes

Users should have a pre-configured serverless.yml created via php artisan vendor:publish, instead of creating it manually. What do you think?

[tillkruss]

Yeah, we should publish a static example, and offer a little cli wizard to generate one with the right names, TLD, etc.

[mnapoli]

PHP-FPM support

• Bref bridge: ✅
• CacheWerk bridge: ❌ (runs via the function layer)

Do we want this: I'd say yes.

I think that this is very important users run Laravel in a standard (i.e. "FPM") environment by default. Octane is cool, but has an impact on how the application runs, and doesn't work with all apps.

The CacheWerk bridge offers running without Octane, but that requires using the function layer. I don't think it's a good fit: first, the app doesn't run in an FPM environment (e.g. $_GET and such) which could be used by less modern apps, and second because it has worse performances.

My conclusion is that we need to use the FPM runtime by default, but I'm interested to hear what you think.

[mnapoli]

Response by @georgeboot

It does not work out of the box, but it's supported. All that is needed is a call to the directory helper in the index.php, and setting public/index.php as the entrypoint in the serverless config.

Right, it's supported good to know. What I'm thinking of is actually documenting that by default. That may not have a big impact on the code, but more on the docs/positioning of the bridge, so that's why I wanted to bring up the discussion first.

Ideally, there would be something in bref that we can register a "middleware" to, that runs on every cold start before the entry point is invoked.

Oh yeah, if that's needed we can look into such a feature.

[tillkruss]

It would be nice to have FPM support as well.

[mnapoli]

CLI handler

• Bref bridge: artisan
• CacheWerk bridge: php/runtime.php with custom code

I think we can simplify the CacheWerk approach by executing php artisan in Lambda directly (thanks to the console layer), instead of going through custom PHP code in php/runtime.php. Of course that also means putting the initialization code in php/runtime.php somewhere else (cause it wouldn't be executed anymore).

Why? It would look more "classic" Laravel (the console function runs php artisan like on any server), that's reassuring and simpler for users to understand.

WDYT?

[tillkruss]

Yeah, certainly room for improvement 👍

[georgeboot]

Agreed. Again the initialisation code.

@mnapoli what do you recon is a good way for Bref to have initialisation middleware type of things? That will also in this case mean the user doesn't have to alter their index.php / artisan

[mnapoli]

Automatically load secrets from SSM

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: ?

Related discussion: cachewerk/bref-laravel-bridge#8

The php artisan env:encrypt command seems to be the simplest, cheapest and most scalable option. Should we standardize around that?

[georgeboot]

I don't like the env:encrypt tbh.

Don't like that you probably have the vault + key on your local computer etc. Sure, could cook something up in CI but probably not going to happen. And it's only a real issue on super large scale.

Parameter Store (especially when wrapped in a cool artisan command) offers better DX if you ask me.

[tillkruss]

Agreed, especially with cachewerk/bref-laravel-bridge#29.

It would be nice to eventually support env:encrypt, just for compatibility.

[georgeboot]

Agreed. Also, the decryption key still needs to be supplied somehow. Most people are just going to commit that vcs and now you've got secrets+key in vcs.

[mnapoli]

Automatically add X-Request-ID to logs

• Bref bridge: ❌
• CacheWerk bridge: ✅

Do we want this: ?

Do we want to enable this by default? What does it look like in practice? Anyone uses it?

[tillkruss]

It's useful for Sentry and similar integration to know the request ID.

[georgeboot]

How it it used in Sentry? Afaik it's (mainly) used for distributed tracing.

[tillkruss]

I set it in a middleware, along with some user metadata.

[georgeboot]

I set it in a middleware, along with some user metadata.

Right, but how do you practically use it in Sentry? Do you correlate it with something? Do you use it to look up logs/metrics in AWS?

Reason I'm asking is because I've seen the AWS request ID a lot, but never really understood what one can do with it.

[tillkruss]

Exactly, tracing down extra logging information in CloudWatch.

[georgeboot]

However I wonder if we can't use Laravel's native maintenance mode handlers? That would avoid having to implement anything, including the 503 responses.

Laravel enables it via a file. Could use that, but then you have to deploy to enable/disable it. I find this approach much more sleek.

PHP-FPM support

It does not work out of the box, but it's supported. All that is needed is a call to the directory helper in the index.php, and setting public/index.php as the entrypoint in the serverless config.

Ideally, there would be something in bref that we can register a "middleware" to, that runs on every cold start before the entry point is invoked.

[mnapoli]

Thanks for the responses! If you don't mind I'll copy them in the related thread and continue the discussion there, that way we have 1 thread per topic.

[georgeboot]

Yeah sorry, you added the replied while I was typing this haha

[mnapoli]

Full Laravel Queue feature support

For example: configure retries and delays in Laravel Queues instead of SQS, store failed messages where?

• Bref bridge: ❌
• CacheWerk bridge: ?

Do we want this: yes

I'm not sure if all features are implement yet and what's missing (excluding the issues already open). Any idea?

[tillkruss]

Two more to go, then it's feature complete I think:
cachewerk/bref-laravel-bridge#24
cachewerk/bref-laravel-bridge#30

[benjam-es]

Hi @tillkruss. I have just been attempting to try out the v2 branch on a fresh laravel project to experiment.

Following the instruction on README for octane doesn't seem to be working. Could there another step I have missed?

php Handler `/var/task/Bref\LaravelBridge\Http\OctaneHandler` doesn't exist

[georgeboot]

How does your serverless.yml look like?

It looks like you are using it with the wrong namespace.

[mnapoli]

@benjam-es I just tried this again with the latest version of bref and the bridge

    "require": {
        "php": "^8.0.2",
        "bref/laravel-bridge": "v2.x-dev",

and it works fine with Octane. Could you open a separate discussion?