Installation

Requirements

• PHP 8.3, 8.4 or 8.5, non-thread-safe (NTS). Thread-safe (ZTS) builds are not supported.
• Linux or macOS. Windows is not supported.
• PIE, PHP’s extension installer.
• unzip, or PHP’s zip extension, for PIE to unpack a prebuilt binary.

Install with PIE

pie install phpstats/phit

PIE finds the latest release on Packagist, installs phit.so into the extension directory, and enables it for the PHP it runs under. To choose another PHP installation, pass --with-php-config=/path/to/php-config.

On Linux x86_64 and arm64 with glibc 2.35 or later, PIE downloads a prebuilt binary from the release, so nothing is compiled. Installing v0.3.1 this way was tested in the official php:8.4-cli-bookworm image with PIE 1.5.0 and unzip, and no Rust toolchain. The release workflow repeats the test for PHP 8.3, 8.4 and 8.5 on both architectures.

Building from source

On macOS, and on Linux systems without a matching binary (Alpine and other musl systems, or glibc older than 2.35), PIE builds the extension from source. The build needs:

• PHP’s development files: phpize and php-config for the same PHP installation.
• A C toolchain with autoconf and make.
• Rust, stable, from rustup.
• Clang and libclang.

These build tools are not needed at runtime.

On Debian or Ubuntu, the build tools come from:

sudo apt-get install build-essential autoconf pkg-config clang libclang-dev php-dev
curl -fsSL https://sh.rustup.rs | sh -s -- -y

A source build of v0.3.0 was tested in the official php:8.4-cli-bookworm image with PIE 1.5.0 and stable Rust. The image provides PHP’s development files, and the test added Clang, libclang and the image’s $PHPIZE_DEPS.

On macOS, install the Xcode command-line tools (xcode-select --install), Rust from rustup, and PHP and autoconf from Homebrew (brew install php autoconf). pie build phpstats/phit completed for v0.3.0 on macOS 27 (Apple silicon) with Homebrew PHP 8.5. If the build cannot find libclang, the development guide shows the variables that select Homebrew’s LLVM.

Prebuilt Linux binaries

Each GitHub release has the binaries PIE uses, built and tested on Debian Bookworm for NTS, non-debug PHP. They can also be installed by hand:

Each archive holds phit.so, INSTALL.txt, a manifest.json that records the build environment and the minimum glibc, the license, and the third-party notices. A .sha256 file sits beside each archive.

sha256sum -c php_phit-v0.3.1_php8.4-x86_64-linux-glibc-nts.sha256
unzip php_phit-v0.3.1_php8.4-x86_64-linux-glibc-nts.zip -d phit
sudo cp phit/phit.so "$(php-config --extension-dir)/"

Then add extension=phit.so to the PHP configuration for each runtime that needs it, and restart PHP-FPM. The release workflow tests these steps for every archive in the matching official PHP image. Releases up to v0.3.0 used .tar.gz archives named phit-0.3.0-php8.4-x86_64-nts-bookworm.tar.gz, which PIE does not download.

Verify

php -r 'echo phpversion("phit"), PHP_EOL;'

0.3.1

The command line and PHP-FPM often read different configuration files. Check the web runtime separately, for example with extension_loaded('phit') in a request, and restart PHP-FPM workers after installing or upgrading. Deploying to servers covers containers and FPM.

Declare the dependency

An application can declare the extension in its composer.json, so Composer reports a missing extension at install time:

{
    "require": {
        "ext-phit": "*"
    }
}

The polyfill also satisfies ext-phit. See Extension or polyfill.

Upgrade

Run pie install phpstats/phit again, or replace phit.so with the newer binary, then restart PHP-FPM. The release notes describe each release.