Documentation request: architecture overview

[nickchomey]

It stands to reason that many people who will be using Frankenphp have little to no experience with Go or even Caddy.

While it does appear to be relatively easy to get started with frankenphp without such knowledge, surely people would benefit from having at least a conceptual understanding of what is going on. With that, they might even start dabbling in writing their own Go/Caddy modules.

I have no expectation that Frankenphp should provide detailed documentation on Caddy, Go etc, but would it be possible to add a simple documentation article that provides an overview of Frankenphp's architecture?

Is Caddy embedded in Frankenphp? Or is Frankenphp a Caddy Module? What about Mercure? How would we extend and/or modify them all - with additional caddy modules? Can Go code be written to make use of Frankenphp worker mode, or is frankenphp even needed if we intend to write Go code? Etc...

I'm sure those questions are contradictory and even incoherent, but I hope you get the sense of what I'm trying to describe and learn.

Id imagine it could all be explained in a few paragraphs, along with some links to relevant Caddy documentation and perhaps Go documentation.

Thanks!

[natepage]

Hi there!

Thank you for creating this creature (frankenphp) 😄, and thank you @nickchomey for creating this issue, I had very similar questions after reading the docs. I completely understand all this is very young, and am impressed by the amount of resources already available.

I'm really sorry I had lots of things I wanted to say/ask but when I started to writing this comment I wasn't sure how to structure it all... So I hope that an example and some context with a dot list of thougts are ok and it helps understanding the point.

I work on a bunch of projects based on Symfony + Openswoole which use functionalities like:

• multiple reactors/workers with coroutine enabled
• caching using swoole tables
• database connections pool shared across coroutines using channel
• persistent database connections with dedicated coroutine to close idle ones after x amount of time
• Symfony kernel listeners to reset the app "critical" state in between requests
• Symfony kernel listeners to stop Swoole Worker in case the app state is compromised

As much as the aboves are great, we've learned the hard way they have side effects 😄

I think it would very helpful to understand how Frankenphp "impacts" the way PHP behaves, especially with worker mode.

• Is memory shared between Workers?
• Can a Worker process more than one request in parallel using goroutines?
• Could we have access to goroutines via PHP? Goroutine::run(function (): void {});
• Could we see things similar to Swoole Tables for storing data in memory?
• Could we hook into Frankenphp events using callbacks? And would we even need to? (e.g. worker start)
• Could we instruct Frankenphp to stop a Worker in case the app state is compromised?
• Is it compatible with debugging extensions such as Xdebug/PCOV?
• Does it support hot reload for local development? Or the server must be restarted after each code change?
• Any impact on PHP extensions such as curl and its multi handle?
• Are functions to echo contents while processing the request supported out the box? (\var_dump(), \print_r(), \dump(), \dd())
• Should serving static files be done in Caddy or PHP?
• ...

I'm obviously not writting all this down expecting an answer to each of those questions, but we've faced all of them while migrating our projects to Openswoole and the learning process was painful because it all looked great and simple at the start but the devil is in the details!

Sorry for this long comment, Frankenphp has got me excited, and I'm very keen to see how it evolves! I hope all this blabla makes sense and is somehow helpful, I'm not really good at putting things on paper, but would be up for a chat if needed.

Thank you!

[dunglas]

Hi,

Just a quick reply to say that I'm currently in vacation, but I plan to work on such docs when I'll be back!