While trying to debug a new bit of nginx config to connect to a PHP-FPM instance, I looked through my other site config files and found this at the bottom of one. I must have worked this out a year or two ago while debugging all this, and it certainly shows how nonsensical this stuff is. I wonder how it ended up like this.

Posting this in case it's useful to others trying to debug configs intended to interface with PHP-FPM. It is probably accurate for PHP 7.3 or 7.4, not 100% sure which was installed when I wrote it. Might also be accurate for more recent versions, who knows!

# The following parameters are required to get PHP-FPM to execute a
# script: REQUEST_METHOD, SCRIPT_FILENAME and SCRIPT_NAME.

# If REQUEST_METHOD is not present, PHP-FPM will check SCRIPT_FILENAME
# but not do anything more. If REQUEST_METHOD is present and its
# value is HEAD, PHP-FPM will also check SCRIPT_NAME but not run it.
# Otherwise it will check both and run the script.

# SCRIPT_FILENAME must be a pathname that PHP-FPM can stat(). It does
# not need to be a plain file and its permissions and ownership don't
# matter. If relative, it's interpreted relative to FPM's "chdir"
# (which is in turn ends up interpreted relative to FPM "chroot").
# security.limit_extensions is checked against SCRIPT_FILENAME, not
# SCRIPT_NAME. If anything goes wrong at this stage the error message
# logged is "Primary script unknown".

# SCRIPT_NAME is always interpreted relative to PHP's doc_root config
# parameter even if it starts with a "/". PHP-FPM must be able to open
# and read it or it'll log the error message "Unable to open primary
# script: FILENAME (ERROR)" where FILENAME is the value of SCRIPT_FILENAME
# (*not* SCRIPT_NAME, so not necessarily the file it can't open!) and
# ERROR is an error message, e.g. "Permission denied" or "No such file or
# directory". This is the file that is actually interpreted as PHP code.