NGINX Unit: a historical application server for PHP

Status first: historical and archived

The official repository banner says it was archived by the owner on Oct 8, 2025 and is read-only. The README note says there will likely be no further development and that security vulnerabilities may be unaddressed. It also says the repository may be cloned and used under its current license, which the repository lists as Apache-2.0.

For this guide, NGINX Unit is historical. Do not choose it for new production work. Read it to understand an architecture you may meet in older systems, and to see how an application server differs from the classic web-server-plus-PHP-process pairing.

What the project is

The README describes NGINX Unit as a lightweight, open-source universal web app server with two primary capabilities: serving static media assets and running application code in eight languages. PHP is one of them, and WebAssembly components (WASI 0.2) are also mentioned. Unit is not an alternative PHP interpreter. It is also not a framework, a CMS, or an async library. It is an application server that hosts a language module, so PHP code is still executed by PHP through the unit-php module.

Two classification points follow from that:

• PHP core is the language engine. Unit is a separate server that loads it through a module. Frameworks such as Laravel or Symfony and CMS products such as Drupal would sit on top of the PHP layer. The source packet says nothing about running any of them on Unit, so this guide makes no claims about them.
• Swoole and Open Swoole are separate PHP extension projects. They are not Unit and are not covered by this source.

Architecture and control model

The README describes an asynchronous, multithreading architecture made of multiple processes, aimed at security and robustness. Configuration is not a file you edit and reload. Unit exposes a RESTful JSON control API, usually reachable through a Unix domain socket, and the README says it allows dynamic updates without interruption.

The model has two main pieces in the README's PHP example:

• An application object with a type (php) and a root directory.
• A listener that binds an address and port and passes requests to an application through a pass value such as applications/helloworld.

You PUT JSON into the /config/applications and /config/listeners sections, then read /config/ to see the combined result.

Unit versus Nginx plus FPM

The source does not discuss PHP-FPM, so treat this comparison as conceptual. A common classic setup is a web server forwarding requests over FastCGI to a separate PHP process manager, with two products and two configuration surfaces. In the README, Unit is a single server that serves static files, manages application processes, and is configured through its JSON API. It compresses several layers of the stack into one component. Despite the shared name, Unit is a separate product from the Nginx web server. If you ever work with FastCGI, never expose it publicly, and keep development listeners on 127.0.0.1.

Request lifetime and state leakage

In a classic request lifetime, PHP state is created and discarded for each request. Persistent workers keep the process alive across requests, so static properties, globals, singletons, open connections, caches, and per-user data can leak from one request into the next. A user object cached in a static property, for example, could be served to the wrong visitor.

The supplied source does not say whether Unit's PHP module resets state per request or keeps it. That is unknown here. Do not assume either behavior. Check the Unit documentation referenced from the repository. If workers can persist, clean up explicitly: reset or avoid mutable statics, scope data to the request, close or validate connections, and clear caches that hold user data.

Practical use cases

The realistic uses today are narrow:

• Reading or maintaining an existing Unit deployment that you inherited.
• Studying how a single server can host several language runtimes behind one JSON control API.
• Comparing an API-configured application server with file-configured stacks.

For anything new, choose a maintained alternative covered elsewhere in this track.

Installation approach

The README lists several routes: Homebrew on macOS (brew install nginx/unit/unit, which installs unitd and unitctl), a Docker image (unit:TAG), and package repositories for Debian, Ubuntu, Amazon Linux, Fedora, and Red Hat through a helper script. It warns that the latest Docker tag may not include specific language modules, so you must check the available tags in the docs before pulling. This guide does not name a tag or a Compose file, because the source does not give a PHP-specific tag, and inventing one would be unsafe. The example below therefore assumes a native host where the unit-php module is already installed and Unit is running.

Compatibility and versions

The source does not state a current Unit version, supported PHP versions, or any benchmark results, so these are unknown. The learning track targets PHP 8.4 with PHP 8.5 planned. Whether Unit's PHP module works with 8.4 is not established by the source. The example script is deliberately trivial and makes no PHP 8.4 claim.

Strengths

• One server for static files and several application languages, according to the README.
• Dynamic configuration through a JSON API, with an OpenAPI specification mentioned for the control API.
• Apache-2.0 license, with the code still available to clone.

Limitations

• Archived and read-only, with unaddressed vulnerabilities possible.
• No evidence in the source of PHP 8.4 or 8.5 support.
• PHP request lifecycle details are not in the source.
• Not a framework, CMS, or standalone interpreter, and no guidance here for framework or CMS setup.
• The example needs a native Unit installation and is not a browser exercise.

Deployment notes

If you must operate an existing Unit instance, keep the control socket private, bind listeners to loopback or place them behind a controlled network boundary, and plan a migration. Because security issues may go unfixed, isolate it and do not expose it directly to untrusted networks without an informed risk decision.

The example

The example follows the README's Hello World: a one-line PHP script, an application object, and a listener on 127.0.0.1:8080. Replace the placeholder socket path with your real control socket. Expect to need elevated privileges for the /www directory and possibly for the socket.

Links

The only official source used is the archived repository at https://github.com/nginx/unit.

<?php

echo "Hello, PHP on Unit!";

{
  "helloworld": {
    "type": "php",
    "root": "/www/helloworld/"
  }
}

{
  "127.0.0.1:8080": {
    "pass": "applications/helloworld"
  }
}

sudo mkdir -p /www
sudo cp -R www/helloworld /www/
curl -X PUT --data-binary @config/applications.json --unix-socket /path/to/control.unit.sock http://localhost/config/applications
curl -X PUT --data-binary @config/listeners.json --unix-socket /path/to/control.unit.sock http://localhost/config/listeners
curl http://127.0.0.1:8080
curl --unix-socket /path/to/control.unit.sock http://localhost/config/