ngx-php: running embedded PHP inside nginx instead of beside it

PHP in the worker process, not behind a FastCGI socket

ngx-php is an extension module of the nginx web server that implements embedded PHP 7 and PHP 8 scripting to process nginx locations and variables. The distinction from the usual arrangement is the whole point. With php-fpm, nginx proxies the request to a separate process over a socket, and with mod_php the interpreter is loaded into Apache. Here the script runs inside the nginx worker, which means it can read and write nginx variables directly and can issue I/O without blocking the worker. The README says the project draws on the design of ngx_lua, the OpenResty module, and is committed to providing non-blocking web services with performance advantages over php-cgi, mod_php, php-fpm and hhvm. It also says ngx-php does not want to replace anything, just wants to provide a solution, and that a legacy ngx_php5 branch exists holding earlier code practices.

The global state warnings are the most useful paragraph in the README

There is a section titled what is different with official PHP, and it is short and unflattering to conventional PHP habits. A global variable is unsafe in a per-request model. A static variable of a class is unsafe in a per-request model. Singleton mode should not be designed for. And the native IO function works fine but slows down nginx. All four follow from the architecture. Because the script executes inside a long-lived worker process rather than in a fresh interpreter per request, state that PHP programmers assume is reset between requests is not reset. A static counter increments across requests. A cached lookup in a global stays cached. The IO point is the flip side of the non-blocking design: a blocking read inside the worker stalls every other request that worker is handling, so the module gives you coroutine-style primitives instead and expects you to use them.

Building it means compiling PHP with embed and nginx with the module

The installation path is a source build, and it has three parts: PHP with the embed SAPI, nginx, and the module itself. The compile instructions download a PHP source tarball, configure it with --enable-embed, and make install, then clone the module and download nginx sources. Four environment variables tell the nginx configure step where PHP lives, PHP_CONFIG, PHP_BIN, PHP_INC and PHP_LIB, and the configure line adds the module twice, once for the bundled NDK under third_party and once for ngx-php itself, with a linker option pointing at the PHP library directory.

$ export PHP_CONFIG=/path/to/php/bin/php-config
$ export PHP_BIN=/path/to/php/bin
$ export PHP_INC=/path/to/php/include/php
$ export PHP_LIB=/path/to/php/lib

The module depends on the NDK, the nginx development kit, and that dependency is why the two load_module lines in nginx.conf are mandatory.

load_module modules/ndk_http_module.so; load_module modules/ngx_http_php_module.so;

Ordering matters here: the NDK module has to be loaded first, and if you skip it the PHP module will fail to initialise.

content_by_php_block puts script inside a location

The nginx configuration syntax is the interface you will spend your time in, and the example config shows the pattern clearly.

        location /php {
            content_by_php_block {
                echo "hello ngx-php";
            }
        }

The content_by_php_block directive takes a block of PHP and runs it when the location matches. Alongside it, the README documents a set of nginx-facing functions for PHP: ngx_request_document_uri to read the request URI, ngx_query_args and ngx_post_args for the query string and the POST body, ngx_var_get to read a variable you set with the set directive, ngx_sleep to pause, and a socket API with ngx_socket_create, ngx_socket_connect, ngx_socket_send, ngx_socket_recv and ngx_socket_close. The socket functions are the ones that show the non-blocking model in practice, since the example sends an HTTP request with a yield on each step.

The Docker image compiles nginx and PHP into two Alpine stages

The Dockerfile is a good way to understand the build, because it shows the module compiled as a dynamic module rather than a static one. The first stage starts from nginx:stable-alpine, installs the build toolchain and php7-dev with php7-embed, then reads the nginx version from the base image, downloads the matching nginx source, and configures it with the base image's own configure arguments minus any dynamic module flags, adding the NDK and ngx-php as dynamic modules. It makes the build and copies out ndk_http_module.so and ngx_http_php_module.so into a modules directory. The second stage is again nginx:stable-alpine, this time installing only php7-embed, patching nginx.conf to include the modules directory, and writing a php.conf with the two load_module lines.

$ docker build -t nginx-php7 .
$ : "app.conf: Create nginx config"
$ docker run -p 80:80 -v $PWD/app.conf:/etc/nginx/conf.d/default.conf nginx-php7

The pinned nginx:stable-alpine base and the runtime that carries only the compiled modules and php7-embed is a sensible split for image size.

Linux only, with a bounded version matrix

The requirements are three lines and they rule the project out for a lot of people. Linux only. PHP 7 through PHP 8.3. And nginx from 1.4.7 to 1.26.x. That is a wide nginx range, which reflects how stable the module interface has been, and a PHP range that stops at 8.3 rather than tracking the newest release. The macOS story is handled with a separate installation document in the docs directory rather than in the README, and the CentOS and RedHat 7 and Ubuntu sections both show a package route where the distro provides an nginx module package, with the Ubuntu route pulling PHP 7.4 packages from the ondrej PPA along with the embed library. The repository also has a Dockerfile at the root, a ChangeLog, a config directory, a src directory, a t directory and a utils directory, plus docs with Chinese-language installation notes for macOS.

Editorial conclusion

ngx-php fits a Linux operator who wants PHP inside nginx rather than behind it, and who needs the script to reach the request context or to use non-blocking I/O without a sidecar. It does not fit a hosting environment on Windows or macOS, and it does not fit an application that relies on shared global state between requests, since the README calls that unsafe. Verify first that your nginx and PHP versions fall inside the stated ranges, read the notes on global variables and static class properties before you port existing code, and test the non-blocking API on your own hardware, because the whole value proposition depends on it working as documented.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-2-Clause
3. README
4. Releases
5. rryqszq4/ngx-php on GitHub