PHPX build fails with PHP 8.5.9 Docker image

[cxlblm]

PHPX build fails with PHP 8.5.9 Docker image; official TypePHP image request

When using TypePHP v0.6.6 / PHPX v2.6.8 with the official
php:8.5-cli Docker image (PHP 8.5.9), PHPX fails to compile:

In file included from /usr/local/include/php/Zend/zend.h:30,
                 from /usr/local/include/php/main/php.h:31,
                 from /app/vendor/swoole/phpx/include/std/misc.h:13,
                 from /app/vendor/swoole/phpx/src/std/misc.cc:10:
/usr/local/include/php/ext/hash/php_hash.h: In function 'void* php_hash_alloc_context(const php_hash_ops*)':
/usr/local/include/php/Zend/zend_alloc.h:158:65: error: invalid conversion from 'void*' to 'char*' [-fpermissive]
  158 | #define ecalloc(nmemb, size)                            _ecalloc((nmemb), (size) ZEND_FILE_LINE_CC ZEND_FILE_LINE_EMPTY_CC)
      |                                                         ~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      |                                                                 |
      |                                                                 void*
/usr/local/include/php/ext/hash/php_hash.h:169:30: note: in expansion of macro 'ecalloc'
  169 |                 char *base = ecalloc(1, ops->context_size + align);
      |                              ^~~~~~~
[ 86%] Building CXX object CMakeFiles/phpx.dir/src/typephp/typephp_attribute.cc.o
[ 88%] Building CXX object CMakeFiles/phpx.dir/src/typephp/typephp_fiber_generator.cc.o
[ 90%] Building CXX object CMakeFiles/phpx.dir/src/typephp/typephp_property.cc.o
[ 92%] Building CXX object CMakeFiles/phpx.dir/src/func/core.cc.o
gmake[3]: *** [CMakeFiles/phpx.dir/build.make:387: CMakeFiles/phpx.dir/src/std/misc.cc.o] Error 1
gmake[3]: *** Waiting for unfinished jobs....
gmake[2]: *** [CMakeFiles/Makefile2:161: CMakeFiles/phpx.dir/all] Error 2
gmake[1]: *** [CMakeFiles/Makefile2:168: CMakeFiles/phpx.dir/rule] Error 2
gmake: *** [Makefile:195: phpx] Error 2
Fatal error: Unable to build libphpx.so: Command failed: cmake --build /app/vendor/swoole/phpx/build --parallel 8 --target phpx
#0 /app/vendor/swoole/typephp/src/Diagnostics/CompilerDiagnosticTrait.php(22): TypePhp\Diagnostics\CliDiagnosticReporter->fatal('Unable to build...')
#1 /app/vendor/swoole/typephp/src/Build/SourcePipelineTrait.php(99): TypePhp\CompilerBase->error('Unable to build...')
#2 /app/vendor/swoole/typephp/src/compiler.php(61): TypePhp\Translator->prepare('src/main.php')
#3 /app/vendor/swoole/typephp/bin/tpc.php(9): main(2, Array)
#4 /app/vendor/bin/tpc.php(119): include('/app/vendor/swo...')

Could you please confirm whether TypePHP/PHPX currently supports the official
PHP 8.5 Docker image?

Also, would the TypePHP project consider publishing an official Docker image
with a tested PHP version, Composer, PHPX, the required build dependencies,
and AMD64/ARM64 support? This would make TypePHP installation and builds much
more reproducible.

[NathanFreeman]

Please try upgrading the PHP version. This issue is caused by a minor version update that introduced header files incompatible with C++.

[NathanFreeman]

php/php-src#22940

[cxlblm]

Please try upgrading the PHP version. This issue is caused by a minor version update that introduced header files incompatible with C++.

After downgrading PHP to 8.5.8, PHPX and the TypePHP program compile successfully. However, running the generated binary still fails because libphpx.so cannot be found.

Build and execution log

root@8eb4facd6c33:/app# ./vendor/bin/tpc.php ./main.php

Initialized platform/backend: Linux + GCC (g++)
The PHPX installation does not provide libphpx.so: /app/vendor/swoole/phpx
Build libphpx.so now? [Y/n] y
Detected package manager: apt-get
All detected PHPX build dependencies are already installed.

$ 'cmake' '-S' '/app/vendor/swoole/phpx' '-B' '/app/vendor/swoole/phpx/build' '-DCMAKE_BUILD_TYPE=Release' '-DBUILD_TESTS=OFF' '-Dphp_dir=/usr/local'

-- The C compiler identification is GNU 14.2.0
-- The CXX compiler identification is GNU 14.2.0
-- Detecting C compiler ABI info - done
-- Detecting C compile features - done
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features - done
-- Building in Release mode
-- Facade API disabled (src/class, src/func, src/const excluded)
-- PHP_PREFIX: /usr/local
-- PHP_INCLUDES: -I/usr/local/include/php -I/usr/local/include/php/main -I/usr/local/include/php/TSRM -I/usr/local/include/php/Zend -I/usr/local/include/php/ext -I/usr/local/include/php/ext/date/lib
-- PHP_LIBS: -lreadline -lncurses -lm -lxml2 -lssl -lcrypto -lsqlite3 -lz -lcurl -lxml2 -lonig -lsqlite3 -lxml2 -largon2 -lrt -ldl -lxml2 -lxml2 -lxml2 -lz -lssl -lcrypto
-- PHP_LDFLAGS: -Wl,-O1 -pie
-- Using bundled mpdecimal with uint128
-- =================================
-- Build Configuration Summary
-- =================================
-- Platform: Linux
-- Build Type: Release
-- C++ Standard: 17
-- PHP Prefix: /usr/local
-- Build Tests: OFF
-- Build Extension: ON
-- GitHub Action: OFF
-- Facade API: OFF
-- =================================
-- Configuring done
-- Generating done
-- Build files have been written to: /app/vendor/swoole/phpx/build

$ 'cmake' '--build' '/app/vendor/swoole/phpx/build' '--parallel' '8' '--target' 'phpx'

[  1%] Building C object CMakeFiles/wren_gc.dir/thirdparty/wren-gc/src/wren_gc.c.o
[  3%] Building C object CMakeFiles/mpdecimal.dir/thirdparty/mpdecimal/libmpdec/basearith.c.o
[ 23%] Linking C static library /app/vendor/swoole/phpx/lib/libwren_gc.a
[ 25%] Built target wren_gc
[ 37%] Linking CXX static library /app/vendor/swoole/phpx/lib/libmpdecimal.a
[ 37%] Built target mpdecimal
[ 39%] Building CXX object CMakeFiles/phpx.dir/src/core/array.cc.o
[ 43%] Building CXX object CMakeFiles/phpx.dir/src/core/big_int.cc.o
[ 45%] Building CXX object CMakeFiles/phpx.dir/src/core/big_float.cc.o
[ 47%] Building CXX object CMakeFiles/phpx.dir/src/core/closure.cc.o
[ 49%] Building CXX object CMakeFiles/phpx.dir/src/core/extension.cc.o
[ 50%] Building CXX object CMakeFiles/phpx.dir/src/core/decimal.cc.o
[ 52%] Building CXX object CMakeFiles/phpx.dir/src/core/class.cc.o
[ 54%] Building CXX object CMakeFiles/phpx.dir/src/core/foreach_iterator.cc.o
[ 56%] Building CXX object CMakeFiles/phpx.dir/src/core/literal_string.cc.o
[ 58%] Building CXX object CMakeFiles/phpx.dir/src/core/native_gc.cc.o
[ 60%] Building CXX object CMakeFiles/phpx.dir/src/core/object.cc.o
[ 62%] Building CXX object CMakeFiles/phpx.dir/src/core/python_bridge.cc.o
[ 64%] Building CXX object CMakeFiles/phpx.dir/src/core/scope.cc.o
[ 66%] Building CXX object CMakeFiles/phpx.dir/src/core/string.cc.o
[ 68%] Building CXX object CMakeFiles/phpx.dir/src/core/type_check.cc.o
[ 70%] Building CXX object CMakeFiles/phpx.dir/src/core/variant.cc.o
[ 72%] Building CXX object CMakeFiles/phpx.dir/src/std/array.cc.o
[ 74%] Building CXX object CMakeFiles/phpx.dir/src/std/core.cc.o
[ 76%] Building CXX object CMakeFiles/phpx.dir/src/std/datetime.cc.o
[ 78%] Building CXX object CMakeFiles/phpx.dir/src/std/fs.cc.o
[ 80%] Building CXX object CMakeFiles/phpx.dir/src/std/misc.cc.o
[ 82%] Building CXX object CMakeFiles/phpx.dir/src/std/math.cc.o
[ 84%] Building CXX object CMakeFiles/phpx.dir/src/std/string.cc.o
[ 86%] Building CXX object CMakeFiles/phpx.dir/src/typephp/typephp_attribute.cc.o
[ 88%] Building CXX object CMakeFiles/phpx.dir/src/typephp/typephp_fiber_generator.cc.o
[ 90%] Building CXX object CMakeFiles/phpx.dir/src/typephp/typephp_property.cc.o
[ 92%] Building CXX object CMakeFiles/phpx.dir/src/func/core.cc.o
[ 94%] Building CXX object CMakeFiles/phpx.dir/src/func/standard.cc.o
[ 96%] Building CXX object CMakeFiles/phpx.dir/src/func/json.cc.o
[ 98%] Building CXX object CMakeFiles/phpx.dir/src/func/random.cc.o
[100%] Linking CXX shared library /app/vendor/swoole/phpx/lib/libphpx.so
[100%] Built target phpx

libphpx.so built successfully in /app/vendor/swoole/phpx/lib

prepare: main.php
prepare completed: 1 source files in total
convert: main.php
generate arginfo file: main.php
[pch] built: vendor/swoole/typephp/build/cache/pch/e23adc3453736a988e1ad61c/typephp_pch.hpp.gch
pcntl extension not available, using sequential compilation
Starting compilation for 6 files
Successfully compiled 6 files

g++ '@./main.rsp' -o 'main' -L'/app/vendor/swoole/phpx/lib' -L'/usr/local/lib' -lphpx -lphp -lgmp -lgmpxx -lmpfr

Build successful: main

root@8eb4facd6c33:/app# ./main

./main: error while loading shared libraries: libphpx.so: cannot open shared object file: No such file or directory

[GleisonOliveira]

Please try upgrading the PHP version. This issue is caused by a minor version update that introduced header files incompatible with C++.

After downgrading PHP to 8.5.8, PHPX and the TypePHP program compile successfully. However, running the generated binary still fails because libphpx.so cannot be found.

Build and execution log

root@8eb4facd6c33:/app# ./vendor/bin/tpc.php ./main.php

Initialized platform/backend: Linux + GCC (g++)
The PHPX installation does not provide libphpx.so: /app/vendor/swoole/phpx
Build libphpx.so now? [Y/n] y
Detected package manager: apt-get
All detected PHPX build dependencies are already installed.

$ 'cmake' '-S' '/app/vendor/swoole/phpx' '-B' '/app/vendor/swoole/phpx/build' '-DCMAKE_BUILD_TYPE=Release' '-DBUILD_TESTS=OFF' '-Dphp_dir=/usr/local'

-- The C compiler identification is GNU 14.2.0
-- The CXX compiler identification is GNU 14.2.0
-- Detecting C compiler ABI info - done
-- Detecting C compile features - done
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features - done
-- Building in Release mode
-- Facade API disabled (src/class, src/func, src/const excluded)
-- PHP_PREFIX: /usr/local
-- PHP_INCLUDES: -I/usr/local/include/php -I/usr/local/include/php/main -I/usr/local/include/php/TSRM -I/usr/local/include/php/Zend -I/usr/local/include/php/ext -I/usr/local/include/php/ext/date/lib
-- PHP_LIBS: -lreadline -lncurses -lm -lxml2 -lssl -lcrypto -lsqlite3 -lz -lcurl -lxml2 -lonig -lsqlite3 -lxml2 -largon2 -lrt -ldl -lxml2 -lxml2 -lxml2 -lz -lssl -lcrypto
-- PHP_LDFLAGS: -Wl,-O1 -pie
-- Using bundled mpdecimal with uint128
-- =================================
-- Build Configuration Summary
-- =================================
-- Platform: Linux
-- Build Type: Release
-- C++ Standard: 17
-- PHP Prefix: /usr/local
-- Build Tests: OFF
-- Build Extension: ON
-- GitHub Action: OFF
-- Facade API: OFF
-- =================================
-- Configuring done
-- Generating done
-- Build files have been written to: /app/vendor/swoole/phpx/build

$ 'cmake' '--build' '/app/vendor/swoole/phpx/build' '--parallel' '8' '--target' 'phpx'

[  1%] Building C object CMakeFiles/wren_gc.dir/thirdparty/wren-gc/src/wren_gc.c.o
[  3%] Building C object CMakeFiles/mpdecimal.dir/thirdparty/mpdecimal/libmpdec/basearith.c.o
[ 23%] Linking C static library /app/vendor/swoole/phpx/lib/libwren_gc.a
[ 25%] Built target wren_gc
[ 37%] Linking CXX static library /app/vendor/swoole/phpx/lib/libmpdecimal.a
[ 37%] Built target mpdecimal
[ 39%] Building CXX object CMakeFiles/phpx.dir/src/core/array.cc.o
[ 43%] Building CXX object CMakeFiles/phpx.dir/src/core/big_int.cc.o
[ 45%] Building CXX object CMakeFiles/phpx.dir/src/core/big_float.cc.o
[ 47%] Building CXX object CMakeFiles/phpx.dir/src/core/closure.cc.o
[ 49%] Building CXX object CMakeFiles/phpx.dir/src/core/extension.cc.o
[ 50%] Building CXX object CMakeFiles/phpx.dir/src/core/decimal.cc.o
[ 52%] Building CXX object CMakeFiles/phpx.dir/src/core/class.cc.o
[ 54%] Building CXX object CMakeFiles/phpx.dir/src/core/foreach_iterator.cc.o
[ 56%] Building CXX object CMakeFiles/phpx.dir/src/core/literal_string.cc.o
[ 58%] Building CXX object CMakeFiles/phpx.dir/src/core/native_gc.cc.o
[ 60%] Building CXX object CMakeFiles/phpx.dir/src/core/object.cc.o
[ 62%] Building CXX object CMakeFiles/phpx.dir/src/core/python_bridge.cc.o
[ 64%] Building CXX object CMakeFiles/phpx.dir/src/core/scope.cc.o
[ 66%] Building CXX object CMakeFiles/phpx.dir/src/core/string.cc.o
[ 68%] Building CXX object CMakeFiles/phpx.dir/src/core/type_check.cc.o
[ 70%] Building CXX object CMakeFiles/phpx.dir/src/core/variant.cc.o
[ 72%] Building CXX object CMakeFiles/phpx.dir/src/std/array.cc.o
[ 74%] Building CXX object CMakeFiles/phpx.dir/src/std/core.cc.o
[ 76%] Building CXX object CMakeFiles/phpx.dir/src/std/datetime.cc.o
[ 78%] Building CXX object CMakeFiles/phpx.dir/src/std/fs.cc.o
[ 80%] Building CXX object CMakeFiles/phpx.dir/src/std/misc.cc.o
[ 82%] Building CXX object CMakeFiles/phpx.dir/src/std/math.cc.o
[ 84%] Building CXX object CMakeFiles/phpx.dir/src/std/string.cc.o
[ 86%] Building CXX object CMakeFiles/phpx.dir/src/typephp/typephp_attribute.cc.o
[ 88%] Building CXX object CMakeFiles/phpx.dir/src/typephp/typephp_fiber_generator.cc.o
[ 90%] Building CXX object CMakeFiles/phpx.dir/src/typephp/typephp_property.cc.o
[ 92%] Building CXX object CMakeFiles/phpx.dir/src/func/core.cc.o
[ 94%] Building CXX object CMakeFiles/phpx.dir/src/func/standard.cc.o
[ 96%] Building CXX object CMakeFiles/phpx.dir/src/func/json.cc.o
[ 98%] Building CXX object CMakeFiles/phpx.dir/src/func/random.cc.o
[100%] Linking CXX shared library /app/vendor/swoole/phpx/lib/libphpx.so
[100%] Built target phpx

libphpx.so built successfully in /app/vendor/swoole/phpx/lib

prepare: main.php
prepare completed: 1 source files in total
convert: main.php
generate arginfo file: main.php
[pch] built: vendor/swoole/typephp/build/cache/pch/e23adc3453736a988e1ad61c/typephp_pch.hpp.gch
pcntl extension not available, using sequential compilation
Starting compilation for 6 files
Successfully compiled 6 files

g++ '@./main.rsp' -o 'main' -L'/app/vendor/swoole/phpx/lib' -L'/usr/local/lib' -lphpx -lphp -lgmp -lgmpxx -lmpfr

Build successful: main

root@8eb4facd6c33:/app# ./main

./main: error while loading shared libraries: libphpx.so: cannot open shared object file: No such file or directory

I believe this is different from Go.

According to the [TypePHP best practices documentation](https://swoole.com/aot/en/docs/best_practice), TypePHP uses dynamic linking to reduce the binary size, so the compiled application depends on the operating system's .so libraries.

The documentation states that:

• The operating system and its base libraries should remain consistent between the build and deployment environments.
• libphp.so and libphpx.so should be built on the build machine and included in the final package.
• PHP extensions are compiled statically into PHP rather than being dynamically loaded.
• The final package should contain the compiled binary, libphp.so, libphpx.so, and the vendor/ directory.

Therefore, unlike a typical statically linked Go binary, the TypePHP executable is not intended to be completely self-contained. The deployment environment is expected to provide compatible system libraries, while the PHP/TypePHP-specific libraries are distributed alongside the executable.

However, I think the documentation could be improved by providing a concrete example of how to build and package an application for distribution following these rules. For example, a complete example showing the build environment, which files need to be included in the final package, and how to deploy and run the resulting application on another machine would make this behavior much clearer.

So I don't think the two cases are directly comparable, but a practical deployment example in the documentation would be very helpful.

So I don't think the two cases are directly comparable.

[matyhtf]

Hi @cxlblm,

1. libphpx.so: cannot open shared object file

This is a runtime library lookup problem, not a build problem.

At link time, -L/app/vendor/swoole/phpx/lib only tells the linker where to find libphpx.so; it has no effect at runtime. On Linux the produced binary carries no RPATH, so the dynamic loader only searches the standard paths — and /app/vendor/... is not among them. (On macOS the phpx lib directory is added as a default rpath, which is why this only shows up on Linux.)

Diagnose it:

$ ldd ./main | grep libphpx
	libphpx.so => not found

libphp.so is usually found fine here, because official images put it in /usr/local/lib, which is a standard path.

Fix — register the directory with the dynamic linker:

# 1. write the config file (use the path where your phpx is installed)
echo "/app/vendor/swoole/phpx/lib" | sudo tee /etc/ld.so.conf.d/typephp.conf

# 2. rebuild the linker cache
sudo ldconfig

# 3. confirm
ldconfig -p | grep libphpx
# 	libphpx.so (libc6,x86-64) => /app/vendor/swoole/phpx/lib/libphpx.so

ldd ./main | grep libphpx    # now resolves

/etc/ld.so.conf.d/*.conf is the conventional place for this: each file simply lists library directories, one per line, and ldconfig merges them all into /etc/ld.so.cache. Keeping it in a dedicated file rather than editing /etc/ld.so.conf directly makes it easy to remove later.

If you do not have root access, LD_LIBRARY_PATH works for the current shell:

LD_LIBRARY_PATH=/app/vendor/swoole/phpx/lib ./main

Add that export to ~/.bashrc to make it persistent for one user.

You can verify the fix matters by removing the config file again — the error comes straight back:

rm /etc/ld.so.conf.d/typephp.conf && ldconfig && ./main
# ./main: error while loading shared libraries: libphpx.so: cannot open shared object file

2. On the PHP version: you don't have to stay on 8.5.8

The php_hash.h failure is an upstream C++ compatibility bug, fixed in php-src PR #22940 ("Make php_hash.h includable from C++ code", merged 2026-07-30 into PHP-8.4).

The header differs between the two tags:

Version	php_hash.h line 169
8.5.9	char *base = ecalloc(1, ops->context_size + align); — broken
8.5.10	char *base = (char *) ecalloc(1, ops->context_size + align); — fixed

So 8.5.10 (released 2026-08-25) and later are fine. 8.5.9 was simply released two days before the fix landed.

Until the official Docker image catches up, you can apply the same one-line change yourself. It is exactly what upstream did, and it is a no-op on versions that already contain the fix (no match, no substitution), so it is safe to keep unconditionally:

sed -i "s/char [*]base = ecalloc(/char *base = (char *) ecalloc(/" \
    /usr/local/include/php/ext/hash/php_hash.h

3. A working Dockerfile

Tested with php:8.5-cli (i.e. 8.5.9), TypePHP v0.6.8 / PHPX v2.6.9:

FROM php:8.5-cli

# 1. Fix php_hash.h C++ compatibility (no-op on versions that already have it)
RUN sed -i "s/char [*]base = ecalloc(/char *base = (char *) ecalloc(/" \
        /usr/local/include/php/ext/hash/php_hash.h

# 2. Build deps. gmp -> bigInt, mpfr -> bigFloat (libmpdec for decimal is bundled).
#    unzip is required by Composer and missing from the official image.
RUN apt-get update && apt-get install -y --no-install-recommends \
        build-essential \
        cmake \
        pkg-config \
        libgmp-dev \
        libmpfr-dev \
        unzip \
    && rm -rf /var/lib/apt/lists/*

COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

WORKDIR /app

# 3. swoole/phpx is installed together with swoole/typephp
COPY composer.json ./
RUN composer install --no-interaction

# 4. Build libphpx.so explicitly: tpc.php only auto-builds interactively
#    (it waits for a Y/n prompt), so CI/Docker must call cmake directly.
#    The PHP prefix of the official image is /usr/local.
ENV PHP_HOME=/usr/local
ENV PHPX_HOME=/app/vendor/swoole/phpx
RUN cmake -S "$PHPX_HOME" -B "$PHPX_HOME/build" \
        -DCMAKE_BUILD_TYPE=Release \
        -DBUILD_TESTS=OFF \
        -Dphp_dir="$PHP_HOME" \
    && cmake --build "$PHPX_HOME/build" --parallel 4 --target phpx

# 5. Compile (the -o directory must exist)
COPY . .
RUN mkdir -p /app/bin \
    && ./vendor/bin/tpc.php project.yml -O2 -o /app/bin/app --no-progress

# 6. Register libphpx.so with the dynamic linker (see section 1)
RUN echo "/app/vendor/swoole/phpx/lib" > /etc/ld.so.conf.d/typephp.conf \
    && ldconfig

# 7. Confirm
RUN ldconfig -p | grep libphpx

CMD ["/app/bin/app"]

Three steps are easy to miss: unzip for Composer, the explicit CMake build of PHPX (step 4), and the ldconfig registration (step 6).

On the official Docker image: we will provide one.