The same build args work with `Dockerfile.litespeed`. Without
`PHP_SRC_VERSION`, both Dockerfiles build exactly as before: the `lsphp-src`
stage and the overlay steps do nothing.
## What the build does and what makes it fail
The build has four parts.
1. The `lsphp-src` stage runs `scripts/lsphp-src-build.sh`, FROM the same
`litespeedtech/openlitespeed` base as the shipped image.
2. In `Dockerfile.lsphp`, the ext-build stage runs `scripts/lsphp-src-overlay.sh dev`.
This builds `cac_path_parity` and runs its `.phpt` suite against the php.net
PHP.
3. The shipped stage runs `scripts/lsphp-src-overlay.sh runtime`.
4. The labels record the source: `org.whp.php-version` is the php.net version
and `org.whp.lsphp-source` is `php.net`. `org.whp.lsphp-package-version`
still names the LiteSpeed packages underneath.
Each of the following fails the build:
| Check | Fails when |
|---|---|
| Tarball sha256 | It does not match `PHP_SRC_SHA256`, which CI takes from the php.net releases JSON. |
| OpenPGP signature | `gpgv` rejects the `.asc` against `keys/php-src/php-keyring.asc`, or the signer's primary fingerprint is not listed for that branch in `keys/php-src/release-managers.txt`. |
| Version sanity | The version is not X.Y.Z, is not in the PHPVER branch, or is not newer than the packaged version. |
| Configure | Replaying the packaged lsphp's own `Configure Command` fails. The usual cause is a `-dev` package missing from `DEVPKGS`. |
| LSAPI SAPI | `php-litespeed-8.4.tgz` (pinned 2026-11-19; was 8.3) does not match its pinned sha256, or the built lsphp's set of `LSAPI_*` names differs from the packaged binary's. |
| Compiled-in ini defaults | Any `php -n` ini default differs from the packaged binary. Directives that are new in the release are allowed and printed. |
| ABI gate | A struct member's offset or size changed, or a non-`*_globals` struct changed size. See `scripts/lsphp-abi-gate.sh`. |
| File replacement | A php-src ELF file owned by a package at the core version has no php.net counterpart. |
| Same-support gate (both SAPIs) | Loaded extensions differ, a PECL or Zend extension changes version, a php-src extension is not at the new version, an effective ini value changes or disappears, or a gd/curl/openssl/icu/imagick/redis/memcached/password/hash/stream feature line changes. |
| Build-env consistency | `Configure Command` differs beyond CFLAGS, an ELF file has an unresolved library, or the packaged release in the builder stage differs from the one in the shipped stage. |
## Differences from the packaged build
These were measured on 2026-10-21 for php85 and php82 (`cac-lsphp`) and php83
(`cac-litespeed`):
- Version strings, build date and build host.
-`memory_hard_limit_percent` exists. The php2shell release added this ini
directive.
- The bundled Olson timezone DB is 2026.5 instead of 2026.3 for 8.5. It comes
from the newer tarball.
- LDAP "Vendor Version" is 20610 instead of 20607. This is the version of the
OpenLDAP headers it was compiled against; noble's libldap-dev is newer now.
The runtime library is the same Ubuntu libldap.
- CFLAGS has no `-ffile-prefix-map` or `-fdebug-prefix-map` pointing at
LiteSpeed's build directory.
- One more `_chk` (FORTIFY) symbol is used. Shared extensions get BIND_NOW,
which is stricter than the packaged build.
- The image is about 100 MB larger. The overlay layer holds a second copy of
lsphp, php and php8.M.
## Maintenance: what must stay in sync
| Item | When it needs attention | How you find out |
|---|---|---|
| `keys/php-src/release-managers.txt` and `php-keyring.asc` | A new release manager, or a new PHP branch (8.6). | The build fails because the signer is not pinned or there is no key. Refresh from <https://www.php.net/gpg-keys.php> and <https://www.php.net/distributions/php-keyring.gpg>. |
| `keys/php-src/litespeed-sapi.txt` | LiteSpeed publishes a new php-litespeed release and builds lsphp with it. | The build fails on the sha256 mismatch or on the LSAPI name-set difference. Re-measure the packaged binary, then re-pin. |
| `DEVPKGS` in `lsphp-src-build.sh` | LiteSpeed adds a configure flag that needs a new `-dev` library. | configure fails and prints the error. |
| session.save_path patch (step 2c) | LiteSpeed patches some other compiled-in default. | The compiled-in ini defaults check fails and shows a diff. |
| PECL reuse | A PHP patch release changes a struct layout. | The ABI gate fails. PECL extensions would then have to be rebuilt from source, which this path does not do. Without that, the emergency path cannot be used for that release. |
| 8.1 | php.net no longer publishes 8.1 (EOL). | The workflow refuses because there is no release. |
No configure flags, extension lists or PECL versions are kept in this repo.
They are read from the packaged lsphp in the same build, so they cannot go out