Imported from erikwang2013/coding-to-rust (php-to-rust/SKILL.md). Install upstream with npx skills add erikwang2013/coding-to-rust --skill php-to-rust. Copyright stays with the author.

PHP to Rust Migration

Architecture Mapping

PHP's shared-nothing, request-per-process execution model (FPM/mod_php) maps to Rust's long-lived, multi-threaded process with async I/O. The PHP runtime (Zend Engine -- interpreted bytecode, reference-counting GC, dynamic typing) is replaced by AOT compilation with zero runtime overhead. A Laravel or Symfony application served by PHP-FPM behind Nginx becomes a single Rust binary serving HTTP via Actix-Web, Axum, or Rocket, using tokio for async I/O. Composer's vendor directory and autoloader map to Cargo's Cargo.toml dependency resolution and Rust's module system. PHP's per-request isolation (every request starts fresh) becomes connection pooling and shared application state in Rust.

Type System Mapping

PHP's dynamic, weak typing is the largest conceptual gap. PHP 8.x's type declarations (int, string, ?string) provide a bridge, but the migration to Rust requires redesigning data structures around algebraic types and generics.

Memory & Ownership Model

PHP's reference-counted, copy-on-write memory model with garbage collection is the hardest mental shift. In PHP, every variable is a reference to a zval structure; in Rust, every variable owns its data, and sharing requires explicit borrowing.

The Copy-on-Write to Ownership Shift

// PHP: COW (Copy-on-Write) — variables share underlying value until mutated
$a = "hello";              // zval refcount = 1
$b = $a;                   // zval refcount = 2 (shared)
$a = "world";              // zval refcount = 1 on new string
// $b is still "hello"

// Rust: Ownership — Move semantics; sharing without copying uses borrowing
let a = String::from("hello");  // a owns the string
let b = a;                       // b now owns the string, a is no longer valid
// println!("{a}");              // compile error: a was moved

// explicitly borrow when sharing is needed
let a = String::from("hello");
let b = &a;                      // b borrows a
println!("{a} {b}");            // both are usable

PHP Array Shapes -> Rust Structs / Enums

// PHP: arrays used as universal data structure
function getUser(int $id): array {
    return [
        'id' => 1,
        'name' => 'Alice',
        'email' => 'alice@example.com',
        'roles' => ['admin', 'editor'],
        'profile' => [
            'avatar' => 'https://...',
            'bio' => 'Software engineer',
        ],
    ];
}

// Rust: each data shape gets a concrete type
use serde::Serialize;

#[derive(Debug, Clone, Serialize)]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub roles: Vec<Role>,
    pub profile: Profile,
}

#[derive(Debug, Clone, Serialize)]
pub struct Profile {
    pub avatar: Option<String>,
    pub bio: Option<String>,
}

fn get_user(id: i64) -> Result<User, UserError> {
    // compiler guarantees return type matches struct definition
    Ok(User {
        id: 1,
        name: "Alice".into(),
        email: "alice@example.com".into(),
        roles: vec![Role::Admin, Role::Editor],
        profile: Profile {
            avatar: Some("https://...".into()),
            bio: Some("Software engineer".into()),
        },
    })
}

Reference Patterns vs. Borrowing

Concurrency / Async Translation

PHP is traditionally single-threaded per request (with extensions like Swoole or Fiber). Rust's async/await enables concurrent request handling natively. PHP 8.1 Fibers provide a limited form of cooperative multitasking; tokio provides full M:N async scheduling.

Synchronous -> Async Execution

// PHP: synchronous ORM queries (PDO/Doctrine)
public function getOrderSummary(int $orderId): array
{
    $order = $this->db->query(
        'SELECT * FROM orders WHERE id = ?',
        [$orderId]
    )->fetch();

    $items = $this->db->query(
        'SELECT * FROM order_items WHERE order_id = ?',
        [$orderId]
    )->fetchAll();

    $customer = $this->db->query(
        'SELECT * FROM customers WHERE id = ?',
        [$order['customer_id']]
    )->fetch();

    return [
        'order' => $order,
        'items' => $items,
        'customer' => $customer,
    ];
}

// Rust: concurrent queries — three queries run in parallel
async fn get_order_summary(
    pool: &PgPool,
    order_id: i64,
) -> Result<OrderSummary, sqlx::Error> {
    let (order, items, customer) = tokio::try_join!(
        sqlx::query_as::<_, Order>("SELECT * FROM orders WHERE id = $1")
            .bind(order_id)
            .fetch_one(pool),
        sqlx::query_as::<_, LineItem>("SELECT * FROM order_items WHERE order_id = $1")
            .bind(order_id)
            .fetch_all(pool),
        async {
            let order = sqlx::query_as::<_, Order>("SELECT customer_id FROM orders WHERE id = $1")
                .bind(order_id)
                .fetch_one(pool)
                .await?;
            sqlx::query_as::<_, Customer>("SELECT * FROM customers WHERE id = $1")
                .bind(order.customer_id)
                .fetch_one(pool)
                .await
        },
    )?;

    Ok(OrderSummary { order, items, customer })
}

PHP Fiber -> Rust Async Task

// PHP 8.1+: Fiber (cooperative concurrency)
$fiber = new Fiber(function () use ($data): void {
    $result = Fiber::suspend(processPart1($data));
    $final = processPart2($result);
    Fiber::suspend($final);
});

$part1 = $fiber->start();
$final = $fiber->resume($part1);

// Rust: async/await (also cooperative, with runtime scheduling)
async fn process(data: Data) -> Result<Final, Error> {
    let result = process_part1(&data).await?; // .await point = yield point
    process_part2(result).await
}

let handle = tokio::spawn(process(data));
let final = handle.await??;

Build System & Dependencies

Cargo.toml for a migrated Laravel application:

[package]
name = "web-api"
version = "0.1.0"
edition = "2021"

[dependencies]
axum = { version = "0.7", features = ["macros"] }
tokio = { version = "1", features = ["full"] }
tower = "0.4"
tower-http = { version = "0.5", features = ["cors", "trace", "compression-gzip", "auth"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
sqlx = { version = "0.8", features = ["runtime-tokio", "postgres", "chrono", "uuid"] }
uuid = { version = "1", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }
anyhow = "1"
thiserror = "2"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["json", "env-filter"] }
dotenvy = "0.15"
cookie = "0.18"
tower-sessions = "0.12"
argon2 = "0.5"  # PHP password_hash 等价物
validator = { version = "0.18", features = ["derive"] }

Framework Mapping: Laravel / Symfony -> Axum / Actix / Rocket

Standard Library & Ecosystem Mapping

Canonical Patterns

1. Dynamic Array Shape -> Struct

// PHP: arrays as universal data structure — no compile-time guarantees
function formatUser(array $user): array {
    return [
        'display' => $user['first_name'] . ' ' . $user['last_name'],
        'member_since' => date('Y', $user['created_at']),
        'is_admin' => in_array('admin', $user['roles'] ?? []),
    ];
}

// Rust: each shape is a concrete type — compile-time correctness
struct UserInput {
    first_name: String,
    last_name: String,
    created_at: chrono::NaiveDateTime,
    roles: Vec<String>,
}

struct UserDisplay {
    display: String,
    member_since: i32,
    is_admin: bool,
}

fn format_user(user: &UserInput) -> UserDisplay {
    UserDisplay {
        display: format!("{} {}", user.first_name, user.last_name),
        member_since: user.created_at.year(),
        is_admin: user.roles.iter().any(|r| r == "admin"),
    }
}

2. PHP Exception -> Rust Result

// PHP: try/catch exceptions — non-explicit control flow
public function transferFunds(Account $from, Account $to, Money $amount): void
{
    if ($from->balance < $amount) {
        throw new InsufficientFundsException($from->id);
    }

    try {
        $this->gateway->debit($from, $amount);
    } catch (PaymentException $e) {
        throw new TransferFailedException('debit failed', 0, $e);
    }

    try {
        $this->gateway->credit($to, $amount);
    } catch (PaymentException $e) {
        // need to rollback debit — exception-based control flow makes this fragile
        $this->gateway->refund($from, $amount);
        throw new TransferFailedException('credit failed', 0, $e);
    }
}

// Rust: Result — errors are values, not control flow
#[derive(Error, Debug)]
enum TransferError {
    #[error("insufficient funds in account {0}")]
    InsufficientFunds(String),
    #[error("payment gateway error: {0}")]
    Gateway(#[from] PaymentError),
}

async fn transfer_funds(
    gateway: &dyn PaymentGateway,
    from: &Account,
    to: &Account,
    amount: Money,
) -> Result<(), TransferError> {
    if from.balance < amount {
        return Err(TransferError::InsufficientFunds(from.id.clone()));
    }

    gateway.debit(from, amount).await?; // ? propagates the error

    match gateway.credit(to, amount).await {
        Ok(()) => Ok(()),
        Err(e) => {
            // explicit compensating action
            let _ = gateway.refund(from, amount).await;
            Err(TransferError::Gateway(e))
        }
    }
}

3. Class Inheritance -> Trait + Composition

// PHP: class inheritance — reuse behavior
abstract class Mailer
{
    abstract protected function transport(): Transport;

    public function send(Message $message): void
    {
        $this->transport()->send($message->toArray());
        $this->log($message);
    }

    protected function log(Message $message): void
    {
        // log the send
    }
}

class SmtpMailer extends Mailer
{
    protected function transport(): Transport
    {
        return new SmtpTransport($this->config);
    }
}

// Rust: trait defines behavior, composition replaces inheritance
#[async_trait]
trait Transport: Send + Sync {
    async fn send(&self, message: &Message) -> Result<(), TransportError>;
}

trait Mailer {
    type TransportImpl: Transport;

    fn transport(&self) -> &Self::TransportImpl;

    async fn send(&self, message: &Message) -> Result<(), MailerError>
    where
        Self: Loggable,
    {
        self.transport().send(message).await?;
        self.log(message);
        Ok(())
    }
}

struct SmtpMailer {
    transport: SmtpTransport,
    config: SmtpConfig,
}

impl Mailer for SmtpMailer {
    type TransportImpl = SmtpTransport;
    fn transport(&self) -> &Self::TransportImpl { &self.transport }
}

4. Composer Autoload -> Module System

// PHP: PSR-4 autoload — filename maps to class name
// src/Services/Payment/Gateway.php
namespace App\Services\Payment;

use App\Contracts\GatewayInterface;
use App\Models\Transaction;

class Gateway implements GatewayInterface
{
    public function charge(Transaction $txn): void { ... }
}

// usage
use App\Services\Payment\Gateway;
$gw = new Gateway();

// Rust: explicit module tree — modules declared in files
// src/services/payment.rs
pub mod gateway;

// src/services/payment/gateway.rs
use crate::contracts::GatewayInterface;
use crate::models::Transaction;

pub struct Gateway { ... }

impl GatewayInterface for Gateway {
    fn charge(&self, txn: &Transaction) -> Result<(), GatewayError> { ... }
}

// usage — path mirrors module hierarchy
use crate::services::payment::gateway::Gateway;
let gw = Gateway::new(config);

5. Middleware / Request Pipeline

// Laravel: middleware pipeline
class Authenticate
{
    public function handle(Request $request, Closure $next): Response
    {
        if (!Auth::check()) {
            return redirect('/login');
        }
        return $next($request);
    }
}

// Rust (axum): middleware as async layer
use axum::{
    extract::Request,
    middleware::Next,
    response::{Response, Redirect},
};

async fn authenticate(
    mut request: Request,
    next: Next,
) -> Result<Response, StatusCode> {
    // extract user info from header or session
    let user = extract_user(&request).ok_or(StatusCode::UNAUTHORIZED)?;
    request.extensions_mut().insert(user);
    Ok(next.run(request).await)
}

// register middleware
let app = Router::new()
    .route("/dashboard", get(dashboard))
    .layer(middleware::from_fn(authenticate));

6. Dynamic Method Call -> Enum Dispatch

// PHP: dynamic method call — decided at runtime
class NotificationService
{
    public function notify(string $channel, string $message): void
    {
        $method = 'sendVia' . ucfirst($channel);
        if (method_exists($this, $method)) {
            $this->$method($message); // runtime dispatch
        }
    }

    private function sendViaEmail(string $msg): void { ... }
    private function sendViaSms(string $msg): void { ... }
    private function sendViaPush(string $msg): void { ... }
}

// Rust: enum + trait — compile-time safe dispatch
enum Channel {
    Email,
    Sms,
    Push,
}

struct NotificationService {
    email: EmailClient,
    sms: SmsClient,
    push: PushClient,
}

impl NotificationService {
    async fn notify(&self, channel: Channel, message: &str) -> Result<(), NotifyError> {
        match channel {  // exhaustive match, compiler guarantees all arms covered
            Channel::Email => self.email.send(message).await?,
            Channel::Sms => self.sms.send(message).await?,
            Channel::Push => self.push.send(message).await?,
        }
        Ok(())
    }
}

FFI & Incremental Migration

PHP-to-Rust migration typically happens at service boundaries or via PHP extensions. The recommended strategy is the "strangler fig" pattern: route traffic incrementally to Rust services.

Strategies

Sidecar Pattern (Recommended)

        +---------+
        | Nginx   |
        +----+----+
             |
    +--------+---------+
    |                  |
    v                  v
+---+----+      +-----+------+
| PHP App|      | Rust Axum  |
| (legacy)|      | (new API) |
+---+----+      +-----+------+
    |                  |
    +-----+------+-----+
          |      |
          v      v
      +---+------+---+
      |  PostgreSQL  |
      +--------------+

Nginx split configuration:

location /api/v2/ {
    proxy_pass http://rust-service:3000;
}

location /api/ {
    proxy_pass http://php-app:9000;
}

PHP Extension via C-ABI (for Library Migration)

// Rust side: cdylib export
use std::ffi::{CStr, CString};
use std::os::raw::c_char;

#[no_mangle]
pub extern "C" fn rustium_validate_email(ptr: *const c_char) -> i32 {
    let email = match unsafe { CStr::from_ptr(ptr) }.to_str() {
        Ok(s) => s,
        Err(_) => return 0,
    };
    // use email validation logic
    if email.contains('@') && email.len() <= 254 {
        1
    } else {
        0
    }
}

// PHP side: FFI call
$ffi = FFI::cdef(
    "int rustium_validate_email(const char* email);",
    "lib/librustium.so"
);

$valid = $ffi->rustium_validate_email("test@example.com");

Migration Order

Common Mistakes

Mistake 1: Porting Arrays as serde_json::Value Universally

// WRONG: translating PHP array habits directly to dynamic JSON types
use serde_json::Value;
fn get_user(id: i64) -> Value {
    json!({         // no compile-time type checking
        "id": 1,
        "name": "Alice",
        "roles": ["admin"]
    })
}

// CORRECT: define concrete types
#[derive(Serialize)]
struct User {
    id: i64,
    name: String,
    roles: Vec<String>,
}
fn get_user(id: i64) -> Result<User, Error> {
    // compiler guarantees all field types are correct
    Ok(User { id: 1, name: "Alice".into(), roles: vec!["admin".into()] })
}

Mistake 2: Copying PHP's Defensive Null Checks

// PHP: habit of checking null/empty everywhere
$name = $user['name'] ?? 'Unknown';
$email = isset($user['email']) ? $user['email'] : '';
$avatar = $user['profile']['avatar'] ?? null;

// Rust: Option type handles absence at the type level
struct User {
    name: String,                  // guaranteed non-null
    email: Option<String>,         // type system indicates nullable
    profile: Option<Profile>,
}

struct Profile {
    avatar: Option<String>,        // may not have an avatar
}

// no ?? operator needed; use pattern matching or combinators
let display_name = user.name;  // always valid
let email = user.email.unwrap_or_default();
let avatar = user.profile
    .as_ref()
    .and_then(|p| p.avatar.as_deref())
    .unwrap_or("/default-avatar.png");

Mistake 3: Runtime Flexibility Over Type Safety

// WRONG: PHP devs emulate dynamic dispatch with trait objects, losing type info
fn process_payment(method: Box<dyn Any>) -> Result<(), String> {
    if let Some(stripe) = method.downcast_ref::<StripePayment>() {
        stripe.charge();
    } else {
        return Err("unknown payment method".into());
    }
    Ok(())
}

// CORRECT: use enum + trait, compile-time exhaustive
enum PaymentMethod {
    Stripe(StripePayment),
    Paypal(PaypalPayment),
    BankTransfer(BankTransferPayment),
}

impl PaymentMethod {
    async fn charge(&self, amount: Money) -> Result<ChargeResult, PaymentError> {
        match self {
            PaymentMethod::Stripe(s) => s.charge(amount).await,
            PaymentMethod::Paypal(p) => p.charge(amount).await,
            PaymentMethod::BankTransfer(b) => b.charge(amount).await,
        }
        // adding a new payment method triggers compiler error for missing arm
    }
}

Mistake 4: Expecting Function-Level Scope Cleanup

// PHP: automatic cleanup at function end (refcount reaches zero)
function process(): void {
    $file = fopen('/tmp/data.csv', 'r');
    // ... use file ...
    // file auto-closes at function end (or GC collects)
}

// Rust: Drop at scope exit, not at function exit
fn process() -> Result<(), Error> {
    {
        let file = File::open("/tmp/data.csv")?;
        // ... use file ...
    } // file dropped here, not at function end

    // file is already closed, safe to open the same file again
    let file2 = File::open("/tmp/data.csv")?;
    Ok(())
} // scope-exit cleanup, not PHP-style "cleanup at function end"

Mistake 5: Over-Using unwrap() / expect()

// WRONG: PHP devs using unwrap() as PHP's implicit null ignoring
let user = db.get_user(id).unwrap();             // may panic
let email = user.email.unwrap();                 // may panic
let name = config.get("app.name").unwrap();      // may panic

// CORRECT: propagate errors or provide reasonable defaults/error handling
let user = db.get_user(id)
    .map_err(|e| AppError::NotFound { id, source: e })?;

let email = user.email
    .ok_or_else(|| AppError::Validation("email is required".into()))?;

let name = config.get("app.name")
    .unwrap_or_else(|| String::from("My App"));

Reference Implementations

Cross-Reference

• java-to-rust: Class-to-trait mapping; shared enterprise patterns with Laravel/Symfony migration
• go-to-rust: Async runtime patterns; PHP Fiber/Goroutine parallelism concepts
• nodejs-to-rust: Web framework migration; shared NPM/Composer-to-Cargo dependency mapping
• python-to-rust: Dynamic-to-static typing patterns; shared Django→Axum migration strategies
• ruby-to-rust: Dynamic language patterns; shared Rails/Laravel framework migration, Bundler/Composer to Cargo
• c-to-rust: PHP extension (C-ABI) interop if migrating via extension approach