phprs

Modernizing PHP with Rust — a memory-safe PHP interpreter and toolchain written in Rust. Performance is a goal; rigorous, published comparisons against PHP are not claimed here yet.

Why phprs? The Rust Advantage

PHP powers much of the web; many production runtimes are implemented in C and C++. phprs is an experiment in implementing PHP semantics in Rust so we can lean on the borrow checker and modern tooling. It aims to be:

Safer by construction (Rust): Memory errors that plague C/C++ code are largely ruled out in safe Rust; the interpreter still has correctness and parity work ahead.
A performance-minded design: Opcode dispatch, JIT hooks, and LLVM for the host binary — without promising a given speedup over Zend until we publish reproducible benchmarks.
Concurrency-friendly host code: Rust’s type system helps avoid data races in the engine itself; PHP’s shared mutable runtime model is still evolving in phprs.
Test-backed: 346+ workspace tests (library + CLI + integration), plus end-to-end example runs in CI.

phprs brings PHP into the future by:

🛡️ Memory Safety - The Rust Guarantee

Traditional PHP (C-based) Problems:

❌ Memory leaks from manual allocation/deallocation
❌ Buffer overflows leading to security exploits
❌ Use-after-free vulnerabilities
❌ Dangling pointers causing crashes
❌ Segmentation faults in production

What Rust gives the codebase:

Strong memory safety guarantees for safe code (no dangling pointers from the borrow checker’s rules).
Bounds-checked access patterns by default, reducing classic buffer overruns.
Option and Result instead of nullable pointers everywhere.
unsafe is explicit and should stay rare and reviewed.

This does not automatically make every PHP script “more secure” end-to-end — it raises the bar for the interpreter implementation itself. Application security still depends on how you deploy and what you run.

⚡ Performance — goals, not guarantees

Rust is a good host language for a VM: LLVM, predictable allocation patterns, and room to optimize hot paths. phprs includes pieces like direct opcode dispatch and JIT-oriented hooks, but we do not publish head-to-head PHP 8.x numbers here — workloads and completeness differ too much for a fair slogan.

If you want the engineering direction (dispatch, JIT ideas, etc.), see PERFORMANCE.md. Treat it as design notes, not a audited benchmark report, until we link reproducible methodology and results.

🔒 Thread Safety - Fearless Concurrency

Traditional PHP Limitations:

❌ No true multi-threading support
❌ Process-based concurrency (high memory overhead)
❌ Race conditions in extensions
❌ Global state issues

Rust (host code):

The borrow checker and Send / Sync rules catch many concurrency mistakes at compile time in the Rust parts of the project.
Primitives like Arc, mutexes, and OnceLock are the usual tools for shared engine state.

PHP scripts under phprs still run through a single runtime model; don’t assume “multi-threaded PHP” parity with extensions or Zend here.

🌐 Framework Support

Progressive compatibility with popular PHP frameworks and CMSs (stubs and demos ship in examples/):

WordPress ✅ - Hooks, wpdb, plugin/theme loading (see examples/wordpress/)
CodeIgniter 4 ✅ - Minimal bootstrap + routed controller demo (examples/codeigniter/, covered by tests/examples_runtime.rs)
Drupal ✅ - Minimal kernel/bootstrap stub (examples/drupal/, covered by tests/examples_runtime.rs)
Laravel 📋 - Routing, Eloquent, Blade (planned)
Symfony 📋 - HTTP kernel, DI (planned)

🛠️ Modern Ecosystem - Rust Crate Integration

Leveraging crates.io:

HTTP: reqwest for HTTP/HTTPS from the host
Regex: the regex crate (different tradeoffs vs PCRE — not a drop-in performance claim)
Crypto / hashing: common Rust crates for checksums and tooling
PDO / sessions / JSON: implemented or stubbed to varying degrees — see source and tests for what’s real today
Package manager: Composer-oriented workflows with semver for version parsing
Dev server: phprs serve for local tries

There is a huge ecosystem of maintained Rust libraries; phprs only uses a small slice.

🎯 Standalone & Embeddable - Rust's Portability

Deployment:

Single binary (typical Rust workflow): fewer moving parts than a full PHP build with many extensions.
Image size and static linking depend on how you package the CLI — compare measurements for your own Dockerfile, don’t trust a slogan.
Cross-compilation is possible in principle; CI mainly exercises tier-1 targets you care about.
Library crate: embed from Rust; FFI to other languages is possible but not the focus of this README.
WASM / every platform: aspirational until documented.

Rust helps with predictable builds; it doesn’t magically shrink every deployment.

Quick Start

Installation

# Clone the repository
git clone https://github.com/yingkitw/phprs.git
cd phprs

# Build library + CLI (workspace)
cargo build --release

# CLI binary: target/release/phprs (from `phprs-cli` workspace member)

Usage - It's That Simple!

Run any PHP file - Zero configuration needed:

# Run a PHP script
phprs run script.php

# Or use cargo during development
cargo run -p phprs-cli -- run script.php

Start development server:

# Built-in web server on port 3080
phprs serve

# Custom port
phprs serve --port 8080

Package management:

# Initialize composer.json
phprs pkg init

# Install dependencies
phprs pkg install

# Add a package
phprs pkg require vendor/package

Running code written for PHP

phprs targets PHP language compatibility, but many extensions, ini settings, and edge cases differ from Zend PHP. Try your script and fix gaps — we don’t promise bit-for-bit behavior yet.

<?php
// Example that may run once the engine supports the features you use
class User {
    public function __construct(
        private string $name,
        private string $email
    ) {}
    
    public function greet(): string {
        return "Hello, {$this->name}!";
    }
}

$user = new User('John', 'john@example.com');
echo $user->greet();

cargo run -p phprs-cli -- run your-app.php

WordPress / Laravel / Symfony: not production migration targets today — use the examples/ trees and TODO.md to see what is implemented. Large apps should expect porting work.

Examples

Basic PHP Script

<?php
// examples/01_hello_world.php
echo "Hello from phprs!\n";

// Many PHP 8 features work; unsupported ones fail at compile or runtime
$numbers = [1, 2, 3, 4, 5];
$squared = array_map(fn($n) => $n ** 2, $numbers);
print_r($squared);

Regular Expressions

<?php
// Email validation with PCRE
$email = "user@example.com";
if (preg_match('/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/', $email)) {
    echo "Valid email!\n";
}

// Pattern replacement
$text = "Hello World";
$result = preg_replace('/World/', 'phprs', $text);
echo $result; // "Hello phprs"

HTTP Streams

<?php
// Fetch data from APIs
$json = file_get_contents('https://api.example.com/data');
$data = json_decode($json, true);

// Works with any HTTP/HTTPS URL
$html = file_get_contents('https://example.com');

Database with PDO

<?php
// Connect to database
$pdo = new PDO('mysql:host=localhost;dbname=myapp', 'user', 'pass');

// Prepared statements (SQL injection safe)
$stmt = $pdo->prepare('SELECT * FROM users WHERE email = :email');
$stmt->bindParam(':email', $email);
$stmt->execute();

$user = $stmt->fetch();

Session Management

<?php
// Secure session handling
session_start();

// Store user data
$_SESSION['user_id'] = 123;
$_SESSION['username'] = 'john_doe';

// Access anywhere in your app
if (isset($_SESSION['user_id'])) {
    echo "Welcome back, " . $_SESSION['username'];
}

WordPress Plugin

<?php
/**
 * Plugin Name: My Plugin
 * Description: Runs on phprs
 */

// WordPress hooks work perfectly
add_action('init', function() {
    register_post_type('custom_type', [
        'public' => true,
        'label' => 'Custom Type'
    ]);
});

add_filter('the_content', function($content) {
    return $content . "\n<!-- Powered by phprs -->";
});

Complete Web Application

<?php
// Modern PHP web app with all features
session_start();

// Database connection
$pdo = new PDO('mysql:host=localhost;dbname=webapp', 'root', '');

// Handle form submission
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $email = $_POST['email'];
    
    // Validate with regex
    if (preg_match('/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/', $email)) {
        // Store in database
        $stmt = $pdo->prepare('INSERT INTO users (email) VALUES (:email)');
        $stmt->bindParam(':email', $email);
        $stmt->execute();
        
        // Set session
        $_SESSION['user_email'] = $email;
        
        echo "Registration successful!";
    }
}

More Examples:

examples/control_flow.php - if/switch, for, while, foreach (see tests/examples_runtime.rs)
examples/mbstring.php - Multibyte string helpers (mb_* subset)
examples/match_expression.php - match expressions
examples/regex-examples.php - Regex patterns
examples/http-stream-examples.php - HTTP streams
examples/session-examples.php - Sessions
examples/pdo-examples.php - PDO usage
examples/integration-test.php - Combined feature script
examples/wordpress/ - WordPress integration
examples/codeigniter/public/index.php - CodeIgniter-style bootstrap demo
examples/drupal/index.php - Drupal-style kernel stub

Project Structure

phprs/
├── src/
│   ├── engine/          # Core PHP engine
│   │   ├── types.rs     # Type system (PhpValue, PhpType, Val)
│   │   ├── compile/     # Lexer, parser, AST compilation
│   │   ├── vm/          # Virtual machine, opcodes, execution
│   │   ├── jit.rs       # JIT compiler
│   │   └── operators.rs # PHP operators implementation
│   └── php/             # PHP runtime & standard library
│       ├── regex.rs     # PCRE-compatible regex
│       ├── http_stream.rs # HTTP/HTTPS streams
│       ├── pdo.rs       # Database abstraction
│       ├── streams.rs   # Stream wrappers
│       └── filesystem.rs # File operations
├── bin/phprs/           # CLI application
├── examples/            # Curated demos (WordPress, CI, Drupal, language features)
│   ├── wordpress/       # WordPress integration
│   ├── regex-examples.php
│   ├── pdo-examples.php
│   └── integration-test.php
└── tests/               # Comprehensive test suite

API Usage

use phprs::engine::compile::{compile_string, compile_string_with_functions};
use phprs::engine::vm::{execute_ex, ExecuteData};
use std::sync::Arc;

// Compile a snippet (no user functions)
let op_array = compile_string("<?php echo 'Hello'; ?>", "inline.php")?;

// Scripts with `function` definitions need the function table:
let (op_array, fn_table) =
    compile_string_with_functions("<?php function f() { return 1; } echo f(); ?>", "t.php")?;

let mut exec_data = ExecuteData::new();
exec_data.function_table = Some(Arc::new(fn_table));
let _ = execute_ex(&mut exec_data, &op_array);

Framework Compatibility

WordPress (partial / `examples/` focus)

There is a WordPress-shaped demo under examples/wordpress/ (stubs, hooks, wpdb-ish pieces, sample plugin/theme). It is useful for development and tests, not a claim that arbitrary WordPress sites run unchanged in production on phprs.

Hooks, plugin/theme loading, and wpdb-related code paths are incomplete compared to PHP + Zend + extensions.
Treat real deployments as unsupported until you validate your stack yourself.

# Demo tree only — not a full WP core checkout
cargo run -p phprs-cli -- run examples/wordpress/index.php

📋 Laravel (Planned)

Routing and middleware
Eloquent ORM
Blade templating
Artisan CLI
Service container

📋 Symfony (Planned)

HTTP kernel
Dependency injection
Twig templating
Console component

✅ CodeIgniter 4 (demo)

Minimal app layout, autoload stubs, router, and sample controller under examples/codeigniter/
Full framework parity is not a goal of the demo; it exercises includes and routing-style code paths

Features & Capabilities

✅ Core PHP Engine

Types: PHP type system (int, float, string, array, object, null, bool) — growing toward full parity
Operators: Core arithmetic, logical, comparison, and string operators (see examples/operators.php)
Control Flow: if/else, switch, match, for (init/cond/inc), foreach (value-only), while; post-increment/decrement on simple variables ($i++)
Functions: User-defined functions, closures, arrow functions
Classes: OOP with inheritance, traits, interfaces, namespaces
Error Handling: try/catch/finally, exceptions

✅ Standard Library (70+ functions, expanding)

String Functions: strlen, substr, str_replace, trim, strtolower, strtoupper, ucfirst, and a growing mbstring subset (mb_strlen, mb_substr, … — see src/php/mbstring.rs, examples/mbstring.php)

URL / query: parse_url, http_build_query, and related helpers (src/php/url.rs)

Array Functions: array_map, array_filter, array_merge, count, in_array, array_key_exists

Regular Expressions: preg_match, preg_match_all, preg_replace, preg_split

File System: file_get_contents, file_put_contents, file_exists, dirname, basename

HTTP Streams: file_get_contents('http://...') - Full HTTP/HTTPS support

Database (PDO): new PDO(), query(), prepare(), execute(), fetch(), fetchAll()

Sessions: session_start(), session_destroy(), $_SESSION, session_id(), session_regenerate_id()

JSON: json_encode, json_decode

Type Checking: isset, empty, is_array, is_string, is_int, is_null

Output: echo, print, var_dump, print_r

✅ Advanced Features

JIT / optimizer hooks: present to varying degrees; see code and tests for what’s wired today
Bytecode / op arrays: compiled once per script in the current model
Memory: Rust ownership for engine structures; PHP values still use runtime-managed lifecycles
Async I/O: Tokio in the host for HTTP client / server paths where used

✅ Development Tools

Built-in Web Server: phprs serve
Package Manager: Composer-compatible
REPL: Interactive PHP shell (planned)
Debugger: Step-through debugging (planned)
Profiler: Performance analysis (planned)

Performance — expectations

phprs is not marketed with a “Nx faster than PHP” number. A fair comparison needs the same features enabled, representative workloads, and pinned versions. We’d rather under-promise and add measured results later than repeat placeholder tables.

Why Rust is still a sensible implementation language:

Mature LLVM backend for the host binary.
Control over allocation and hot paths in the VM without a GC for the Rust parts.
Room to grow JIT and other optimizations incrementally.

Inside the project today (high level):

Opcode execution via a direct dispatch table (see VM sources).
JIT-related code paths and optimizer scaffolding — completeness varies; read src/engine/jit.rs and tests.
PERFORMANCE.md discusses intent and architecture; when we have reproducible benchmarks, they should live next to methodology (machine, OS, PHP build flags, phprs commit).

If you need predictable numbers for a decision, measure your own scripts on both runtimes or open an issue asking for a benchmark harness — we welcome contributions there.

Getting Started

Prerequisites

Rust 1.75+ (2024 edition)
Cargo (comes with Rust)

Build from Source

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone https://github.com/yingkitw/phprs.git
cd phprs
cargo build --release

# Install globally (optional)
cargo install --path bin/phprs

Run Your First Script

# Create a PHP file
echo '<?php echo "Hello from phprs!\n";' > hello.php

# Run it
phprs run hello.php

Try the Examples

# Run example scripts
phprs run examples/01_hello_world.php
phprs run examples/regex-examples.php
phprs run examples/pdo-examples.php

# WordPress example
phprs run examples/wordpress/index.php

# Integration test (all features)
phprs run examples/integration-test.php

# Run all tests
cd examples
chmod +x run-all-tests.sh
./run-all-tests.sh

Testing

# Library + CLI + integration tests (recommended)
cargo test --workspace

# Library only
cargo test --lib

# PHP example compile checks
cargo test --test php_examples

# End-to-end: compile + VM + output for curated `examples/*.php`
cargo test --test examples_runtime

# Smoke a script manually
cargo run -p phprs-cli -- run examples/control_flow.php
cargo run -p phprs-cli -- run examples/test-streams-regex-pdo.php
cargo run -p phprs-cli -- run examples/wordpress/test-theme-plugin.php

The workspace runs clean (no warnings) on cargo test --workspace and cargo build --workspace.

Documentation

Core Documentation

SPEC.md - Project specification and scope
ARCHITECTURE.md - Module structure and execution flow
TODO.md - Migration roadmap and statistics (70+ built-in functions, 15 PHP runtime modules)
PERFORMANCE.md - Optimization ideas and VM notes (not a benchmark certificate)

Feature Documentation

examples/STREAMS-REGEX-PDO-README.md - Stream wrappers, regex, sessions, PDO
examples/wordpress/THEME-PLUGIN-README.md - WordPress integration guide
examples/TEST-GUIDE.md - Comprehensive testing guide
examples/TESTING-SUMMARY.md - Example and test coverage notes

Quick Links

examples/ - Curated PHP demos (language features, WordPress, CodeIgniter, Drupal stubs)
AGENTS.md - Development guidelines
Cargo.toml - Dependencies and build configuration

Roadmap

✅ Completed (v0.1.x)

Core PHP engine with 63 opcodes
70+ built-in functions
Regular expressions (PCRE-compatible)
HTTP/HTTPS stream wrappers
PDO database abstraction
Session handling
WordPress support (hooks, plugins, themes)
Package manager (Composer-compatible)
JIT / optimizer scaffolding (see sources; not a complete production JIT story)
Compiled op arrays (per-run bytecode; caching story is incremental)

🚧 In Progress (v0.2.x)

Laravel framework support
Symfony framework support
Advanced JIT optimizations
Debugger and profiler
REPL (interactive shell)

📋 Planned (v0.3.x+)

Deeper CodeIgniter / Drupal parity (beyond examples/ demos)
Native extensions API
WebAssembly compilation
Distributed caching (Redis, Memcached)
Real database drivers (MySQL, PostgreSQL)
HTTP/2 and HTTP/3 support

See TODO.md for detailed roadmap.

Contributing

We welcome contributions! Here's how to get started:

Development Setup

# Fork and clone
git clone https://github.com/YOUR_USERNAME/phprs.git
cd phprs

# Create a branch
git checkout -b feature/my-feature

# Make changes and test
cargo test
cargo run -p phprs-cli -- run examples/test-streams-regex-pdo.php

# Submit PR
git push origin feature/my-feature

Areas for Contribution

🐛 Bug Fixes: Report or fix issues
✨ Features: Implement new PHP functions or features
📚 Documentation: Improve docs and examples
🧪 Testing: Add test cases
🎨 Framework Support: Add support for more frameworks
⚡ Performance: Optimize hot paths

Guidelines

Follow Rust 2024 edition best practices
Add tests for new features
Update documentation
Keep code DRY and maintainable
See AGENTS.md for detailed guidelines

Community & Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs/

License

Apache License 2.0 - See LICENSE for details.

Acknowledgments

PHP Team - For the original PHP implementation
Rust Community - For the amazing language and ecosystem
Contributors - Everyone who has contributed to phprs

Built with ❤️ using Rust | Modernizing PHP for the future

phprs 0.1.7