folk-runtime-embed 0.1.17

Embedded PHP runtime for Folk — PHP interpreter runs in-process via FFI
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

# Folk Embed Runtime — Extension Compatibility Matrix

This matrix documents PHP extension compatibility with the Folk embed SAPI (`runtime = "embed"`).

## How to read

| Column | Meaning |
|--------|---------|
| **Load** | Extension loads without crash |
| **Basic** | Basic functionality works |
| **Multi-req** | Works across multiple request cycles |
| **Threads** | Safe with multiple worker threads |
| **Notes** | Known issues or limitations |

Status: ✓ = works, ✗ = fails, ⚠ = works with limitations, — = not tested

## Bundled PHP Extensions

| Extension | Load | Basic | Multi-req | Threads | Notes |
|-----------|------|-------|-----------|---------|-------|
| bcmath | ✓ | ✓ | ✓ | ✓ | Pure computation |
| bz2 | ✓ | ✓ | ✓ | ✓ | |
| calendar | ✓ | ✓ | ✓ | ✓ | Pure computation |
| ctype | ✓ | ✓ | ✓ | ✓ | |
| curl | ✓ | ✓ | ✓ | ✓ | Each thread gets own curl handles |
| date | ✓ | ✓ | ✓ | ✓ | |
| dom | ✓ | ✓ | ✓ | ✓ | libxml2 is thread-safe |
| exif | ✓ | ✓ | ✓ | ✓ | |
| ffi | ✓ | ⚠ | ✓ | ⚠ | User must ensure thread-safety of loaded libs |
| fileinfo | ✓ | ✓ | ✓ | ✓ | |
| filter | ✓ | ✓ | ✓ | ✓ | |
| ftp | ✓ | ✓ | ✓ | ✓ | |
| gd | ✓ | ✓ | ✓ | ✓ | Per-request image resources |
| gettext | ✓ | ✓ | ✓ | ✓ | |
| gmp | ✓ | ✓ | ✓ | ✓ | Pure computation |
| hash | ✓ | ✓ | ✓ | ✓ | |
| iconv | ✓ | ✓ | ✓ | ✓ | |
| intl | ✓ | ✓ | ✓ | ✓ | ICU is thread-safe |
| json | ✓ | ✓ | ✓ | ✓ | |
| ldap | ✓ | ✓ | ✓ | ✓ | Per-connection handles |
| mbstring | ✓ | ✓ | ✓ | ✓ | |
| mysqli/mysqlnd | ✓ | ✓ | ✓ | ✓ | Per-thread connections |
| openssl | ✓ | ✓ | ✓ | ✓ | Thread-safe since OpenSSL 1.1 |
| Zend OPcache | ✓ | ✓ | ✓ | ✓ | SHM shared between workers (read-only) |
| pcntl | ⚠ | ⚠ | ⚠ | ✗ | **fork() conflicts with threads** — do not use |
| pcre | ✓ | ✓ | ✓ | ✓ | |
| pdo | ✓ | ✓ | ✓ | ✓ | |
| pdo_mysql | ✓ | ✓ | ✓ | ✓ | |
| pdo_pgsql | ✓ | ✓ | ✓ | ✓ | |
| pdo_sqlite | ✓ | ✓ | ✓ | ✓ | |
| pgsql | ✓ | ✓ | ✓ | ✓ | |
| phar | ✓ | ✓ | ✓ | ✓ | |
| posix | ✓ | ✓ | ✓ | ✓ | |
| readline | ✓ | — | — | ✗ | Interactive — no use case in embed |
| reflection | ✓ | ✓ | ✓ | ✓ | |
| session | ✓ | ⚠ | ⚠ | ⚠ | File sessions need per-worker paths |
| shmop | ✓ | ✓ | ✓ | ⚠ | Shared memory — needs coordination |
| simplexml | ✓ | ✓ | ✓ | ✓ | |
| soap | ✓ | ✓ | ✓ | ✓ | |
| sockets | ✓ | ✓ | ✓ | ✓ | |
| sodium | ✓ | ✓ | ✓ | ✓ | Thread-safe |
| spl | ✓ | ✓ | ✓ | ✓ | |
| sqlite3 | ✓ | ✓ | ✓ | ✓ | Per-thread database handles |
| standard | ✓ | ✓ | ✓ | ✓ | |
| sysvmsg | ✓ | ✓ | ✓ | ⚠ | System V IPC — shared state |
| sysvsem | ✓ | ✓ | ✓ | ⚠ | System V IPC — shared state |
| sysvshm | ✓ | ✓ | ✓ | ⚠ | System V IPC — shared state |
| tidy | ✓ | ✓ | ✓ | ✓ | |
| tokenizer | ✓ | ✓ | ✓ | ✓ | |
| xml | ✓ | ✓ | ✓ | ✓ | |
| xmlreader | ✓ | ✓ | ✓ | ✓ | |
| xmlwriter | ✓ | ✓ | ✓ | ✓ | |
| xsl | ✓ | ✓ | ✓ | ✓ | |
| zip | ✓ | ✓ | ✓ | ✓ | |
| zlib | ✓ | ✓ | ✓ | ✓ | |

## PECL Extensions

| Extension | Load | Basic | Multi-req | Threads | Notes |
|-----------|------|-------|-----------|---------|-------|
| apcu | ✓ | ✓ | ✓ | ✓ | SHM shared between workers |
| igbinary | ✓ | ✓ | ✓ | ✓ | Serialization — stateless |
| imagick | ✓ | ✓ | ✓ | ✓ | ImageMagick is thread-safe |
| memcached | ✓ | ✓ | ✓ | ✓ | Per-thread connections |
| mongodb | ✓ | ✓ | ✓ | ✓ | Thread-safe driver |
| msgpack | ✓ | ✓ | ✓ | ✓ | Serialization — stateless |
| redis | ✓ | ✓ | ✓ | ✓ | Per-thread connections |
| uuid | ✓ | ✓ | ✓ | ✓ | |
| xhprof | ✓ | ✓ | ✓ | ⚠ | Profiling overhead — disable in production |
| yaml | ✓ | ✓ | ✓ | ✓ | |

### Known Incompatible

| Extension | Status | Reason |
|-----------|--------|--------|
| pcntl | ⚠ Unsafe | `fork()` in threaded process = undefined behavior |
| parallel | ✗ | Own threading model, conflicts with embed workers |
| swoole/openswoole | ✗ | Own event loop and coroutines, conflicts with embed |
| xdebug | ⚠ | Thread-safety issues — use only for debugging, not production |
| pthreads | ✗ | Removed in PHP 8, but historically incompatible |

## Recommendations

1. **Safe for production**: All bundled extensions except pcntl, readline
2. **Database**: Use per-thread connections (PDO/mysqli with `new` per request)
3. **Caching**: APCu and OPcache work great (SHM shared between workers)
4. **Serialization**: msgpack, igbinary — fully thread-safe
5. **Avoid**: pcntl (fork), parallel (own threads), swoole (own event loop)

## Running Tests

```bash
# Full compatibility suite (Docker, all extensions)
docker build -f crates/folk-runtime-embed/compat/Dockerfile -t folk-compat .
docker run --rm folk-compat

# Local (tests whatever extensions are available)
cargo test -p folk-runtime-embed --test extension_compat -- --test-threads=1 --nocapture
```