whynot 0.1.0

Rust ↔ PHP bridge: call PHP functions from Rust, capture return values, output, and exceptions.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

# whyNot 🐘➡️🦀
[![Crates.io](https://img.shields.io/crates/v/whynot.svg)](https://crates.io/crates/whynot)
[![Docs.rs](https://docs.rs/whynot/badge.svg)](https://docs.rs/whynot)

**Rust ↔ PHP bridge** that lets you call PHP functions directly from Rust, capture return values, printed output, and exceptions — with async support via threads or Tokio.

---

## ✨ Features

- Call any PHP function from Rust
- Capture both return values and printed output
- Structured exception handling (`PhpException`)
- Objects returned with class + fields
- Persistent runtime (globals/includes survive across calls)
- `include` and `eval` support
- Async via threads (`call_async_with_cfg`)
- Async/await via Tokio (`--features async_tokio`)

---

## 🚀 Getting Started

### Install

To install you can run:
```bash
cargo add whynot
```

Or add to your `Cargo.toml`:
```toml
[dependencies]
whynot = "0.1.0"
```

### Requirements

- PHP CLI (`php`) available in PATH
- `php/runner.php` and `php/bootstrap.php` included in your project

---

## 📖 Usage

### Basic call

```rust
use whynot::{new_runtime, PhpRuntime, RuntimeConfig, RuntimeKind};

fn main() {
    let cfg = RuntimeConfig::default();
    let mut rt = new_runtime(RuntimeKind::Process(cfg)).unwrap();

    let result = rt.call("add", &[7.into(), 5.into()]).unwrap();
    println!("add.result = {:?}", result.result);
    println!("add.output = {:?}", result.output);
}
```

### Exceptions

```rust
let boom = rt.call("risky", &[]).unwrap();
if let Some(ex) = boom.exception {
    println!("Exception: {} ({})", ex.message, ex.class);
    println!("Trace: {}", ex.trace);
}
```

### Async (threads)

```rust
use whynot::process::ProcRuntime;

let h1 = ProcRuntime::call_async_with_cfg(cfg.clone(), "greet".to_string(), vec!["Milton".into()]);
let h2 = ProcRuntime::call_async_with_cfg(cfg.clone(), "add".to_string(), vec![7.into(), 9.into()]);

println!("greet = {:?}", h1.join().unwrap().unwrap().result);
println!("add = {:?}", h2.join().unwrap().unwrap().result);
```

### Async/await (Tokio)

Enable the feature:

```bash
cargo run --example tokio_async --features async_tokio
```

Example:

```rust
#[tokio::main]
async fn main() {
    let cfg = RuntimeConfig::default();

    let greet = whynot::async_tokio::call_async(cfg.clone(), "greet".to_string(), vec!["Milton".into()])
        .await.unwrap();
    println!("greet.result = {:?}", greet.result);
}
```

---

## 📂 Project Layout

```
whynot/
  Cargo.toml
  src/
    lib.rs
    value.rs
    macros.rs
    process.rs
    embedded.rs
    async_tokio.rs
  php/
    runner.php
    bootstrap.php
  examples/
    call_any.rs
    async_calls.rs
    tokio_async.rs
```

---

## 🛠 Roadmap

- [x] Function calls, output capture, exceptions
- [x] Objects serialization
- [x] Includes, eval
- [x] Threaded async
- [x] Tokio async/await
- [ ] Embedded Zend runtime (in‑process)
- [ ] Resource/extension support
- [ ] Automatic Rust ↔ PHP struct mapping
- [x] Publish crate to crates.io

---

## 🤝 Contributing

Pull requests welcome. Please open issues for bugs, feature requests, or questions.