RPHP - Rust PHP Interpreter

A PHP interpreter written in Rust, implementing a subset of PHP 8.x features.

Project Status

This is an early-stage implementation that demonstrates the core architecture of a PHP interpreter. The project successfully implements:

• ✅ Lexical analysis (tokenization)
• ✅ Syntax analysis (parsing to AST)
• ✅ Compilation (AST to bytecode/opcodes)
• ✅ Virtual machine execution engine
• ✅ Basic type system (Zval)
• ✅ Extension system architecture
• ✅ CLI SAPI

Currently Supported Features

Control Flow

• ✅ Conditional statements: if, else, elseif
• ✅ Loops: while, for, foreach with full support
• ✅ Loop control: break and continue statements

Data Types & Operations

• ✅ Variables: Declaration and assignment ($x = 10;)
• ✅ Integers and floats: Full arithmetic support
• ✅ Strings: Literals and concatenation (. operator)
• ✅ Booleans: true, false with logical operations
• ✅ Null: null type
• ✅ Arrays: Indexed and associative arrays with full manipulation

Operators

• ✅ Arithmetic: +, -, *, /, %
• ✅ Comparison: <, >, <=, >=, ==, !=, ===, !==
• ✅ Logical: &&, ||, !
• ✅ String: . (concatenation)

Functions

• ✅ User-defined functions: Declaration, parameters, return values
• ✅ Function calls: With argument passing
• ✅ Anonymous functions/Closures: function($x) use ($y) { ... }
• ✅ Arrow functions: fn($x) => $x * 2 (PHP 7.4+)
• ✅ Variable capture: use() clause with value semantics, auto-capture in arrow functions
• ✅ Built-in functions:
  • Array: count, array_push, array_pop, in_array, array_merge, array_keys, array_values, array_sum, array_reverse, array_map, array_filter, array_reduce
  • String: strlen, substr, str_replace, strtoupper, strtolower, trim, explode, implode
  • Math: abs, max, min, pow

Object-Oriented Programming

• ✅ Classes: Definition with properties and methods
• ✅ Objects: Instantiation with new
• ✅ Constructors: __construct method
• ✅ Property access: $obj->property
• ✅ Method calls: $obj->method()
• ✅ Inheritance: Single inheritance with extends
• ✅ Visibility: public, private, protected modifiers
• ✅ Static members: Static properties and methods
• ✅ Abstract classes: Cannot be instantiated, can have abstract methods
• ✅ Interfaces: Define method contracts
• ✅ Traits: Method and property reuse across classes
• ✅ Type declarations: Parameter, return, and property types with nullable/union support

Exception Handling

• ✅ try/catch/finally: Full exception handling blocks
• ✅ throw: Throw exception objects
• ✅ Exception class: Built-in Exception with getMessage()/getCode()
• ✅ Custom exceptions: User-defined exception classes extending Exception
• ✅ Multi-catch: catch (TypeError | ValueError $e)
• ✅ Stack unwinding: Exceptions propagate across function calls

I/O

• ✅ Output: echo statement with multiple expressions

File Inclusion

• ✅ include/require: include, include_once, require, require_once
• ✅ Runtime inclusion: Full pipeline (lex → parse → compile → execute) at runtime
• ✅ Once tracking: include_once/require_once skip already-loaded files
• ✅ Shared scope: Included files share the caller's variable scope
• ✅ Path resolution: Relative paths resolved from current script's directory

Namespaces

• ✅ Namespace declarations: namespace App\Models;
• ✅ Use imports: use App\Models\User;
• ✅ Aliasing: use App\Models\User as UserModel;
• ✅ Qualified names: new App\Models\User() in expressions
• ✅ Global fallback: Built-in functions/classes accessible from any namespace

Comments

• ✅ Single-line: //, #
• ✅ Multi-line: /* */

Architecture

The interpreter follows the classic compilation pipeline:

PHP Source → Lexer → Tokens → Parser → AST → Compiler → Opcodes → VM → Execution

Key Components

• src/zend/lexer/: Tokenizes PHP source code
• src/zend/parser/: Parses tokens into Abstract Syntax Tree
• src/zend/ast/: AST node definitions
• src/zend/compiler/: Compiles AST to bytecode (opcodes)
  • Loop context tracking for break/continue
  • Jump target patching
• src/zend/vm/: Virtual machine that executes opcodes
  • vm.rs: Main VM execution engine (1122 lines)
  • operations.rs: Generic arithmetic operations
  • builtins/: Modular builtin function implementation
    • mod.rs: Central dispatcher
    • arrays.rs: Array functions
    • strings.rs: String functions
    • math.rs: Math functions
• src/zend/types/: Zval and PHP type system
• src/error/: Error handling with line number tracking
• src/ext/: Extension system
• src/sapi/: Server API layer

Building

Requires Rust 1.70 or later.

# Build the project
cargo build

# Or use make
make build

Running

# Run a PHP script
cargo run <script.php>

# Or use make
make run FILE=<script.php>

Testing

RPHP includes a comprehensive test suite:

# Run all tests
./run_tests.sh

# Or use make
make test

# Run a single test
cargo run tests/fixtures/04_if_true.php

Test Results

Current test status: 68/68 passing (100%)

✅ All features tested and working:

• Basic arithmetic and expressions
• Conditional statements (if/else/elseif)
• All comparison and logical operators
• While, for, and foreach loops
• Break and continue statements
• String operations and concatenation
• Arrays (indexed and associative)
• Array manipulation functions
• Higher-order array functions (map, filter, reduce)
• User-defined functions with parameters and returns
• Classes with inheritance
• Object properties and methods
• Constructors
• Static properties and methods
• Type declarations
  • Parameter types
  • Return types
  • Property types
  • Nullable types
  • Union types
• Abstract classes and interfaces
  • Abstract class declarations
  • Abstract method declarations
  • Interface definitions
  • Class implements interface
  • Runtime checks for abstract class instantiation
• Traits
  • Trait declarations with methods and properties
  • Class uses one or multiple traits
  • Trait method/property flattening at compile time
  • Class overrides trait methods
  • Trait methods override parent class methods
• Closures and anonymous functions (NEW)
  • Traditional anonymous functions with function() {}
  • Arrow functions with fn() =>
  • Variable capture with use() clause
  • Auto-capture in arrow functions
  • Closures as callbacks to built-in functions
  • Higher-order functions (functions returning closures)
• Exception handling
  • try/catch/finally blocks
  • throw statements
  • Built-in Exception class
  • Custom exception classes with inheritance
  • Multi-catch with | operator
  • Stack unwinding across function calls
• Built-in functions (21 functions across arrays, strings, math)
• Include/Require
  • Basic file inclusion with functions and classes
  • require_once deduplication
  • Shared variable scope between files
• Namespaces
  • Namespace-qualified class instantiation
  • Use imports with alias support
  • Global fallback for built-in functions

See tests/README.md for detailed test documentation.

Examples

Basic Arithmetic

<?php
$x = 10;
$y = 20;
$z = $x + $y;
echo $z;  // Output: 30

$ cargo run test.php
30

Conditional Statements

<?php
$x = 15;
if ($x > 10) {
    echo 100;
} else {
    echo 200;
}
// Output: 100

Loops with Break and Continue

<?php
// Break example
for ($i = 0; $i < 10; $i = $i + 1) {
    if ($i == 5) {
        break;  // Exit loop at 5
    }
    echo $i;
}
// Output: 01234

// Continue example
for ($i = 0; $i < 5; $i = $i + 1) {
    if ($i == 2) {
        continue;  // Skip iteration 2
    }
    echo $i;
}
// Output: 0134

Arrays and Functions

<?php
$arr = [1, 2, 3, 4, 5];
echo count($arr);  // Output: 5

function double($x) {
    return $x * 2;
}

$result = array_map("double", $arr);
foreach ($result as $val) {
    echo $val;  // Output: 246810
}

Object-Oriented Programming

<?php
class Animal {
    public $name;

    public function __construct($name) {
        $this->name = $name;
    }

    public function speak() {
        echo $this->name;
    }
}

class Dog extends Animal {
    public function bark() {
        echo "Woof";
    }
}

$dog = new Dog("Buddy");
$dog->speak();  // Output: Buddy
$dog->bark();   // Output: Woof

Type Declarations (PHP 7.0+ / 8.0+)

<?php
// Parameter and return type declarations
function add(int $a, int $b): int {
    return $a + $b;
}

// Nullable types
function greet(?string $name): string {
    if ($name === null) {
        return "Hello, Guest!";
    }
    return "Hello, " . $name;
}

// Union types (PHP 8.0+)
function process(int|float|string $value): string {
    return "Value: " . $value;
}

// Property type declarations
class User {
    public string $name;
    public int $age;
    private ?string $email = null;

    public function __construct(string $name, int $age) {
        $this->name = $name;
        $this->age = $age;
    }

    public function getInfo(): string {
        return $this->name . " is " . $this->age;
    }
}

$user = new User("Alice", 30);
echo $user->getInfo();  // Output: Alice is 30

Design Documentation

See docs/plans/2026-02-27-rphp-design.md for detailed design documentation.

Development Roadmap

Phase 1: Core Foundation ✅ (Completed)

• ✅ Basic lexer, parser, compiler, VM
• ✅ Variables, arithmetic, and type system
• ✅ Control flow (if/else)
• ✅ Loops (while, for, foreach)
• ✅ Break and continue statements
• ✅ Functions with parameters and returns
• ✅ Arrays (indexed and associative)
• ✅ String operations
• ✅ Classes, objects, inheritance
• ✅ 21 built-in functions
• ✅ Error reporting with line numbers
• ✅ VM refactoring for maintainability

Status: All 49 tests passing

Phase 2: Language Completeness ✅ (Completed)

• ✅ Static properties and methods (Completed)
• ✅ Type declarations (Completed)
  • Parameter type declarations: function foo(int $x, string $y)
  • Return type declarations: function foo(): int
  • Property type declarations: public int $age;
  • Nullable types: ?int, ?string
  • Union types: int|string, int|float
  • Built-in types: int, float, string, bool, array, object, void, mixed
• ✅ Abstract classes and interfaces (Completed)
• ✅ Anonymous functions and closures (Completed)
• ✅ Traits (Completed)
• ✅ Namespaces (Completed)
• ✅ use/import statements (Completed)
• ✅ include/require (Completed)

Phase 3: Exception Handling ✅ (Completed)

• ✅ try/catch/finally blocks
• ✅ throw statements
• ✅ Exception class hierarchy (built-in Exception + custom subclasses)
• ✅ Multi-catch support
• ✅ Stack unwinding across function/method calls
• Error to exception conversion

Phase 4: PHP 8.x Modern Features

• Named arguments
• Union types
• Match expressions
• Enums
• Readonly properties
• Constructor property promotion
• Attributes

Phase 5: Standard Library Extension

• File system operations (fopen, fread, fwrite, etc.)
• Network operations (curl, sockets)
• JSON support (json_encode, json_decode)
• Regular expressions (preg_match, preg_replace)
• Date/time handling (date, time, strtotime)
• Database abstraction (PDO)

Phase 6: Performance Optimization

• Opcode caching
• Constant folding and dead code elimination
• Inline caching for property access
• JIT compilation (experimental)
• Memory pool optimization

Phase 7: Production Ready

• CGI/FastCGI SAPI
• Web server integration (Nginx, Apache)
• Configuration system (php.ini parsing)
• Debugging support (xdebug compatibility)
• Profiling and performance monitoring

Known Limitations

1. No reference support: Variables are copied by value, not reference (no &$var)
2. No variadic functions: ...$args syntax not yet implemented
3. No static analysis: Type errors only detected at runtime
4. Limited error context: Error messages could provide more detailed context
5. No superglobals: $_GET, $_POST, $_SERVER, etc. not available (CLI only)
6. Memory management: Cycle detection GC not implemented (simple reference counting only)

Contributing

This is an educational/experimental project. Contributions are welcome!

License

MIT OR Apache-2.0

References

• PHP Language Specification
• PHP Source Code
• Zend Engine Documentation

Acknowledgments

This project is inspired by the official PHP implementation (php-src) and aims to demonstrate how a programming language interpreter works using Rust's safety and performance features.