The Embed SAPI

Recall from the Introduction that PHP is built out of a system of layers. At the highest layer are all the extensions that provide the userspace library of functions and classes. Meanwhile, the bottom is occupied by the Server API (SAPI) layer, which acts as an interface to web servers such as Apache and IIS as well as the command line interface (CLI).

Among the many SAPI implementations is a special type known as Embedshort for embeddable. When this SAPI implementation is built, a library object is created that contains all the PHP and Zend API functions and variables you've come to know, along with an extra set of helper functions and macros to make interfacing from an external program simple.

Generating the library and header files of the Embed SAPI is performed just like any other SAPI compilation. Just pass enable-embed to the ./configure command and build as usual. As before, it will be helpful to use enable-debug in case errors pop up and need to be tracked down.

You'll also want to keep enable-maintainer-zts turned on both for the familiar reason that it will help you notice coding mistakes, but also for another reason. Imagine for a moment that you have more than one application that will be using the PHP Embed library to perform scripting tasks; one of these is a simple, short-lived application with no use for threading and so would want ZTS turned off for efficiency.

Now imagine that the second application does use threading and that, like a web server, each thread needs to track its own request context. If ZTS is turned off, only the first application will be able to use the library; however, with ZTS enabled, both applications can take advantage of the same shared object in their own process space.

You could, of course, build both versions and simply give them different names, but that tends to be more problematic than does simply accepting the minor slowdown that including ZTS support when it's not needed.

By default, the embed library will be built as a shared object libphp5.soor dynamic link library under Windowshowever, it might be built as a static library using the optional static keyword: enable-embed=static.

Building a static version of the Embed SAPI avoids the ZTS versus non-ZTS problem, as well as the potential situation of having multiple PHP versions on a single system. On the downside, it does mean that your resulting application binary will be significantly largerbearing the full weight of the Zend Engine and PHP frameworkso consider your choices with as much or more care as you would other, smaller libraries.

Whichever build type you choose, once you issue make install, libphp5 will be copied to lib/ under your ./configure selected EPREFIX root. An additional header file named php_embed.h will also be placed into EPREFIX/include/php/sapi/embed next to several other important headers that you'll need as you compile programs that use the PHP Embed library.