How to Deploy & Use php/php-src

# PHP Interpreter Build and Deployment Guide

## 1. Prerequisites

### Required Build Tools
- **C Compiler**: GCC or Clang with build essentials
- **autoconf**: Generate configuration scripts
- **bison**: Parser generator
- **re2c**: Lexer generator
- **libtool**: Library support (macOS/Linux)
- **pkg-config**: Library metadata detection

### Required Libraries (Default Build)
- **libxml2-dev** (or libxml2-devel)
- **libsqlite3-dev** (or sqlite-devel)

### OS-Specific Installation

**Ubuntu/Debian:**
```shell
sudo apt install -y pkg-config build-essential autoconf bison re2c libxml2-dev libsqlite3-dev

Fedora/RHEL:

sudo dnf install re2c bison autoconf make libtool ccache libxml2-devel sqlite-devel

macOS (Homebrew):

brew install autoconf bison re2c libiconv libxml2 sqlite

Note: Ensure bison is in your PATH as macOS ships with an outdated version.

macOS (MacPorts):

sudo port install autoconf bison re2c libiconv libxml2 sqlite3

2. Installation

Clone Repository

git clone https://github.com/php/php-src.git
cd php-src

Generate Configure Script

./buildconf

Configure Build

Development build (recommended for debugging):

./configure --enable-debug

Production build (optimized):

./configure

View all available options:

./configure --help

Compile

Use parallel jobs matching your CPU cores:

make -j$(nproc)

On macOS use sysctl -n hw.ncpu instead of nproc.

Install System-Wide

sudo make install

Default install prefix is /usr/local. Use --prefix=/path with configure to change.

3. Configuration

Build Configuration Flags

Key ./configure options:

• --enable-debug: Enable debug symbols and assertions (development)
• --prefix=/usr/local/php: Installation directory
• --disable-all: Minimal build without extensions
• --enable-{extension}: Enable specific extensions (see ./configure --help)

Runtime Configuration

PHP uses php.ini for runtime configuration. Search paths (in order):

1. PHPRC environment variable
2. --with-config-file-path compile-time path
3. Default system locations (/usr/local/lib, /etc/php)

Testing Environment Variables

• TEST_PHP_ARGS: Arguments for test runner (e.g., -j4 for parallel)
• TESTS: Specific test directories to run

Example:

export TEST_PHP_ARGS=-j4

4. Build & Run

Development Workflow

Build with debugging support:

./buildconf --force
./configure --enable-debug --enable-maintainer-zts
make -j$(nproc)

Run without installing:

./sapi/cli/php -v
./sapi/cli/php your_script.php

Production Build

./configure \
    --prefix=/usr/local/php \
    --enable-fpm \
    --with-openssl \
    --with-zlib \
    --enable-mbstring
make -j$(nproc)
sudo make install

Testing

Run full test suite:

make test

Parallel testing (recommended):

make TEST_PHP_ARGS=-j$(nproc) test

Test specific components:

make TESTS=tests/lang/ test
make TESTS=ext/json/ test

5. Deployment

Method 1: System Package Installation

Install compiled PHP to system paths:

sudo make install

Creates binaries at $PREFIX/bin/php, $PREFIX/sbin/php-fpm (if enabled).

Method 2: Container Deployment

Dockerfile example for custom PHP build:

FROM ubuntu:22.04 AS builder
RUN apt-get update && apt-get install -y \
    build-essential autoconf bison re2c \
    libxml2-dev libsqlite3-dev
COPY . /php-src
WORKDIR /php-src
RUN ./buildconf && \
    ./configure --prefix=/opt/php && \
    make -j$(nproc) && \
    make install

FROM ubuntu:22.04
COPY --from=builder /opt/php /opt/php
ENV PATH="/opt/php/bin:/opt/php/sbin:${PATH}"
CMD ["php", "-a"]

Method 3: Web Server Integration

After make install, configure your web server:

PHP-FPM (FastCGI Process Manager): Enable during configure: --enable-fpm

./configure --enable-fpm --with-openssl
make && sudo make install
sudo /usr/local/sbin/php-fpm

Apache Module: Enable during configure: --with-apxs2

./configure --with-apxs2=/usr/bin/apxs
make && sudo make install
# Restart Apache to load mod_php

Method 4: Static Binary Distribution

Create portable build:

./configure --enable-static --disable-shared LDFLAGS=-static
make -j$(nproc)
strip sapi/cli/php  # Reduce binary size

6. Troubleshooting

Build Errors

autoconf: not found Install autoconf: sudo apt install autoconf or brew install autoconf

bison: version mismatch Ensure bison 3.0+ is in PATH before system bison:

export PATH="/usr/local/opt/bison/bin:$PATH"

re2c: command not found Install re2c: sudo apt install re2c or brew install re2c

Configure fails with libxml2 not found Install development headers:

# Ubuntu
sudo apt install libxml2-dev
# Fedora
sudo dnf install libxml2-devel
# macOS
brew install libxml2
export PKG_CONFIG_PATH="/usr/local/opt/libxml2/lib/pkgconfig"

Compilation Issues

make: *** No targets specified Run ./buildconf first to generate configure script.

Parallel build failures Reduce job count or build single-threaded:

make -j1

Undefined reference errors during link Usually indicates missing system libraries. Re-run configure with explicit paths or install missing -dev packages.

Runtime Issues

php: command not found after install Add to PATH or use full path:

export PATH="/usr/local/bin:$PATH"
# Or
/usr/local/bin/php -v

Tests failing with Unable to fork Insufficient system resources. Reduce parallel test jobs:

make TEST_PHP_ARGS=-j1 test

Permission denied on make install Use sudo or specify user-writable prefix:

./configure --prefix=$HOME/php-install
make install  # No sudo needed

Debug Builds

If experiencing segmentation faults in development builds:

./configure --enable-debug --enable-address-sanitizer
make clean && make -j$(nproc)
# Run with gdb
gdb ./sapi/cli/php
(gdb) run your_script.php
(gdb) bt  # Backtrace on crash