SpawnWP — PHP ftp/FTPS extension missing from site images

[wpeasy]

Summary
WordPress sites on a SpawnWP host cannot perform outbound FTP or FTPS transfers. Plugins/core report "ftp and ftps are not available." The cause is that the PHP image built by SpawnWP (docker/php/Dockerfile) does not include the PHP ftp extension, and enabling it fully on PHP 8.4 requires two extra steps beyond a simple docker-php-ext-install ftp. We've patched our own host as a stopgap; this should be fixed in the SpawnWP base image so all sites get it.

Environment
SpawnWP release 0.5.14 (also observed on 0.5.7-era site stacks)
PHP image base: wordpress:php8.4-fpm (Debian 13)
Affected file: runtime/docker/php/Dockerfile (and the per-site copies under /srv//docker/php/Dockerfile)
The problem, in three layers
Each was only revealed after fixing the previous one:

ftp extension not installed. The image's docker-php-ext-install list has intl zip exif bcmath (+ gd, imagick, redis) but no ftp. Result: ftp_connect() undefined → "ftp not available".
FTPS needs OpenSSL dev headers at build time. After adding ftp, plain FTP worked but FTPS did not (ftp_ssl_connect undefined, php --ri ftp showed FTPS support => disabled). The base image ships the OpenSSL runtime but not libssl-dev, so ext/ftp compiled without SSL.
PHP 8.4 made FTPS an explicit opt-in. Even with libssl-dev present, FTPS was still disabled. On PHP 8.4, ext/ftp's --with-ftp-ssl is only implicit when the extension is built as part of PHP's main ./configure --with-openssl. Because docker-php-ext-install builds each extension standalone via phpize, that implicit path doesn't apply, and configure reports "whether to enable FTP over SSL support... no". It must be passed explicitly.
Confirmed via the ext's own configure help:

--with-ftp-ssl — Explicitly enable FTP over SSL support when building without openssl extension or when using phpize. If the openssl extension is enabled at the configure step (--with-openssl), FTP-SSL is enabled implicitly.

The fix (what we applied)
In docker/php/Dockerfile, add libssl-dev to the apt list, pre-configure ftp with --with-ftp-ssl, and add ftp (plus other commonly-needed extensions) to the install list:

RUN apt-get update && apt-get install -y --no-install-recommends
libicu-dev
libmagickwand-dev
libwebp-dev
libzip-dev
libexif-dev
unzip
less
mariadb-client
libgmp-dev \ # for gmp
libxml2-dev \ # for soap
libssl-dev \ # for ftp (FTPS)
&& docker-php-ext-configure ftp --with-ftp-ssl \ # <-- REQUIRED on PHP 8.4 for FTPS
&& docker-php-ext-install
intl
zip
exif
bcmath
ftp
soap
sockets
pcntl
gmp
pdo_mysql
calendar
&& docker-php-ext-configure gd --with-jpeg --with-webp
&& docker-php-ext-install gd
&& pecl install imagick redis
&& docker-php-ext-enable imagick redis
&& apt-get clean && rm -rf /var/lib/apt/lists/*
Why the ordering works: docker-php-ext-install's per-ext loop runs [ -e Makefile ] || docker-php-ext-configure "$ext" — i.e. it only auto-configures (with no args) if a Makefile doesn't already exist. Running docker-php-ext-configure ftp --with-ftp-ssl first creates that Makefile, so the batch install honors the SSL-enabled config instead of reconfiguring. (Same mechanism as the existing gd --with-jpeg.)

Verified result
php --ri ftp → FTP support => enabled
FTPS support => enabled
ftp_connect → OK
ftp_ssl_connect → OK
Extra extensions we bundled (optional, but recommended for a WP platform)
Alongside ftp we added soap (payment/shipping/ERP integrations), sockets, pcntl (WP-CLI background jobs), gmp (JWT/crypto/licensing plugins), pdo_mysql (currently only pdo_sqlite is present — plugins using PDO MySQL fail), and calendar. You may want to standardize on whichever of these fit your target audience. Note: imap is not installable this way on PHP 8.4 (removed from core).

What we need from SpawnWP
Add ftp to the base image with libssl-dev + docker-php-ext-configure ftp --with-ftp-ssl so FTPS works out of the box on PHP 8.4 (and verify on 8.1/8.2/8.3 images too).
Consider adding the other common extensions above (at minimum pdo_mysql and soap).
Ship this in the release template so newly spawned sites inherit it automatically.
Why this matters for us / heads-up
We patched the 0.5.14 release template on our host directly, but a future spawnwp update will overwrite it, so new sites created after an update would silently lose FTP/FTPS again until this is fixed upstream. A base-image fix is the durable solution.

[tts-empire]

Fixed and shipped in SpawnWP 0.5.18 — thank you, this was an excellent report.

Your three-layer diagnosis was spot on, and I reproduced every layer. The docker-php-ext-install mechanism you identified is exactly right — line 107 of that script is literally [ -e Makefile ] || docker-php-ext-configure "$ext", so pre-configuring ftp makes the batch install honour the SSL-enabled config.

And your pdo_mysql catch was the one I most expected to be wrong — it wasn't. The image really did have only pdo_sqlite. WordPress never noticed because it uses mysqli, and that's precisely why the gap survived this long. Good spot.

One important heads-up for your own host

SpawnWP builds four PHP images (7.4, 8.2, 8.3, 8.4), and your patch as written only works on 8.4. On the other three, docker-php-ext-configure ftp --with-ftp-ssl fails outright:

configure: error: unrecognized options: --with-ftp-ssl

The reason is in ext/ftp/config.m4: the option was renamed in 8.4. Up to 8.3 it's spelled --with-openssl-dir — the source even carries a dnl TODO: Rename this option for master comment. Since the Dockerfile chains everything with &&, a failed configure aborts the whole image build. You'd only hit this the moment you build anything other than 8.4.

The full matrix, all verified by building the real images:

PHP	flag that works	FTPS
7.4	--with-openssl-dir	✅
8.2	--with-openssl-dir	✅
8.3	--with-openssl-dir	✅
8.4	--with-ftp-ssl	✅

Worth noting how differently they behave: on 7.4, FTPS turns on by itself once libssl-dev is present. On 8.2 and 8.3 — the versions nobody had tested — it's the worst case: the flag is rejected and FTPS stays off without it. Three different behaviours across four versions, none of them guessable without building each one.

So the image now picks the flag by version:

&& if [ "$(printf '%s\n8.4\n' "$PHP_VERSION" | sort -V | head -1)" = "8.4" ]; then \
       docker-php-ext-configure ftp --with-ftp-ssl; \
   else \
       docker-php-ext-configure ftp --with-openssl-dir; \
   fi \

(sort -V rather than a hardcoded = "8.4", so a future 8.5 doesn't quietly fall into the wrong branch.)

Result: FTPS is enabled on all four versions — ftp_connect() and ftp_ssl_connect() both work, and php --ri ftp reports FTPS support => enabled everywhere.

Extensions added, your full list: ftp, pdo_mysql, soap, sockets, pcntl, gmp, calendar (plus libssl-dev, libxml2-dev, libgmp-dev as build deps). Image size is essentially unchanged. I also added installer/tests/php-image.sh, which asserts the whole extension set and that FTPS is on — so a future refactor can't silently drop it again.

What to do on your host

1. sudo spawnwp update to 0.5.18, and drop your local patch — it will be overwritten anyway, and as above it would break your build the day you spin up a non-8.4 image.
2. New sites get all of this automatically.
3. Existing sites don't — they keep running their current container. To bring one up to date: rebuild its PHP image (System → refresh PHP images, or SPAWNWP_REBUILD=1), then Down/Up the site.
4. The first deploy on each PHP version after updating pays a one-off ~5-minute image rebuild (the cockpit announces it while it happens), because the build context hash changed for all four.

Thanks again — genuinely. You did the hard part.

[wpeasy]

Thanks man. Looking good.

I have to be honest. I'm not that highly experienced with Linux. Claude did the hard work and even wrote the request :)

[tts-empire]

Follow-up: your report turned up a second, older bug — Xdebug

Worth flagging for anyone else reading this thread.

While writing up the PHP extension list (something this whole episode convinced me was overdue), I checked php -m against the real image instead of trusting our own docs. Xdebug wasn't there. It never had been — pecl install xdebug appears in no commit in the project's history.

The image only ever copied an xdebug.ini, and make xdebug-on uncommented a zend_extension=xdebug line pointing at a module that didn't exist:

PHP Warning: Failed loading Zend extension 'xdebug' (... cannot open shared object file ...)

So step-debugging has been silently broken since the very first release, while the docs and the CLI happily advertised it.

Fixed in 0.5.19. Xdebug is now installed on every PHP version and still disabled by default — it costs nothing until you run make xdebug-on. (PHP 7.4 pins Xdebug 3.1.6, the last release that supports it; 8.2/8.3/8.4 get 3.5.x. Another per-version trap, just like the FTPS flag.)

0.5.19 also publishes the full PHP extensions list, with a CI check that reads the extensions straight from the image's Dockerfile — so the page can't quietly go stale the way this one did.

Same deal as the FTP fix: new sites get it automatically, existing sites need an image rebuild (System → refresh PHP images) and a Down/Up.

Two real bugs out of one report. Thanks again.