Documentation
elephc docs
Everything about elephc — from PHP syntax support to compiler-specific extensions and internal architecture.
Getting Started
Install elephc and compile your first program.
How-To
Task-oriented guides for building real programs with elephc.
Compiling
Command-line flags, the compilation pipeline, targets, optimization, and diagnostics.
Compiling Overview
How the elephc command-line compiler turns a PHP file into a standalone native binary, and a map of the compilation documentation.
The compilation pipeline
Every phase a PHP or LFC source file passes through on the way to a native binary, in order, with the timing label each phase reports.
CLI reference
The complete, authoritative list of every elephc command-line flag, its accepted values, default, and environment-variable override.
Targets and cross-compilation
The supported target matrix, how to select a target with --target, and the accepted target spellings.
Optimization and codegen controls
Controls that affect generated code quality and shape: the EIR optimization passes (--ir-opt), the register allocator (--regalloc), and the null representation (--null-repr).
Output formats and diagnostics
Choosing what the compiler produces (executable, PHP module, C library, assembly, IR) and the flags that inspect or instrument a compile.
Source maps
The version 2 JSON source-map schema emitted by --source-map for debugger, profiler, and disassembly tooling.
Linking, heap, and conditional compilation
Linking native libraries and frameworks for FFI, sizing the runtime heap, and defining compile-time symbols for ifdef branches.
Native dependencies
Declare, lock, install, inspect, prune, and link curated native packages with elephc native.
Interactive REPL
Run PHP interactively through eval with persistent state, parser-driven multiline input, and a cached native session host.
PHP Syntax
Standard PHP features supported by elephc. All PHP syntax is 100% compatible with the PHP interpreter.
Builtins
Index of all PHP builtins supported by Elephc.
Types
Data types supported by elephc: int, float, string, bool, array, null, mixed, iterable, resource, callable, object, enum, and extension types.
Operators
Arithmetic, comparison, logical, bitwise, string, assignment, ternary, null coalescing, and error-control operators.
Control Structures
if/else, while, for, foreach, switch, match, try/catch, and more.
Functions
Function declarations, closures, arrow functions, variadic parameters, and more.
Eval
Experimental PHP eval support, including literal AOT lowering, dynamic interpreter fallback, scope synchronization, safety, and limitations.
Strings
String types, escape sequences, interpolation, heredoc/nowdoc, and built-in string functions.
Regex
PCRE2-backed regular expressions, preg_* functions, SPL regex iterators, and the managed pcre2 package.
Arrays
Indexed arrays, associative arrays, copy-on-write, and built-in array functions.
Math
Mathematical functions: abs, floor, ceil, round, clamp, trigonometry, logarithms, and more.
Classes
Classes, interfaces, abstract classes, traits, enums, properties, and inheritance.
SPL
Standard PHP Library interfaces, exceptions, and runtime-backed container classes.
Namespaces
Namespace declarations, use imports, name resolution, include/require.
Sessions
PHP session functions for persistent state across HTTP requests under --web.
System & I/O
System functions, date/time, JSON, filesystem utilities, process execution, and debugging utilities.
Streams
Stream resources, wrappers, contexts, filters, sockets, TLS, and process pipes.
Magic Constants
PHP magic constants (__DIR__, __FILE__, __LINE__, __FUNCTION__, __CLASS__, __METHOD__, __NAMESPACE__, __TRAIT__) resolved at compile time to plain string or integer literals.
Fibers
Cooperative coroutines (PHP 8.1+ Fiber): create, start, suspend, resume, with FiberError.
Generators
Generator functions with yield, the built-in Iterator and Generator types, foreach over Iterator objects, and Generator::send for coroutine-style flow.
cURL
PHP's ext/curl on pinned libcurl 8.21.0 with HTTP/2, 25 protocols, OpenSSL, and native iOS SecTrust: easy, multi and share interfaces, uploads, callbacks, and documented PHP differences.
Date and Time
Built-in DateTime, DateTimeImmutable, DateTimeZone, and DateInterval classes for working with dates and time intervals.
Images
GD image creation and I/O, plus the always-available image info functions, backed by a pure-Rust codec bridge.
mysqli (MySQL / MariaDB)
The mysqli subset: connections, buffered queries and results, prepared statements, multi_query, mysqli_report error handling, and the documented divergences from php-src.
PDO (Databases)
PDO database access with SQLite, PostgreSQL, MySQL/MariaDB, optional PDO_DBLIB, PDO_FIREBIRD, PDO_ODBC, PDO_INFORMIX, PDO_IBM, PDO_SQLSRV, PDO_OCI, and PDO_CUBRID: connections, prepared statements, fetch modes, transactions, and php-src divergences.
Calendar
The ext/calendar functions: Julian Day conversions for the Gregorian, Julian, French Republican and Jewish calendars, plus Easter and calendar metadata.
OPcache
The Zend OPcache API over compiled scripts and the runtime cache for dynamic include and require.
PHP Compatibility
How much of PHP elephc covers: functions, classes, and constants by module, language constructs, extensions, and known limitations.
BCMath
Arbitrary-precision decimal arithmetic with PHP's 14 BCMath functions and immutable Number objects.
GMP
Arbitrary-precision integers with php-src's ext/gmp surface over a pinned libgmp 6.3.0, including operators, casts, serialization and all 51 functions.
Tokenizer
Inspect PHP source with token_get_all, token_name and PhpToken while preserving source bytes.
iconv
Character-set conversion and character-oriented string functions: the 10 PHP iconv functions.
PCNTL
Forking, waiting, process replacement, signals, sessions, daemonization, affinity, namespaces, and target-specific controls.
Core classes and constants
PHP Core attribute objects, enum interfaces, exceptions, weak object collections, and predefined constants.
DOM HTML (Termwind subset)
A pay-for-use DOMDocument HTML fragment walker for Termwind-style tree walks, not full PHP DOM.
XML
The ext/xml SAX parser (XMLParser, xml_* functions, XML_* constants) and ext/xmlwriter (XMLWriter, xmlwriter_* functions).
Random
PHP's random extension engines, Randomizer, interval boundaries, exceptions, and procedural API.
File information
PHP fileinfo functions, finfo objects, MIME types and character encodings.
String builtins
Builtins in the String category.
Array builtins
Builtins in the Array category.
Math builtins
Builtins in the Math category.
Type builtins
Builtins in the Type category.
JSON builtins
Builtins in the JSON category.
Regex builtins
Builtins in the Regex category.
Date builtins
Builtins in the Date category.
IO builtins
Builtins in the IO category.
Filesystem builtins
Builtins in the Filesystem category.
Streams builtins
Builtins in the Streams category.
Network builtins
Builtins in the Network category.
Process builtins
Builtins in the Process category.
SPL builtins
Builtins in the SPL category.
Class builtins
Builtins in the Class category.
Pointer builtins
Builtins in the Pointer category.
Buffer builtins
Builtins in the Buffer category.
Misc builtins
Builtins in the Misc category.
Database builtins
Builtins in the Database category.
Web builtins
Builtins in the Web category.
Image builtins
Builtins in the Image category.
XML builtins
Builtins in the XML category.
Beyond PHP
Compiler-specific extensions that go beyond standard PHP.
LFC Source Files
Tagless .lfc source files, mixed PHP/LFC projects, and per-file strict-mode behavior.
Pointers
Low-level memory access with ptr(), ptr_get(), ptr_set(), raw byte/string helpers, pointer arithmetic, and typed casting.
Buffers
Fixed-size contiguous arrays with buffer<T> for hot-path data and game loops.
Packed Classes
Flat POD record types with compile-time field offsets for hot-path storage.
FFI & Extern
Foreign Function Interface: calling C libraries, extern functions, globals, classes, and callbacks.
Conditional Compilation
ifdef blocks for compile-time feature flags and platform-specific code.
Shared Libraries (cdylib)
Compile PHP functions into a C-callable shared library with --emit cdylib and #[Export].
PHP extensions
Compile exported functions, classes and constants into real PHP 8.5 modules.
Web Server (--web)
Compile a PHP program into a standalone prefork HTTP server binary with --web.
Persistent Web Applications
Bootstrap one typed PHP application per worker and reuse it across isolated HTTP requests.
zval Bridge
Convert elephc values to and from PHP zval structs with zval_pack, zval_unpack, zval_type, and zval_free.
Profiling (elephc monitor)
Profile an elephc-compiled program at the PHP level with one command, in every environment: build it with --with-monitoring, then point elephc monitor at the binary or at the running service.
Generics
Generic functions, classes and methods that compile to one specialized version per type, instead of erasing to boxed mixed.
Hosting PHP extensions
Build real PECL, PIE, or in-house C extensions from source and call them from compiled programs with elephc extension.
Testing
The native test runtime: Elephc\Testing\TestCase, the supported PHPUnit-compatible assertion subset, the Runner and its report, and the PHPUnit\Framework\TestCase alias.
Compiler Internals
How elephc works under the hood — from lexing to ARM64 code generation.
What is a Compiler?
What happens when source code becomes a program.
The Pipeline
The full journey from PHP source to a running binary.
The Lexer
How raw text becomes tokens.
The Parser
How tokens become an AST with Pratt parsing.
The Type Checker
How elephc infers and validates types at compile time.
The Optimizer
How elephc folds constants, prunes control flow, and eliminates dead code before code generation.
The Code Generator
How EIR becomes target assembly and links against the shared runtime.
The Runtime
Hand-written assembly routines for strings, arrays, generators, fibers, system calls, exceptions, and I/O.
Eval Runtime Architecture
How literal eval is planned for AOT lowering, when Magician is linked, and how native and interpreted scopes share values.
Memory Model
Stack frames, heap allocation, and memory management.
Architecture
Module map, calling conventions, and pipeline diagram.
ARM64 Assembly
Introduction to ARM64 assembly for compiler output.
ARM64 Instructions
ARM64 instruction reference used by elephc.
The EIR Design
Specification for elephc's default intermediate representation between AST optimization and assembly emission.