feat: Add Caddy placeholders

[Starfox64]

This pull request introduces a mechanism to expose HTTP response details from FrankenPHP as placeholders for use in Caddy directives, improving observability and configurability. The core of the change is a new responseWriterInterceptor that captures response status and headers, making them available as placeholders. Documentation has also been updated to describe the new placeholders.

This is inspired by Caddy's native reverse proxy module: https://github.com/caddyserver/caddy/blob/65e0ddc22137bbbaa68c842ae0b98d0548504545/modules/caddyhttp/reverseproxy/reverseproxy.go#L955-L961

[AlliBalliBaba]

Would this only be used for formatting access logs? Here it says that part of the original response will be used for routing decisions, not sure though what that means if you're not working with a reverse proxy.

Reverse proxies often modify the response, so these placeholders can help if you want to log values from the original response. But in the FrankenPHP case the response is not modified and all original status/headers are already present in the access logs.

[Starfox64]

I'll give you the full context of what I'm trying to achieve since that's not entirely reflected in the generic example I added:

I'm migrating from Apache with mod_php which has a apache_note() function to pass strings over to Apache which can then be used for logging (and maybe other things?). In my use case I used this to log the userId and tenantId to my access log.

However there is no such mechanism in Caddy/FrankenPHP but the way I've seen nginx and Caddy in reverse proxy mode handle this requirement has been by adding that information in response headers which then get stripped before being sent out to the client.

I don't want to use caddy's default response headers logging because:

1. I don't want to log response headers (storage/costs optimization)
2. I don't want this information to be sent out to the client

[dunglas]

IMHO we should add a function similar to apache_note instead of adding placeholders, which will have a non-negligible memory and CPU cost for all requests.

[AlliBalliBaba]

I agree, we probably shouldn't replicate the hacky solution. Ideally a function call would add that context to the logger/replacers. Not sure though how to most elegantly forward that info to caddy.

[Starfox64]

That's what I've also been considering, I've gone ahead and implemented that function.

I believe the remaining linter error is a bug: https://github.com/super-linter/super-linter/pull/7094 https://github.com/super-linter/super-linter/pull/7089

[AlliBalliBaba]

@Starfox64 would an explicit frankenphp_log function like the one added by #1979 also work for you?