Documentation
¶
Overview ¶
Package nativephp runs PHP-FPM on the host instead of in a container, for sites whose runtime is "native". macOS bind-mounts the project into the podman VM, so a containerised PHP pays a virtiofs crossing on every file it reads; running on the host removes that boundary entirely.
Index ¶
- Constants
- func BinaryPath(version string) string
- func ConfPath(version string) string
- func DevtoolsExtensionPath(version string) string
- func Ensure(version string) error
- func EnsureInstalled(version, binary string) error
- func EnsureShim(version, cliBinary string) (string, error)
- func EnsureSupported(version string) error
- func Extensions(version string) ([]string, error)
- func FPMBinaryPath(version string) string
- func FPMConfig(version, errorLog string) (string, error)
- func HostCommand(dir string, argv []string, extraEnv ...string) (*exec.Cmd, error)
- func HostPath(dir string) string
- func IniScanDir(version string) string
- func IniScanDirs(version string) []string
- func ListInstalled() []string
- func Loaded(version string) bool
- func LogPath(version string) string
- func ModulesDir(version string) string
- func OverrideDir(version string) string
- func PortFor(version string) (int, error)
- func Reload(version string) error
- func Remove(version string) error
- func Running(version string) bool
- func ShimDir(version string) string
- func Stop(version string) error
- func Supported(version string) bool
- func ToolName(version string) string
- func UnitLabel(version string) string
- func WriteOverrides(version string) error
- func XdebugExtensionPath(version string) string
Constants ¶
const MinVersion = "8.1"
MinVersion is the oldest PHP with a native runtime. Below it the toolchain cannot produce a usable binary: static PHP carries no OPcache before 8.0, and 7.4 and 8.0 both fail to compile against the libxml2 and ICU the build uses, which would cost dom, simplexml, soap, xsl and intl even if they linked.
Variables ¶
This section is empty.
Functions ¶
func BinaryPath ¶
BinaryPath is where lerd keeps the native PHP-FPM for a version. Suffixed with the minor because a project's composer.lock was resolved against one, and deliberately not "php": that name in BinDir is the shim into the container, and a static binary written over it would send every php on the machine to a PHP with no lerd behind it.
func DevtoolsExtensionPath ¶
DevtoolsExtensionPath is where a native build's query-capture extension lives when the build ships one. It is the engine-level collector behind the Debug window's query lens, compiled into the PHP image and shipped beside the binary here, the same way xdebug is.
Named per version because a PHP module is built against one PHP's ABI: an 8.4 module will not load into 8.5, and offering it would warn on every request while the lens stayed empty.
func Ensure ¶
Ensure brings a version's native FPM up: config and overrides on disk, the launchd job installed, and the process running. Safe to call repeatedly; an unchanged plist is left alone so a running FPM is not restarted for nothing.
func EnsureInstalled ¶
EnsureInstalled reports whether the native runtime for a version is usable, naming what is missing rather than letting nginx fastcgi into a dead port.
func EnsureShim ¶
EnsureShim points ShimDir's php at the native CLI, replacing a stale link so a version switch or reinstall is picked up.
func EnsureSupported ¶
EnsureSupported rejects a version no native build will ever exist for. A permanent limit is not a missing download, and the two need different words or the reader waits for a build that is never coming.
func Extensions ¶
Extensions reports what a version's native build carries, read from the binary itself so it cannot drift from what is actually installed. The list is the module names PHP prints, which callers should canonicalise before comparing (PHP prints OPcache as "Zend OPcache").
func FPMBinaryPath ¶
FPMBinaryPath is where lerd keeps the native PHP-FPM for a version. Separate from BinaryPath because FPM and CLI are different SAPIs and different builds: FPM serves requests, the CLI runs artisan, composer and tinker.
func FPMConfig ¶
FPMConfig renders the php-fpm.conf for a PHP version's native listener. Pool sizing mirrors the containerised pool so switching a site's runtime doesn't silently change how much concurrency it can absorb. PHP settings are deliberately absent: they come from IniScanDir, the same files the containers mount, so php:ini stays the single place they are edited.
func HostCommand ¶ added in v1.36.0
HostCommand builds the host process that stands in for a podman exec into the FPM container: argv runs in dir with HostPath, so a bare php is lerd's shim and runs the project's native build with its cli_ini.
func HostPath ¶ added in v1.36.0
HostPath is the PATH a command gets on the host under the native runtime: the project's composer binaries first, then lerd's shim dir, which is where php comes from.
func IniScanDir ¶
IniScanDir joins IniScanDirs into the PHP_INI_SCAN_DIR value PHP expects.
func IniScanDirs ¶
IniScanDirs returns the directories a native FPM scans for php.ini fragments, in load order. These are the same files the containers bind-mount into conf.d, so php:ini, dumps, the debug window and xdebug behave identically whichever runtime a site is on. Order matches the containers' numeric conf.d prefixes (94-mail, 95-shared, 96-devtools, 97-dump, then the per-version 98-user and 99-xdebug).
func ListInstalled ¶
func ListInstalled() []string
ListInstalled returns the PHP versions with a usable native runtime on disk, sorted. A version needs both SAPIs: the CLI runs artisan, composer and the workers, and FPM serves requests, so a half-installed version would list as available and then fail at whichever half is missing.
func Loaded ¶
Loaded reports whether a version's pool job is up, without connecting to it. It answers the same question the container runtime answers with "is the container running", and is what a repeated status poll must use: a dial into the FastCGI port is handed to a child, which resets the ondemand idle timer, so polling with Running keeps a pool that should fall to zero alive forever. Running stays the right call for a command a person typed.
func ModulesDir ¶
ModulesDir holds the shared objects a native build ships beside its binary. Per version, because they are named for the extension and not for the PHP they were built against: one directory would leave every version loading whichever xdebug.so was installed last, and a module only loads into the ABI it was compiled for.
func OverrideDir ¶
OverrideDir holds the ini fragment that rewrites container paths to host ones. Scanned last so it wins over the copies the containers share.
func PortFor ¶
PortFor returns the loopback port the native FPM for a PHP version listens on. Derived from the version rather than allocated, so it survives restarts with nothing persisted and stays the same across machines.
func Reload ¶
Reload restarts a version's native FPM so a changed php.ini reaches the processes handling requests. Ensure is deliberately a no-op for a listener that is already up, which is right on start and wrong after an ini edit.
func Remove ¶
Remove uninstalls a version's native build: the pool comes down, then the generated runtime and the files on disk go, so ListInstalled stops reporting a version nothing can serve with.
func Running ¶
Running reports whether a version's pool is accepting connections on its port, which is the same question nginx asks of it before proxying. Cheaper and more honest than asking launchd: a job can be loaded and not yet serving.
func ShimDir ¶
ShimDir holds a "php" symlink to the native CLI for a version. Workers run their command through a shell, so this goes on PATH ahead of BinDir, whose own "php" is the shim into the container. Without it a native site's workers would keep running containerised while its web requests did not.
func ToolName ¶
ToolName is the manifest entry and version-stamp name for a version's host build. Shared so the CLI that installs it and the dashboard that reports on it cannot disagree about what the stamp beside the binary is called.
func WriteOverrides ¶
WriteOverrides materialises the override fragment for a version.
func XdebugExtensionPath ¶
XdebugExtensionPath is the xdebug.so a native build ships, or "" when it did not ship one. Xdebug is a zend_extension, so it loads by path from the ini rather than from an image package the way the container runtime gets it.
Types ¶
This section is empty.
Source Files