marekskopal/php-v8js repository overview

⁠php-v8js

PHP 8.4 and 8.5 images with the phpv8/v8js⁠ extension (Google's V8 JavaScript engine embedded in PHP) and Composer 2, built on the official php⁠ images.

• Multi-arch: linux/amd64 + linux/arm64 (incl. Apple Silicon via Docker Desktop)
• Variants: cli, fpm, apache, and thread-safe zts
• OS: Debian trixie and Alpine
• Tested at build time: every image runs a smoke test (new V8Js(), script execution, JS↔PHP marshalling, exception propagation), so a broken extension fails the build, not your deploy
• Rebuilt monthly to pick up upstream PHP and OS security updates

Source, Dockerfiles and build docs: https://github.com/marekskopal/php-v8js-docker⁠

⁠Supported tags

Tag shorthands follow the official php image convention: bare <php> and <php>-<variant> point to the Debian/trixie variant. There is no apache-alpine variant, because the upstream php image doesn't provide one.

⁠Quick start

docker pull marekskopal/php-v8js:latest

docker run --rm marekskopal/php-v8js:latest \
  php -r 'echo (new V8Js)->executeString("1+2"), PHP_EOL;'

PHP-FPM (Docker Compose)

services:
  php:
    image: marekskopal/php-v8js:8.5-fpm
    volumes:
      - ./app:/var/www/html

Apache

docker run --rm -p 8080:80 -v "$PWD/app":/var/www/html \
  marekskopal/php-v8js:8.5-apache

As a base image

FROM marekskopal/php-v8js:8.5-fpm
COPY . /var/www/html
RUN composer install --no-dev --optimize-autoloader

⁠V8 versions

The V8 version an image was built against is recorded in /etc/v8.version and in the v8.version image label. At runtime:

docker run --rm marekskopal/php-v8js:latest php -r 'echo V8Js::V8_VERSION, PHP_EOL;'

V8 14.x isn't supported yet because v8js doesn't build against it (phpv8/v8js#546⁠). 13.9.210 is the newest V8 13 release.

⁠zts (thread-safe) variant: FrankenPHP

The cli/fpm/apache images are non-thread-safe (NTS), like the upstream php defaults. The zts images ship a thread-safe v8js.so for ZTS PHP builds, most notably FrankenPHP⁠. An NTS extension cannot load into a ZTS PHP.

The Alpine zts image is meant for copying the extension into a FrankenPHP Alpine image:

FROM marekskopal/php-v8js:8.5-zts-alpine AS v8js
FROM dunglas/frankenphp:1-php8.5-alpine
RUN apk add --no-cache nodejs-libs
COPY --from=v8js /usr/local/lib/php/extensions/no-debug-zts-20250925/v8js.so \
     /usr/local/lib/php/extensions/no-debug-zts-20250925/v8js.so
COPY --from=v8js /usr/local/etc/php/conf.d/v8js.ini \
     /usr/local/etc/php/conf.d/v8js.ini

The extension directory suffix (no-debug-zts-20250925) is the PHP 8.5 module API stamp. It's the same across all 8.5.x patch releases, so it matches any FrankenPHP php8.5 Alpine tag.

⁠Known limitations

• No Temporal API. V8's Temporal implementation requires Rust, and there's no Linux arm64 Rust toolchain for V8, so it's disabled. Upstream gates it behind --harmony-temporal anyway.
• V8 13.9 is newer than upstream v8js CI covers (its CI matrix stops at 12.9). Every image passes the build-time smoke test.
• Alpine's V8 isn't pinned. It tracks Alpine's Node.js package, so an Alpine point release can change it. Check /etc/v8.version.

⁠Building your own

Images are built with docker buildx bake. You can override the V8 version, for example:

docker buildx bake --set "*.args.V8_VERSION=13.8.260"

Building V8 from source takes 1–2 hours per architecture on the first build. See the GitHub repository⁠ for build details, toolchain notes and CI setup.

⁠License

MIT