Add chapter on embedding PHP

[cubiclesoft]

There is almost no documentation on the Internet on how to compile and use the PHP embed SAPI. The only "official" source is a very old book by Sara Golemon entitled "Extending and Embedding PHP." There's a macro called PHP_EMBED_START_BLOCK that appears to kick off the linkage between C/C++ code and the PHP embed SAPI. This is the first complete code sample that I found by searching for that macro:

https://stackoverflow.com/questions/73345686/store-output-of-php-execute-script

[Girgias]

I know @dunglas had started to write a bit because he hit the same issue while working on FrankenPHP

[SammyK]

The embed SAPI readme has basic info on how to compile and run the SAPI.

The embed SAPI isn't very useful on its own. It only allows setting up a full PHP startup + request cycle without the ability to take control of the individual request cycle within the startup cycle. It really serves as a bare-bones SAPI that is a good starting point for a fork.

Example: the unit tests for the Datadog PHP tracer are run with Tea SAPI which is a fork of embed.

Adding a chapter to the internals book on compiling/forking embed is a good idea. 👍

(Tangentially related; libphp is only created when PHP is compiled with --enable-embed which means if you fork embed, you'll need to enable embed to gain access to the shared lib. IMO we should add a way to create the shared lib without explicitly enabling embed so that we don't hit the too-many-SAPIs limit at compile time when you have a custom SAPI that you'd like to run alongside several other in-tree ones. But I only dream. 😄)