ePHPm Implementation Guide

[workspace]
members = ["crates/*"]
resolver = "3"

[workspace.package]
version = "0.1.0"
edition = "2024"
rust-version = "1.85"
license = "MIT"
repository = "https://github.com/user/ephpm"

[workspace.dependencies]
tokio = { version = "1", features = ["full"] }
hyper = { version = "1", features = ["http1", "http2", "server"] }
hyper-util = "0.1"
http-body-util = "0.1"
tower = { version = "0.5", features = ["full"] }
serde = { version = "1", features = ["derive"] }
figment = { version = "0.10", features = ["toml", "env"] }
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
thiserror = "2"
anyhow = "1"
clap = { version = "4", features = ["derive"] }

[workspace.lints.rust]
unsafe_code = "warn"

[workspace.lints.clippy]
all = "warn"
pedantic = "warn"

# crates/ephpm/Cargo.toml
[package]
name = "ephpm"
version.workspace = true
edition.workspace = true
rust-version.workspace = true

[dependencies]
ephpm-server = { path = "../ephpm-server" }
ephpm-php = { path = "../ephpm-php" }
ephpm-config = { path = "../ephpm-config" }
tokio = { workspace = true }
clap = { workspace = true }
tracing = { workspace = true }
tracing-subscriber = { workspace = true }
anyhow = { workspace = true }

[lints]
workspace = true

[toolchain]
channel = "stable"
components = ["rustfmt", "clippy", "llvm-tools-preview"]

style_edition = "2024"
use_small_heuristics = "Max"
group_imports = "StdExternalCrate"
imports_granularity = "Module"

[licenses]
allow = [
    "MIT",
    "Apache-2.0",
    "Apache-2.0 WITH LLVM-exception",
    "BSD-2-Clause",
    "BSD-3-Clause",
    "ISC",
    "Unicode-3.0",
]

[advisories]
db-path = "~/.cargo/advisory-db"
db-urls = ["https://github.com/rustsec/advisory-db"]

name: CI
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: Swatinem/rust-cache@v2
      - run: cargo check --workspace --all-targets

  fmt:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          components: rustfmt
      - run: cargo fmt --all -- --check

  clippy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          components: clippy
      - uses: Swatinem/rust-cache@v2
      - run: cargo clippy --workspace --all-targets -- -D warnings

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: Swatinem/rust-cache@v2
      - uses: taiki-e/install-action@nextest
      - run: cargo nextest run --workspace

  deny:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: EmbarkStudios/cargo-deny-action@v2

  msrv:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@1.85.0
      - run: cargo check --workspace

name: Release
on:
  push:
    tags: ['v*']

jobs:
  build:
    strategy:
      matrix:
        php: ['8.3', '8.4']
        include:
          # Linux
          - os: ubuntu-latest
            target: x86_64-unknown-linux-gnu
            artifact_suffix: linux-x86_64
            binary_name: ephpm
          - os: ubuntu-24.04-arm
            target: aarch64-unknown-linux-gnu
            artifact_suffix: linux-aarch64
            binary_name: ephpm
          # macOS
          - os: macos-latest
            target: aarch64-apple-darwin
            artifact_suffix: macos-aarch64
            binary_name: ephpm
          - os: macos-13
            target: x86_64-apple-darwin
            artifact_suffix: macos-x86_64
            binary_name: ephpm
          # Windows
          - os: windows-latest
            target: x86_64-pc-windows-msvc
            artifact_suffix: windows-x86_64
            binary_name: ephpm.exe
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable

      - name: Build PHP static library
        run: |
          # Download and build static-php-cli
          # Build libphp.a with WordPress-required extensions
          bin/spc download --with-php=${{ matrix.php }} \
            --for-extensions="bcmath,curl,dom,exif,fileinfo,filter,gd,hash,iconv,json,mbstring,mysqli,openssl,pcre,session,simplexml,sodium,xml,xmlreader,zip,zlib"
          bin/spc build \
            "bcmath,curl,dom,exif,fileinfo,filter,gd,hash,iconv,json,mbstring,mysqli,openssl,pcre,session,simplexml,sodium,xml,xmlreader,zip,zlib" \
            --build-embed

      - name: Build Rust binary
        env:
          PHP_VERSION: ${{ matrix.php }}
          LIBPHP_DIR: ./buildroot
        run: cargo build --release

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: ephpm-php${{ matrix.php }}-${{ matrix.artifact_suffix }}
          path: target/release/${{ matrix.binary_name }}

  release:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
      - name: Create GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          files: ephpm-*/*

# Download static-php-cli
curl -fsSL https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64.tar.gz | tar xz

# Download PHP source + extension dependencies
bin/spc download --with-php=8.4 \
  --for-extensions="bcmath,curl,dom,exif,fileinfo,filter,gd,hash,iconv,json,mbstring,mysqli,openssl,pcre,session,simplexml,sodium,xml,xmlreader,zip,zlib"

# Build static libphp.a with embed SAPI
bin/spc build \
  "bcmath,curl,dom,exif,fileinfo,filter,gd,hash,iconv,json,mbstring,mysqli,openssl,pcre,session,simplexml,sodium,xml,xmlreader,zip,zlib" \
  --build-embed

# Output:
#   buildroot/lib/libphp.a          ← link this
#   buildroot/include/php/...       ← bindgen reads these headers

#include <sapi/embed/php_embed.h>
#include <main/SAPI.h>
#include <main/php_main.h>
#include <main/php_variables.h>
#include <Zend/zend.h>
#include <Zend/zend_exceptions.h>

use std::env;
use std::path::PathBuf;

fn main() {
    let php_dir = env::var("LIBPHP_DIR")
        .unwrap_or_else(|_| "/usr/local".to_string());

    // Tell cargo to link against libphp.a
    println!("cargo:rustc-link-lib=static=php");
    println!("cargo:rustc-link-search={}/lib", php_dir);

    // Also link system libraries that PHP depends on
    println!("cargo:rustc-link-lib=dylib=xml2");
    println!("cargo:rustc-link-lib=dylib=z");
    println!("cargo:rustc-link-lib=dylib=curl");
    println!("cargo:rustc-link-lib=dylib=ssl");
    println!("cargo:rustc-link-lib=dylib=crypto");

    // Generate Rust FFI bindings
    let bindings = bindgen::Builder::default()
        .header("wrapper.h")
        .clang_arg(format!("-I{}/include/php", php_dir))
        .clang_arg(format!("-I{}/include/php/main", php_dir))
        .clang_arg(format!("-I{}/include/php/Zend", php_dir))
        .clang_arg(format!("-I{}/include/php/TSRM", php_dir))
        .clang_arg(format!("-I{}/include/php/sapi/embed", php_dir))
        .generate()
        .expect("Unable to generate PHP bindings");

    let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
    bindings
        .write_to_file(out_path.join("php_bindings.rs"))
        .expect("Couldn't write bindings");
}

[server]
listen = "0.0.0.0:8080"
document_root = "/var/www/html"
index_files = ["index.php", "index.html"]
# workers = 4                  # future: number of PHP worker threads (ZTS)

[php]
max_execution_time = 30
memory_limit = "128M"
# ini_file = "/etc/php/8.5/php.ini"    # optional: load a custom php.ini
ini_overrides = [
    ["display_errors", "Off"],
    ["error_reporting", "E_ALL"],
]

# [logging]
# level = "info"               # tracing filter level
# format = "json"              # or "pretty" for development

# --- Future sections (not in MVP) ---

# [tls]
# auto = true                  # automatic ACME/Let's Encrypt
# email = "admin@example.com"
# domains = ["example.com", "www.example.com"]

# [db.sqlite]
# path = "./data/app.db"         # file path, or ":memory:" for in-memory
# journal_mode = "wal"
# create = true

# [db.mysql]
# url = "mysql://user:pass@db:3306/myapp"
# min_connections = 5
# max_connections = 50
# inject_env = true

# [db.postgres]
# url = "postgres://user:pass@db:5432/myapp"
# min_connections = 5
# max_connections = 30
# inject_env = true

# [kv]
# memory_limit = "256MB"
# eviction_policy = "allkeys-lru"

# [kv.cluster]
# seeds = ["node-b:7946", "node-c:7946"]

# [observability]
# admin_ui = true
# prometheus = true

# [observability.otlp_export]
# endpoint = "jaeger:4317"
# protocol = "grpc"

use figment::{Figment, providers::{Format, Toml, Env, Serialized}};
use serde::Deserialize;

#[derive(Debug, Deserialize)]
pub struct Config {
    pub server: ServerConfig,
    pub php: PhpConfig,
}

#[derive(Debug, Deserialize)]
pub struct ServerConfig {
    pub listen: String,
    pub document_root: String,
    #[serde(default = "default_index_files")]
    pub index_files: Vec<String>,
}

#[derive(Debug, Deserialize)]
pub struct PhpConfig {
    #[serde(default = "default_max_execution_time")]
    pub max_execution_time: u32,
    #[serde(default = "default_memory_limit")]
    pub memory_limit: String,
    #[serde(default)]
    pub ini_file: Option<PathBuf>,  // path to custom php.ini (applied before ini_overrides)
    #[serde(default)]
    pub ini_overrides: Vec<[String; 2]>,  // INI directives as [key, value] pairs
}

fn default_index_files() -> Vec<String> {
    vec!["index.php".into(), "index.html".into()]
}

fn default_max_execution_time() -> u32 { 30 }
fn default_memory_limit() -> String { "128M".into() }

impl Config {
    pub fn load(path: &str) -> Result<Self, figment::Error> {
        Figment::new()
            .merge(Serialized::defaults(Config::default()))
            .merge(Toml::file(path))
            .merge(Env::prefixed("EPHPM_").split("_"))
            .extract()
    }
}

# 1. Build
cargo build --release

# 2. Configure
cat > ephpm.toml <<'EOF'
[server]
listen = "0.0.0.0:8080"
document_root = "/var/www/wordpress"

[php]
max_execution_time = 30
memory_limit = "128M"
EOF

# 3. Run
./target/release/ephpm --config ephpm.toml

# 4. Verify — all must pass:

FROM scratch
COPY ephpm /usr/local/bin/ephpm
ENTRYPOINT ["ephpm"]