docs

title	elephc Documentation
description	A PHP-to-native compiler. Compiles a static subset of PHP to native assembly and produces standalone binaries for supported targets.
sidebar	order 0

elephc compiles PHP to native binaries for the supported targets — currently macOS ARM64, Linux ARM64, and Linux x86_64. No interpreter, no VM, no runtime dependencies. This documentation covers everything from PHP syntax support to compiler-specific extensions and internal architecture.

Getting Started

• Installation — install elephc via Homebrew or from source
• Your First Program — write, compile, and run your first PHP binary
• Benchmark Suite — compare elephc against PHP and equivalent C fixtures

How-To

Task-oriented guides for building real programs with elephc.

• Build a Fiber Web Server — create a native HTTP server with non-blocking sockets, poll(), and one Fiber per connection

Compiling

Everything about driving the compiler: the command-line flags and the full path from a .php file to a native binary.

• Compiling Overview — basic invocation, output naming, defaults, and a map of this section
• The compilation pipeline — every phase from source text to binary, in order
• CLI reference — the complete, authoritative list of every flag, value, default, and env override
• Targets and cross-compilation — the supported target matrix and --target
• Optimization and codegen controls — --ir-opt (EIR identity, peephole, and dead-instruction passes), --regalloc, --null-repr
• Output formats and diagnostics — --emit, --emit-asm, --emit-ir, --check, --timings, --source-map, --debug-info, --gc-stats, --heap-debug
• Source maps — the --source-map v2 JSON schema (function ranges, labels, opcode/origin-tagged mappings, inverse line index) and --debug-info DWARF lines
• Linking, heap, and conditional compilation — --link/-l, --link-path/-L, --framework, --heap-size, --define

PHP Syntax

Standard PHP features supported by elephc. Implemented PHP syntax is intended to match PHP behavior; known compatibility gaps are documented on the relevant reference pages and tracked in the roadmap.

• Types — int, float, string, bool, array, null, mixed, callable, enum, union types, extension types, type casting
• Operators — arithmetic, comparison, instanceof, logical, bitwise, string, assignment, ternary, null coalescing, error control
• Control Structures — if/else, while, for, foreach, switch, match, multi-level break/continue, try/catch/finally
• Functions — declarations, closures, arrow functions, named arguments, variadic, spread, pass-by-reference, first-class callables, static variables
• Strings — escape sequences, interpolation, heredoc/nowdoc, 70+ built-in string functions
• Regex — PCRE2-backed preg_* functions, SPL regex iterators, and native PCRE2 build requirements
• Arrays — indexed, associative, copy-on-write, 50+ built-in array functions
• Math — abs, floor, ceil, round, trigonometry, logarithms, random, constants
• Classes — inheritance, interfaces, abstract/final classes, typed/final/static properties, static property redeclarations, constructor promotion, methods, traits, enums, magic methods
• SPL — SPL interfaces, exceptions, autoload/introspection helpers, and runtime-backed containers
• Namespaces — namespace, use, include/require/include_once/require_once, Composer/SPL autoloading, class introspection, constants, superglobals
• System & I/O — system functions, date/time, JSON, filesystem, exec, debugging
• Streams — stream resources, wrappers, contexts, filters, sockets, TLS, process pipes
• Magic Constants — __DIR__, __FILE__, __LINE__, __FUNCTION__, __CLASS__, __METHOD__, __NAMESPACE__, __TRAIT__
• Fibers — cooperative coroutines (PHP 8.1+ Fiber): start, suspend, resume, FiberError
• Generators — yield, yield from, Generator::send / throw / getReturn, state-machine codegen
• PDO (Databases) — PDO connections, prepared statements, fetch modes, transactions, and PDOException for SQLite, PostgreSQL, and MySQL/MariaDB drivers
• Date and Time — DateTime, DateTimeImmutable, DateTimeZone, DateInterval: construct, format, setters, add/sub, diff
• Calendar — ext/calendar: Julian Day conversions for the Gregorian, Julian, French Republican and Jewish calendars, Easter, day/month names, cal_* dispatch
• Images — GD image creation, I/O, color, drawing, text, transforms/filters, Exif/IPTC metadata, the Imagick (Imagick/ImagickDraw/ImagickPixel/ImagickPixelIterator/ImagickKernel) and Gmagick (Gmagick/GmagickDraw/GmagickPixel) object APIs, and Cairo 2D vector drawing (CairoImageSurface/CairoContext/CairoMatrix/patterns/gradients), plus getimagesize/image_type_to_*, backed by a pure-Rust codec/raster bridge (no system GD/ImageMagick/GraphicsMagick/cairo/libpng/libjpeg/libexif)

Beyond PHP

Compiler-specific extensions that go beyond standard PHP. These features have no PHP equivalent and exist to enable use cases PHP was never designed for.

• Pointers — ptr(), ptr_get(), ptr_set(), pointer arithmetic, typed casting
• Buffers — buffer<T> for fixed-size contiguous arrays, hot-path data
• Packed Classes — flat POD records with compile-time field offsets
• FFI & Extern — calling C libraries, extern functions/globals/classes, callbacks
• Conditional Compilation — ifdef blocks, compile-time feature flags, CLI flags
• Shared Libraries (cdylib) — --emit cdylib, #[Export] C-ABI functions, dlopen lifecycle
• Web Server (--web) — compile a PHP file into a standalone prefork HTTP server binary
• zval Bridge — zval_pack/unpack/type/free convert elephc values to/from PHP zval structs

Compiler Internals

How elephc works under the hood — from lexing to code generation and runtime structure.

• What is a Compiler? — the big picture of compilation
• The Pipeline — from <?php to running binary
• The Lexer — raw text to tokens
• The Parser — tokens to AST with Pratt parsing
• The Type Checker — compile-time type inference and validation
• The Optimizer — constant folding, constant propagation, purity / may-throw reasoning, control-flow pruning, normalization, and dead-code elimination on the AST
• The Code Generator — checked AST to EIR, then target assembly
• The EIR Design — PHP-shaped intermediate representation used by codegen and --emit-ir
• The Runtime — hand-written assembly routines
• Memory Model — stack frames, heap, reference counting
• Architecture — module map, calling conventions
• ARM64 Assembly — introduction to ARM64
• ARM64 Instructions — instruction reference

For compile-time instrumentation and debug artifacts, the CLI also supports --timings to print per-phase compiler timings, including the optimizer phases, and --source-map to emit a sidecar .map file next to generated assembly.