elephc Documentation

The elephc project is organized into a core compiler/runtime engine and several specialized crates that provide high-performance bridges to PHP functionality.

Core Compiler (src/) components:

• Frontend: Lexer, Parser (AST), and Type Checker.
• Middle-end: IR (Intermediate Representation), Optimization passes, and Type-checking.
• Backend: Codegen (EIR to Assembly), Link-planning, and Linker integration.
• Runtime Support: codegen_support provides the heavy lifting for ABI, platform-specific transforms, and the extensive PHP runtime routines (strings, arrays, IO, etc.).
• Preludes: Specialized injection points for features like PDO, Timezones, Images, and Web superglobals.

Specialized Crates (crates/) for PHP functionality:

These crates are typically compiled as staticlibs to provide high-performance implementations of PHP core functions:

• elephc-crypto: Hashing/HMAC bridge for hash() and hash_hmac().
• elephc-image: Image processing bridge (GD, Exif, Imagick, Gmagick, Cairo).
• elephc-magician: Optional EvalIR parser/interpreter for dynamic eval() support.
• elephc-pdo: Multi-driver database bridge.
• elephc-phar: PHAR/tar/zip archive bridge for phar:// paths.
• elephc-tls: TLS bridge for https:// stream wrappers.
• elephc-tz: IANA timezone-introspection bridge.
• elephc-web: Prefork HTTP server bridge for --web binaries.

elephc is a PHP-compatible compiler and runtime. As of the current roadmap, it supports a wide range of PHP language features including:

Control Structures

• Loops: if, elseif, else, while, for, do...while.
• Loop Control: break N and continue N (multi-level).
• Branching: switch (with fall-through) and match expressions (PHP 8 style, no fall-through).

Variables and Types

• Types: Integers, Strings, Booleans (true/false), and Floats.
• Type Casting: (int), (string), (float), (bool), (array).
• Null: Proper null support with is_null() and null coercion.
• Constants: define(), const, and predefined constants like PHP_INT_MAX, M_PI.
• Scope: global $var, static variables, and local function scope.
• Parameter Handling: Pass by reference (&$x), default values, and variadic functions (...$args).
• Closures: Anonymous functions with use captures and Arrow functions (fn($x) => ...).

Operators

• Arithmetic: +, -, *, /, %, ** (exponentiation).
• Assignment: Standard =, compound assignments (+=, -=, etc.), and null coalescing (??, ??=).
• Comparison: ==, !=, <, >, <=, >=, and strict comparison ===, !==.
• Logical: &&, ||, and, or, xor, !.
• Bitwise: &, |, ^, ~, <<, >> and compound versions.
• Other: Ternary (? :), Spaceship (<=>), and Spread operator (...).

Data Structures

• Indexed Arrays: $arr = [1, 2, 3]; with push, pop, count, etc.
• Associative Arrays: $map = ["key" => "value"]; with hash table runtime support.
• Multi-dimensional Arrays: [[1,2],[3,4]].
• Unpacking: List unpacking [$a, $b] = $array; and spread [...$a, ...$b].

Built-in Functions

• String: strlen, str_replace, explode, implode, sprintf, hash family, etc.
• Array: array_map, array_filter, array_merge, array_column, etc.
• File System: fopen, file_get_contents, mkdir, unlink, etc.
• Math: abs, min, max, round, rand, etc.

The fold_constants() pass recursively walks the AST and rewrites expressions whose results are statically decidable from their children. This allows the compiler to emit constants directly instead of calling runtime helpers like pow, __rt_concat, or numeric string conversion paths.

Supported folding operations include:

• Arithmetic: +, -, *, /, %, ** (scalar arithmetic).
• Bitwise/Shift: Integer bitwise and shift operations.
• Unary: -, !, and ~.
• Strings: Concatenation using the . operator.
• Comparisons: Strict, numeric, and spaceship <=> operators.
• Logical: && and || when both sides are scalar constants.
• Control Structures: ??, ternary, and match when the result is known.
• Arrays: Scalar indexed and associative array-literal reads (e.g., [2, 9][0]).
• Casts: Unambiguous scalar casts like (int)"42" or (bool)"0".

Folding is applied recursively inside function/method bodies, closures, arrow functions, default parameter values, property defaults, and constant declarations.

<?php
$x = (2 < 3) ? (2 ** 3) : (3 ** 4);
echo $x . "\n";

// After folding, the AST is effectively:

<?php
$x = 8;
echo $x . "\n";

The hash_init() function returns a HashContext object, which is used for incremental hashing. This object allows you to feed data into a hashing context in chunks using hash_update() and then finalize the digest with hash_final().

Key behaviors:

• Lifecycle: The context is freed automatically when the object goes out of scope. Using a context after hash_final() will raise a TypeError.
• Cloning: hash_copy() returns an independent object. Feeding the original after copying does not affect the copy, and finalizing the original leaves the copy usable.
• Security: hash_equals() should be used for timing-safe string comparison.
• Limitations:
  • serialize() is not supported and will raise an Exception.
  • HMAC streaming via hash_init($algo, HASH_HMAC, $key) is not supported; use hash_hmac() instead.
  • print_r() and var_export() do not render HashContext objects.
• Implementation: The class is injected by the compiler only when hashing functions are referenced. It is a real object, not a resource.

$c = hash_init('md5');
var_dump(is_object($c));            // bool(true)
var_dump(gettype($c));              // string(6) "object"
var_dump(get_class($c));            // string(11) "HashContext"
var_dump($c instanceof HashContext) // bool(true)
var_dump($c);                       // object(HashContext)#1 (1) { ["algo"]=> string(3) "md5" }