phplang 0.2.13

PHP as a fusevm frontend: lexer, parser, and compiler to fusevm::Chunk on a PhpHost heap — the first compiled standalone PHP runtime
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
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
```text
██████╗ ██╗  ██╗██████╗ ██╗      █████╗ ███╗   ██╗ ██████╗
██╔══██╗██║  ██║██╔══██╗██║     ██╔══██╗████╗  ██║██╔════╝
██████╔╝███████║██████╔╝██║     ███████║██╔██╗ ██║██║  ███╗
██╔═══╝ ██╔══██║██╔═══╝ ██║     ██╔══██║██║╚██╗██║██║   ██║
██║     ██║  ██║██║     ███████╗██║  ██║██║ ╚████║╚██████╔╝
╚═╝     ╚═╝  ╚═╝╚═╝     ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝
```

![Rust](https://img.shields.io/badge/Rust-2021-05d9e8?style=flat-square)
[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://menketechnologies.github.io/phplang/)
[![Built on](https://img.shields.io/badge/built%20on-fusevm-8a2be2.svg)](https://github.com/MenkeTechnologies/fusevm)
![status](https://img.shields.io/badge/status-active%20%C2%B7%20in%20development-9b5de5?style=flat-square)
![license](https://img.shields.io/badge/license-MIT-ff2a6d?style=flat-square)

### `[PHP, COMPILED TO BYTECODE — ON A SHARED CRANELIFT JIT]`

> *"Zend compiles PHP to its own opcodes and walks them. phplang lowers PHP to a
> shared machine that other languages already run on, and lets a tracing JIT
> compile the hot loops."*

**phplang** is PHP as a [`fusevm`](https://github.com/MenkeTechnologies/fusevm)
frontend — a lexer/parser and compiler that lowers PHP to `fusevm::Chunk`
bytecode running on fusevm's bytecode VM + tracing Cranelift JIT, over a
`PhpHost` object heap. There is no bespoke interpreter loop: phplang is a pure
front end; execution and codegen live in `fusevm` — the same engine behind
[`zshrs`](https://github.com/MenkeTechnologies/zshrs),
[`strykelang`](https://github.com/MenkeTechnologies/strykelang),
[`awkrs`](https://github.com/MenkeTechnologies/awkrs),
[`pythonrs`](https://github.com/MenkeTechnologies/pythonrs), and
[`rubylang`](https://github.com/MenkeTechnologies/rubylang).

It is, to our knowledge, the first compiled standalone PHP runtime. The binary
is `php`.

### [`Read the Docs`]https://menketechnologies.github.io/phplang/ · [`Engineering Report`]https://menketechnologies.github.io/phplang/report.html · [`Builtin Reference`]https://menketechnologies.github.io/phplang/reference.html · [`fusevm`]https://github.com/MenkeTechnologies/fusevm

---

## Table of Contents

- [\[0x00\] Overview]#0x00-overview
- [\[0x01\] Pipeline]#0x01-pipeline
- [\[0x02\] Usage]#0x02-usage
- [\[0x03\] Supported Today]#0x03-supported-today
- [\[0x04\] Not Yet (Later Waves)]#0x04-not-yet-later-waves
- [\[0x05\] Parity Fuzzer]#0x05-parity-fuzzer
- [\[0x06\] Build]#0x06-build
- [\[0x07\] Documentation]#0x07-documentation
- [\[0xFF\] License]#0xff-license

---

## [0x00] OVERVIEW

phplang keeps PHP the language and throws away Zend's execution model. It lexes
and parses PHP (two-mode: inline-HTML passthrough plus `<?php … ?>` code), lowers
the AST to `fusevm` bytecode, and runs it on the shared bytecode VM with a
tracing Cranelift JIT. Arithmetic lowers to native ops so the JIT can trace hot
loops; PHP-specific behavior — loose comparison, string↔number coercion, array
semantics, the standard library — is served by the `PhpHost` object heap.

It carries no VM or JIT of its own. Bug fixes and JIT improvements in `fusevm`
land once and benefit every hosted frontend at the same time.

## [0x01] PIPELINE

```
source ──▶ lexer ──▶ parser ──▶ compiler ──▶ fusevm::Chunk ──▶ fusevm VM + JIT
              │         │           │                                  │
         two-mode   PHP AST    lower to bytecode              callbacks into PhpHost
        (HTML/PHP)            (native ops + CallBuiltin)      (builtins + numeric hook)
```

- **Scalars** (`int`, `float`, `bool`, `string`, `null`) ride through the VM as
  native `fusevm::Value`s.
- **Arrays** are heap objects in `PhpHost`; they travel as `Value::Obj(u32)`
  handles into that heap.
- **Arithmetic** `+ - *` lowers to native fusevm ops so the JIT can trace hot
  loops; a strict **numeric hook** supplies PHP coercion when an operand is a
  string/array/null or an `i64` op overflows. `/ % **`, concatenation,
  comparisons, and everything PHP-specific lower to `CallBuiltin` handlers. The
  hook is the *sited* form, so it can index the running chunk's line table and
  report a warning against the operator's own line.
- **PHP 8 operand rules** are applied by every operator that reads a number. A
  string with no numeric prefix (`"g"`, `""`, `"   "`, `"INF"`) makes the
  operation a `TypeError: Unsupported operand types: string + int`; one that
  merely trails garbage (`"5g"`) raises `Warning: A non-numeric value
  encountered` and continues with its prefix. Operands resolve left before right
  and before each operator's own checks, so `"g" / 0` is a `TypeError` rather
  than a `DivisionByZeroError`.

## [0x02] USAGE

```sh
php script.php              # run a file
php -r 'echo 1 + 1;'        # run a one-liner (no <?php tag needed)
php < script.php            # run a script on stdin
php -a                      # interactive REPL (persistent state per line)
php --dump-bytecode f.php   # print the lowered fusevm bytecode
php --tiers f.php           # run it, then report which fusevm tiers took it
```

The three script entry points name the script differently, and the name is
observable: every diagnostic quotes it and `__FILE__` returns it. A file is its
resolved path, `-r` is `Command line code`, and stdin is `Standard input code` —
the same three names the reference uses.

A `man/php.1` man page and runnable `examples/*.php` ship with the crate.

## [0x03] SUPPORTED TODAY

A working core, grown outward from the sibling frontends. Implemented and tested
end-to-end (see `tests/basic.rs`):

- `<?php … ?>` tags with inline-HTML passthrough; `<?=` short echo; `#`, `//`,
  and `/* */` comments.
- Scalars, single- and double-quoted strings with escapes and the full set of
  interpolation forms — `"$v"`, the simple one-level `"$o->p"` / `"$a[key]"` (where
  an unquoted key is a string, not a constant), the complex `"{$expr}"` for any
  expression, and the legacy `"${v}"`.
- **Heredoc** (`<<<EOT`) and **nowdoc** (`<<<'EOT'`): a heredoc body is the
  double-quoted language minus the `\"` escape (a `"` there needs none), a
  nowdoc body is verbatim to the byte. PHP 7.3's flexible closing delimiter is
  honoured — its indentation is stripped from every body line before anything
  is interpolated, and a line indented less than it is a parse error naming
  that line. Only the exact label closes a body, the newline before the label
  belongs to the delimiter, and the label may be followed by any token.
- Variables, arithmetic (`+ - * / % **`), string concat (`.`), compound
  assignment (`+= .=` …), pre/post `++`/`--`.
- Loose/strict comparison (`== != === !== < > <= >=`, PHP-8 string↔number
  ordering), short-circuit `&& || and or`, ternary `?:` (incl. the elvis short
  form), null-coalesce `??`, the nullsafe operator `?->` (a null receiver
  short-circuits the whole REMAINING CHAIN to null — `$a?->b->c["k"]->d()`
  evaluates no member, no subscript and no argument past the `?->`, while a
  `?->` inside an argument keeps its own extent), `!`, and
  `(int)`/`(float)`/`(string)`/`(bool)` casts. An object with `__toString`
  compared against a string is cast to it first, as `zend_compare` does.
- Computed member names: `$o->$name`, `$o->{expr}` and `$o?->{expr}` for
  property reads and writes, compound assignment, `++`/`--`, `&`, `isset`,
  `unset` and method calls, the name evaluated once, after the receiver.
  `$o->{"x y"}` names a property no bare identifier can spell.
- Indexed, associative, and appended (`$a[] =`) arrays with PHP **value semantics**
  — assigning, passing, returning or storing one hands over a copy (deep through
  nested arrays; an object inside stays a handle), while `$b = &$a` and a `&$x`
  parameter share; index read/write; deep
  and nested lvalues (`$a[b][c] =`, `$a[b][] =`, compound and `++`/`--` on
  elements); the by-reference array mutators (`array_push`/`pop`/`shift`/
  `unshift`/`splice`).
- `if` / `elseif` / `else`, `while`, `do … while`, `for`,
  `foreach ($a as [$k =>] $v)`, `switch` (with fall-through), `break`,
  `continue`, `return`; `match` expressions (a no-arm/no-`default` match throws
  `\UnhandledMatchError`, as PHP 8 does). Each of the six control structures is
  also read in PHP's ALTERNATIVE spelling — `if (…): … endif;`, `endwhile`,
  `endfor`, `endforeach`, `endswitch`, `enddeclare` — including bodies cut in
  half by `?> html <?php`, which is the spelling templates are written in.
- `print` is an operator, not a statement: it writes its operand like `echo` and
  evaluates to the int `1`, so `$r = print "x"` and `var_dump(print $v)` are
  expressions. It binds looser than `=` and tighter than `yield`.
- The three WORD logical operators `and`, `or` and `xor`, at their own precedence
  BELOW assignment — which is the only reason the language has them next to
  `&&`/`||`: `$x = a and b` assigns `a` first. `xor` has no short circuit and
  answers a bool.
- User `function`s with positional, default (`$x = 1`) and variadic (`...$rest`)
  parameters, recursion, argument unpacking at EVERY call site (`f(...$args)`,
  `$f(...$args)`, `$o->m(...$args)`, `C::s(...$args)`, `new C(...$args)`)
  and inside an array literal (`[...$a, ...$b]`, keys renumbered for integers
  and kept for strings), either of which also drives a Generator or a
  Traversable, and
  **named arguments** (`f(name: 1, other: 2)`, mixable with positional, order
  independent, extra names collected into a variadic); anonymous
  `function () use (...) { … }` closures — by value, and by reference with
  `use (&$v)`, which binds the closure's name to the enclosing variable itself —
  and `fn (…) => …` arrow functions.
- **First-class callable syntax** (`strlen(...)`, `$obj->method(...)`,
  `Cls::method(...)`, `$callable(...)`) — each yields a `Closure` that forwards
  its arguments to the referenced function/method.
- **Closure rebinding**: `Closure::bind($fn, $obj, $scope)`, `$fn->bindTo($obj,
  $scope)`, and `$fn->call($obj, …)` rebind `$this` and the private/protected
  access scope; a closure created inside a method auto-binds the current `$this`
  and class scope.
- **Generators** (`yield`): a function whose body contains `yield` returns a
  lazy `Generator` — `yield $v`, `yield $k => $v`, bare `yield`, and `yield from`
  (delegating to an array, `Traversable`, or another generator). The `Generator`
  object supports `current`/`key`/`next`/`valid`/`send`/`throw`/`getReturn` and
  drives `foreach` lazily (side effects interleave; infinite generators work).
  Implemented as host-side stackful coroutines (`corosensei`) — the fusevm VM run
  loop executes on the coroutine's stack, so `yield` suspends it with one stack
  switch and no VM change.
- Classes/OOP: `new`, instance properties and methods, `$this`, constructors
  (with property promotion), **typed properties without a default start
  uninitialized** (absent until written; `var_dump` shows `uninitialized(T)` in
  the declared slot with the type spelled as the engine spells it; a read or
  `++` before the first write is the reference's `Error`, and `__get` answers
  only after an explicit `unset()`), declared properties keep their declared
  slot when written back after `unset()`, a trait's properties follow the
  class's own, class constants, `::class`, static methods/constants,
  `self::`/`parent::` (inside a trait both name the COMPOSING class, and inside
  a closure the class it is bound to — `(function () { return self::K; })->call($o)`
  — both resolved when the code runs), constants inherited from an implemented
  or extended **interface**, **late static binding** (`static::` — `static::class`,
  `new static`, `static::CONST`, `static::$prop`, `static::m()` — resolves to the
  class the call was made on, and `self::`/`parent::`/`static::` calls forward
  it), single inheritance, **interfaces** (`implements`, interface
  `extends`), the **`instanceof`** operator, **traits** (`use Trait;` member
  merging, with `insteadof`/`as` adaptation blocks resolving collisions and
  binding extra names or visibilities — an unresolved collision is a fatal error
  raised when the declaration is reached, as the reference raises it), and
  **anonymous classes** (`new class(args) extends P implements I { … }`, named
  `Base@anonymous` after the parent, else the first interface, else `class`).
  `abstract` classes and interfaces reject direct instantiation
  (`new` on either is a `Cannot instantiate …` error). A class declaration gets the
  reference's compile-time checks before anything runs: a repeated or misplaced
  modifier, a member declared twice, an abstract method outside an abstract
  class, a body that contradicts its modifiers, a non-public interface method, an
  untyped readonly property, and a parameter named twice are each its `Fatal
  error`. A top-level function declared twice or named like a library function
  is `Cannot redeclare`, and a function or class declared inside a block is
  bound when its statement runs, so `function_exists` answers false before then. **References** — `$b = &$a`,
  references to a container slot in either direction (`$r = &$a['x']['y']`,
  `$r = &$o->p`, `$a[] = &$v`, `$o->p = &$v`), return-by-reference
  (`function &f()`), `foreach ($a as &$v)`, by-reference parameters
  (`function f(&$x)`) on every kind of call — a free function, an instance or
  static method, a closure, an arrow function, and a `?->` call that actually
  ran — with a declared scalar type coerced through the reference before the
  body runs (`function f(int &$x)` called with `"5"` leaves the caller's
  variable `int(5)`), and by-reference destructuring targets (`[&$x, $y] = $a`
  in both spellings, keyed, nested, alongside holes, and inside `foreach`, each
  aliasing the subject's element so a write through the target reaches the
  subject), and `&` elements in an array literal (`[&$a]`, `['k' => &$x]`),
  each bound to its variable; a referenced element stays shared across an array
  copy and `var_dump` marks it with `&`, as PHP does.
  Namespaces are accepted in a flat model
  (`namespace X;` / `use A\B\C;`; qualified names fold to their short name).
- The **magic constants** `__LINE__`, `__FILE__`, `__DIR__`, `__FUNCTION__`,
  `__CLASS__`, `__METHOD__`, `__NAMESPACE__` and `__TRAIT__`, resolved where they
  are WRITTEN rather than where the call arrives: `__CLASS__` in an inherited
  method names the class that declared it, and a closure carries the PHP 8.4 name
  `{closure:<scope>:<line>}` built from the scope it was written in (nesting
  composes — `{closure:{closure:f():3}:4}`). The two answers a parse cannot settle
  come from the running frame: `__CLASS__` inside a trait method is the class that
  USED the trait, and inside an anonymous class it is the generated
  `class@anonymous` name `get_class` reports. `__FILE__` is the file the code
  came from: for the main script whatever the entry point named it — a resolved
  path, `Command line code` for `-r`, or `Standard input code` for a script on
  stdin — for included code its resolved path, for `eval()`'d code
  `<file>(<line>) : eval()'d code` — and `__DIR__` falls back to the working
  directory when there is no file. In the flat namespace model
  `__NAMESPACE__` is the declared namespace in full, while class and function
  names stay unqualified.
- **Enums** (PHP 8.1): pure enums (`enum Suit { case Hearts; … }` with
  `Suit::Hearts`, `->name`, `Suit::cases()`, singleton `===` identity) and backed
  enums (`enum Status: string { case Active = 'active'; }` with `->value`,
  `Status::from()`, `Status::tryFrom()`); enums may declare methods and constants
  and satisfy `instanceof UnitEnum`/`BackedEnum`. A case renders as the case, not
  as the object behind it: `enum(Suit::Hearts)` from `var_dump`, `\Suit::Hearts`
  from `var_export`, `Suit Enum:string ( … )` from `print_r`, its backing value
  from `json_encode` (a pure enum fails the encode with
  `JSON_ERROR_NON_BACKED_ENUM`), and `E:12:"Suit:Hearts";` from `serialize`,
  which `unserialize` resolves back to the very same singleton.
- Exceptions: `throw` as a statement and a PHP-8 expression (`$x ?? throw …`),
  `try` / `catch (A | B $e)` / `finally` with `finally`-always semantics (it runs
  on return, throw, break, and continue out of the guarded body), a built-in
  exception hierarchy (`Exception`/`Error` disjoint roots under `Throwable`, plus
  `RuntimeException`, `LogicException`, `InvalidArgumentException`, `TypeError`,
  `ValueError`, `UnhandledMatchError`, `DivisionByZeroError`) that user classes
  can subclass, and `getMessage()`/`getCode()`/`getPrevious()`/`__toString()`.
- **Diagnostics.** Every diagnostic is written TWICE, under two independent ini
  flags, exactly as the reference writes it: `display_errors` puts the copy the
  program sees on *stdout*, interleaved with its output and inside any open
  `ob_start` buffer, and `log_errors` puts a `PHP `-prefixed copy on *stderr*.
  Both default on; `-d display_errors=0` leaves only the stderr copy and
  `-d log_errors=0` only the stdout one. A fatal and a parse error are not
  exempt from either, nor from the `error_reporting` mask — `php -d
  error_reporting=0` runs an uncaught exception to completion in silence and
  still exits 255. `trigger_error` raises a real diagnostic through the same
  path, so it obeys all three gates, rejects a level that is not one of the four
  `E_USER_*` with the reference's `ValueError`, and ends the request on
  `E_USER_ERROR`. The diagnostics themselves cover undefined
  variables, array keys and properties, array offsets on a non-array, string
  offsets past the end, the `++`/`--` cases that have no effect, and PHP 8.2's
  `Creation of dynamic property C::$p is deprecated`. `isset()`, `empty()` and
  `??` read in PHP's isset mode and stay silent, as do writes, auto-vivification
  and by-reference arguments — an unset variable passed to `sort` or
  `array_push` binds as null without a warning, and the refusal is the
  `TypeError` for that null. `@` is separate and dynamic: the operand is
  evaluated normally and every diagnostic raised while it runs is dropped,
  including those raised from inside the library functions it calls
  (`@preg_match('/[a', $s)`). Which of them are
  *displayed* is the `error_reporting` mask, writable by `error_reporting()`,
  `ini_set('error_reporting', …)`, or `php -d error_reporting=…`. Only the `-d`
  path runs the php.ini constant-expression scanner, so `E_ALL & ~E_DEPRECATED`
  is understood there and reads as plain integer `0` through `ini_set` — the
  reference behaves the same way.
- **Compile-time notices** are raised while the source is READ, so they precede
  every byte the program writes and fire whether or not the code carrying them
  runs — `Using ${var} in strings is deprecated, use {$var} instead` is the one
  PHP 8.2 added. A run-time `error_reporting(0)` cannot retract one; only the
  startup level (`-d`) applies.
- **Attributes** (`#[Attr]`, `#[Ns\\Attr(1, [2])]`) parse everywhere a
  declaration can carry them — class, function, method, property, class constant,
  enum case, parameter. `#[AllowDynamicProperties]` is honoured, and inherited by
  subclasses.
- **Library argument errors throw.** A standard-library function given arguments
  it rejects raises the catchable exception PHP raises — `ValueError`,
  `DivisionByZeroError` — with the library call itself as frame `#0` of the trace
  (`#0 <file>(<line>): range(9, 10, 2)`), and a `#[\\SensitiveParameter]`
  argument masked as `Object(SensitiveParameterValue)` exactly as PHP masks it.
- **Property overloading** — `__get`, `__set`, `__isset` and `__unset` fire for a
  property the object does not carry, whether because no class declared it,
  because it was `unset`, or because its visibility puts it out of reach of the
  reading scope. They are consulted BEFORE the access error, so a class defining
  them never reports `Cannot access private property`. A magic method is not
  re-entered for the property it is already handling, so `__get($n) { return
  $this->$n; }` terminates. The four questions PHP asks differently are all
  distinguished: `isset()` asks `__isset` alone, `empty()` and `??` follow a true
  `__isset` with `__get` (and `??` falls back to `__get` when there is no
  `__isset`, where `empty()` does not), and a plain read asks `__get`.
- **Property access errors throw.** Reading, writing or unsetting an out-of-reach
  property raises a catchable `Error: Cannot access private property C::$x`
  naming the class that DECLARED it, rather than aborting the process. `isset()`
  never throws — asking is always allowed.
- **Method overloading** — `__call` and `__callStatic` catch a call to a method
  the class does not declare *or* cannot reach, receiving the name plus one array
  of the arguments. The instance and static forms are distinct: a class with only
  `__call` does not answer `C::m()`. Every call form routes through them,
  including `call_user_func([$o, 'm'])`, so `is_callable([$o, 'm'])` is true for
  a name only the catch-all handles while `method_exists` stays false.
- **`__invoke`** makes every instance of the declaring class callable, and it is
  recognized wherever a callable is: `$obj(…)`, `is_callable($obj)`, and any
  builtin taking a callback (`array_map`, `usort`, `array_filter`,
  `Closure::fromCallable`). One decoder in `host::call_value` reads every callable
  form — closure handle, `"function"`, `"C::m"`, `[$obj, "m"]`, `["C", "m"]`, and
  an `__invoke` object — so no two call sites can disagree about what is callable.
- **Call errors throw.** `Call to undefined method C::m()`, `Call to undefined
  function f()` and `Call to private method C::m() from global scope` are all
  catchable `Error`s, with the trace starting at the call site (no frame is
  invented for the callee that does not exist).
- **`ArrayAccess`** — `$o[k]`, `$o[k] = v`, `$o[] = v`, `isset($o[k])` and
  `unset($o[k])` dispatch to `offsetGet`/`offsetSet`/`offsetExists`/`offsetUnset`
  on any class implementing it. `isset()` asks `offsetExists` and nothing else;
  `??` follows a true `offsetExists` with `offsetGet`. **`Countable`** backs
  `count()`, which rejects anything else with the reference's `TypeError` rather
  than answering 1. The SPL prelude classes declare both, so `$fixedArray[0]`,
  `$arrayObject['k']` and `count($storage)` work through the ordinary syntax.
- **`Stringable`** is implied by `__toString`, whether or not a class names the
  interface, exactly as PHP 8 implies it.
- **Closures and generators are objects.** A closure is an instance of `Closure`
  and a generator one of `Generator` to `is_object`, `get_class`, `::class`,
  `get_debug_type`, `instanceof`, `is_a`, `is_subclass_of`, `method_exists`,
  `get_object_vars` and every diagnostic that names a value's type — and
  `$gen instanceof Iterator` / `Traversable` is true, through an engine ancestry
  table rather than a class declaration. `Closure` is also the one class the
  reference gives an identity-only `==`.
- **`class_exists`/`interface_exists`/`trait_exists`/`enum_exists` each answer
  for ONE declaration kind**: an `interface I {}` makes `interface_exists('I')`
  true and `class_exists('I')` false, while an enum is both an enum and a class.
  The engine's own types answer too — `Closure` and `Generator` as classes,
  `Traversable`, `Iterator`, `IteratorAggregate`, `Countable`, `ArrayAccess`,
  `Stringable`, `JsonSerializable`, `Throwable`, `UnitEnum` and `BackedEnum` as
  interfaces. `class_implements` and `class_uses` report the real lists.
- **`__toString`** is invoked wherever a value becomes a string: `echo`, `print`,
  `.` concatenation, interpolation, the `(string)` cast / `strval`, `implode`'s
  elements, and the library functions whose parameters PHP declares as `string`.
- Integer literals in every base (`0xFF` hex, `0755`/`0o17` octal, `0b101` binary,
  `1_000` separators); predefined constants (`PHP_INT_MAX`, `PHP_EOL`, `M_PI`, the
  `SORT_*`/`FILTER_*`/`JSON_*`/… flag families) plus `define`/`defined`/`constant`
  and the `const NAME = expr, …;` declaration (top-level, as PHP's grammar has
  it — a redefinition through either spelling warns and keeps the first value);
  and superglobals (`$_SERVER`, `$_ENV`, `$_GET`/`$_POST`/…, `$GLOBALS`, `$argv`/
  `$argc`) auto-global across every scope.
- **`include` / `require` / `include_once` / `require_once` and `eval()`**:
  the loaded file or code is compiled when the construct runs and executes in
  the CURRENT scope, its functions and classes becoming global. The construct
  evaluates to the code's `return` value (`1` for a file that returns nothing,
  null for `eval`), a repeated `_once` to `true`, a failed `include` to `false`
  after the reference's two warnings, and a failed `require` throws `Error`. A
  syntax error in loaded code throws `ParseError` (reported as `Parse error:` if
  uncaught). Loaded code names its own file in diagnostics, exception
  `getFile()`, `__FILE__`/`__DIR__` and stack traces, where each include or eval
  is a frame of its own (`#1 main.php(3): include('/path/to/f…')`).
  `get_included_files()` lists what was loaded.
- **Stream resources**: `fopen` on files and on `php://memory`, `php://temp`,
  `php://stdin`/`stdout`/`stderr`/`output`, `tmpfile()`, and the `STDIN`/
  `STDOUT`/`STDERR` constants. A resource is numbered as the reference numbers
  it (the standard streams 1–3, the first stream a script opens 5, numbers never
  reused) and renders as it does everywhere — `var_dump`'s
  `resource(5) of type (stream)`, `Resource id #5`, `gettype`, `(int)`, array
  keys, comparisons — including after `fclose`, when it is of type `Unknown`.
  `feof` answers whether a read came up short, seeking past the end and writing
  there zero-fills, append modes append, and the stream functions refuse a
  non-resource or a closed stream with the reference's `TypeError`.
- The `DateTime`/`DateTimeImmutable`/`DateInterval` classes and the SPL data
  structures (`SplStack`, `SplQueue`, `SplDoublyLinkedList`, `SplFixedArray`,
  `ArrayObject`, `SplObjectStorage`, `SplPriorityQueue`, `SplMinHeap`/`SplMaxHeap`)
  plus `stdClass`, all as PHP preludes; output buffering (`ob_start`/`ob_get_clean`/…),
  variadic introspection (`func_get_args`/`func_num_args`), the stream functions
  (`fread`/`fwrite`/`fgets`/`fgetc`/`fseek`/`ftruncate`/`fstat`/`fclose`/…), the
  `unset()` construct, `spl_object_id`,
  and the `@` error-suppression operator.
- **`exit` / `die`** — the request ends where they stand. Parentheses and the
  argument are both optional; an int becomes the process exit status (modulo
  256, so `exit(300)` leaves 44 and `exit(-1)` leaves 255), a string is printed
  and the status is 0, a bool or float narrows, an explicit null is deprecated,
  and anything else is a `TypeError`. The unwind is not catchable and does not
  run a `finally`, but open output buffers still flush. PHP 8.4 also registered
  them as callable functions, so `function_exists("exit")` is true and
  `$f = "exit"; $f(3);` works.
- A large standard library (see the
  [builtin reference]https://menketechnologies.github.io/phplang/reference.html
  for the current surface — it is generated from the same corpus a test pins to
  the runtime's registration tables, so it cannot drift), incl. bcmath and gmp
  arbitrary precision, split into category modules under `src/stdlib/` and
  consulted through a per-category dispatch chain:
  - **strings** — `str_*`, `substr*`, `strpos`/`stripos`/`strrpos`, `strstr`,
    `strtr`, `sprintf`/`vsprintf`/`sscanf`, `number_format`, `nl2br`,
    `addslashes`, `str_rot13`, `similar_text`, `levenshtein`, `mb_*`, …
  - **arrays** — `array_map`/`filter`/`reduce`/`merge`/`slice`/`column`/`chunk`,
    the `sort`/`usort`/`natsort` families, `array_diff`/`intersect` (+`_key`/
    `_assoc`), `compact`/`extract`, the internal-pointer family, …
  - **math** — `abs`/`floor`/`ceil`/`round`/`sqrt`, full trig + hyperbolic +
    inverse, `hypot`/`fdiv`/`fmod`, base conversions (`dec*`/`*dec`/`base_convert`),
    `rand`/`mt_rand`/`random_int`.
  - **ctype** — the `ctype_*` predicates. **types** — `is_*`, `gettype`,
    `get_debug_type`, `serialize`/`unserialize`, `var_dump`/`print_r`/`var_export`.
    Objects render in full: `print_r` annotates a non-public property
    (`[b:protected]`, `[c:P:private]`), `var_export` emits
    `\P::__set_state(array( … ))` (`(object) array( … )` for a `stdClass`), and
    `serialize` mangles the property keys the way the engine stores them
    (`"\0*\0b"`, `"\0P\0c"`). `unserialize` restores an object WITHOUT running its
    constructor, turns an unknown class into `__PHP_Incomplete_Class`, and
    reproduces the reference's diagnostics — including the byte offset it blames
    and the "Extra data" case, where trailing bytes warn but keep the value.
  - **preg** — `preg_match`/`match_all`/`replace`/`replace_callback`/`split`/
    `quote`/`grep` (byte-mode by default, Unicode with `/u`). Look-around,
    backreferences, atomic groups and possessive quantifiers all work: a pattern
    the `regex` crate will not compile is retried on `fancy-regex`. `$matches` is
    a real by-reference OUT parameter, so it defines the caller's variable
    whether or not it existed, and a `(?<name>…)` group appears under its name as
    well as its index.
  - **datetime** — `time`/`mktime`/`date`/`gmdate`/`checkdate`/`strtotime` (UTC).
  - **hash** — `md5`/`sha1`/`hash`/`crc32`/`hash_hmac`. **encoding** —
    `base64_*`, `bin2hex`/`hex2bin`, quoted-printable, `utf8_*`. **url** —
    `urlencode`/`rawurlencode` (+decode), `http_build_query`, `parse_url`,
    `parse_str` (with the `PHP_URL_*` component selectors).
  - **json** — `json_encode`, `json_decode` (objects to `stdClass`, or to arrays
    under `$associative` / `JSON_OBJECT_AS_ARRAY`; oversized integers as strings
    under `JSON_BIGINT_AS_STRING`), `json_validate`, `json_last_error`(`_msg`) with
    every `JSON_ERROR_*` code, and the encode flags through
    `JSON_PARTIAL_OUTPUT_ON_ERROR` and `JSON_PRESERVE_ZERO_FRACTION`. **filter**
    — `filter_var` (`VALIDATE_INT`/`FLOAT`/`BOOLEAN`/`EMAIL`/`URL`/`IP`/`DOMAIN`/
    `REGEXP`, `SANITIZE_*`). **mbstring** — `mb_str_split`, `mb_convert_case`,
    `mb_strpos`/`rpos`, `mb_ord`/`chr`, `mb_convert_encoding`, `mb_detect_encoding`.
  - **fileio** — `file_get_contents`/`put_contents`, `file`, `readfile` (all of
    which also take `php://` URLs), and the path-level file ops
    (`file_exists`, `is_file`/`dir`, `unlink`, `mkdir`, `scandir`, `copy`,
    `basename`/`dirname`/`pathinfo`, `realpath`, `getcwd`, …).
  - **reflection** — `class_exists`, `method_exists`, `property_exists`,
    `get_class`, `get_parent_class`, `get_object_vars`, `get_class_methods`,
    `class_parents`, `is_a`/`is_subclass_of`. **callable** — `call_user_func`(`_array`)
    (incl. array/`Class::method` callables), `function_exists`. **misc** —
    `strnatcmp`/`strnatcasecmp`, `soundex`, `str_getcsv`, `array_walk_recursive`,
    `array_find`/`array_any`/`array_all`, `array_udiff`/`array_multisort`.
  - **system** — `getenv`/`putenv`, `phpversion`, `php_sapi_name`, `php_uname`,
    `getmypid`, `extension_loaded`, `get_defined_constants`, `get_declared_classes`.

## [0x04] NOT YET (LATER WAVES)

True (non-flat) namespaces with `as` alias remapping. A few current deviations,
documented in-code:

- Only a SCALAR type declaration is enforced — `int`, `float`, `string`, `bool`
  and their `?` nullable forms, on a parameter or a return. Every other type is
  parsed and carried but checks nothing: a union (`int|string`), an intersection,
  a class name, `array`, `iterable`, `callable`, `mixed`, `object`, and the
  return-only `void`/`never`/`static`. A value that would not satisfy one of
  those passes through where the reference raises a `TypeError`.
- `declare(strict_types=1)` is whole-program rather than per-file: the main
  script's declaration sets the mode for every call, and one in an `include`d
  file or `eval()`'d code is ignored. Upstream reads the mode from the file
  containing the CALL, so a strict included file calling into a non-strict one
  still checks strictly there; phplang does not.
- A callback invoked BY a library function (`array_map`, `usort`) is checked in
  whatever mode the program declared. Upstream treats an internal caller as
  having no strict-mode file and so coerces, while `call_user_func` forwards the
  caller's mode; phplang forwards it in both cases.
- The UNCAUGHT rendering of a parameter/return `TypeError` names the CALL site
  where the reference names the function's DEFINITION — `in file:9` rather than
  ` and defined in file:2` — because no definition line is recorded for a
  function. `getMessage()` itself is byte-exact, which is what a `catch` sees.
- Default parameter values are not restricted to constant expressions, and a
  default is not checked against the parameter's declared type (upstream checks
  it once, at declaration).
- The by-reference OUT parameter is implemented for `preg_match`/
  `preg_match_all`/`preg_replace`(`_callback`)/`parse_str`/`similar_text`/
  `str_replace`/`settype`/`array_multisort` and not for the rest of the library
  — `sscanf`'s trailing arguments are the one that remains, so
  `sscanf($s, "%d %s", $a, $b)` returns the parsed array where the reference
  returns the count and fills `$a`/`$b`. The two-argument form is exact.
- An argument that cannot supply a by-reference binding is refused where the
  callee is NAMED — a free function or a library function — with the reference's
  `Error: f(): Argument #1 ($a) could not be passed by reference`, and a call's
  temporary with its `Notice: Only variables should be passed by reference`. A
  METHOD, a closure and a `$f(…)` call reach a callee only the run knows, and
  those still bind a literal silently.
- A diagnostic names the *statement's* line. PHP names the line of the
  expression, so a statement spanning several lines reports its first.
- A `preg_*` pattern the REFERENCE also rejects reproduces its `Warning` and its
  `preg_last_error()` state. **Pattern RECURSION is the one construct that now
  compiles and answers WRONGLY rather than failing**: `preg_match('/\((?:[^()]|
  (?R))*\)/', '(a(b))')` matches in both engines, but the reference captures
  `(a(b))` where this one captures `(b)`. There is no diagnostic to copy and no
  error sentinel to return — the answer is simply not the reference's, which
  makes it the most dangerous shape a gap can take. Conditional groups
  (`(?(1)…|…)`), look-around, backreferences, atomic groups and possessive
  quantifiers all match the reference.
- A pattern that only the `fancy-regex` engine will take matches as if `/u` were
  set, because that engine works over `&str`: `.` is one codepoint rather than
  one byte. This is visible only for a NON-ASCII subject, and only for a pattern
  the byte engine already refused.
- A **syntax error** reproduces PHP's `unexpected <token>` text but not the
  `, expecting "X" or "Y"` clause that often follows it: the expected set comes
  out of PHP's generated LALR tables, not the grammar as written here.
- `var_dump`'s `#N` object number and `spl_object_id` agree with each other, but
  PHP reuses a freed object's number and phplang's arena never frees, so the two
  agree only until an object becomes unreachable.
- `ini_get`/`ini_set` know PHP core plus `date` and `pcre` — the two extensions
  PHP 8 cannot be built without — at the values the reference reports for them
  with no php.ini loaded. A name belonging to an optional extension, or one whose
  default is the build's install prefix (`extension_dir`), reads back `false`
  rather than a machine-specific guess. `ini_set` does not model per-setting
  VALUE validation: the reference refuses `ini_set('memory_limit', '20')` with a
  message quoting its live memory usage, which is not a reproducible number.

Persistent bytecode caching and AOT (`--build`) —
present in the sibling frontends — are not wired yet; an LSP server (`--lsp`) and
a DAP debug adapter (`--dap`, with source-line and function breakpoints, stepping,
call stack, locals, and expression `evaluate`) are.

## [0x05] PARITY FUZZER

`parity-fuzz` is a differential fuzzer: it generates seed-deterministic PHP
snippets, runs each through both the reference `php` and phplang, and reports
every case where **stdout, stderr or the exact exit code** differs. It is a
development tool — it needs a reference `php` on `PATH`, so CI never runs it.
Neither side is run with `error_reporting` turned down: PHP writes
`Warning`/`Deprecated`/`Fatal error` to stdout *and* a `PHP `-prefixed copy to
stderr, so both copies are part of what is compared.

All three observables are compared because each omission was a blind spot
rather than a decision. stderr used to be piped to `/dev/null`, which made the
harness structurally incapable of reporting a stderr-only divergence however
many cases it ran; the exit code used to be compared only as zero-vs-nonzero,
which made `exit(3)` and `exit(9)` the same answer.

```sh
cargo build --bin parity-fuzz
./target/debug/parity-fuzz --count 5000            # fuzz 5000 cases
./target/debug/parity-fuzz --count 500 --mode enums   # 500 cases of ONE mode
./target/debug/parity-fuzz --once --seed 1234         # replay one case, both sides
```

`--mode NAME` generates that mode's cases rather than filtering the rest away,
so `--count 500 --mode enums` compares 500 enum programs. A divergence prints
the case SEED, which `--once --seed <it>` rebuilds exactly; add the same
`--mode` when the run that found it was filtered. `PHPLANG_FUZZ_PHP` pins the
oracle and is refused unless it is a reference PHP — pointing it at phplang
would compare the binary under test against itself and report a clean sweep.

Generators are biased toward where a PHP frontend is likely to disagree with the
reference: float formatting, integer division/modulo signs, `**` precedence,
loose-vs-strict comparison, `sort` ordering, `sprintf`/`number_format`, and
string↔number coercion, and the PCRE constructs the `regex` crate lacks.
Divergences are delta-debugged to a minimal reproducer and grouped by signature;
a full report lands in `target/parity-fuzz/divergences-<pid>.txt`, named for the
run so concurrent invocations against one checkout cannot overwrite each other.

The exit status answers *did this run measure what it was asked to*, not merely
*did it find a disagreement*. A run exits non-zero when no cases ran, when every
case that ran was skipped (the reference timing out on all of them), when a case
reached a worker and produced no verdict, or when a case agreed only because the
reference printed nothing. Each is named in a closing `RUN NOT CLEAN` line, and
the summary reports the skipped and barren counts even at zero — a clean number
is only evidence if those are visible next to it.

A clean run over the existing modes proves nothing about a construct no
generator emits, and that is where the divergences have actually been. Before
picking a target, cross-reference the generator modes against the registered
library surface:

```sh
# every registered builtin that no generator mode ever emits
grep -rhoE '"[a-z_][a-z0-9_]{2,}"' src/stdlib/*.rs src/builtins.rs | tr -d '"' \
  | sort -u | while read f; do
      php -r "exit(function_exists('$f')?0:1);" &&
        ! grep -q "$f" src/bin/parity_fuzz.rs && echo "$f"
    done
```

Round 7 found `json_decode`, `ctype_*`, `parse_url`, `strip_tags`, `__invoke`,
`compact`, `md5` and `base64_*` on that list, and every one of them was carrying
a bug. Round 8 found `sscanf`, `addcslashes`, `count_chars`, `strtok`,
`substr_compare` and the array forms of `substr_replace` on it, with the same
result. Round 10 ran the same test over the SYNTAX instead of the library — a
grep for `<<<`, `yield`, `enum `, `trait `, `...` and a `?->` past the first
link returned zero hits over the generators — and every one of those six was
carrying a bug too, `<<<` not being implemented at all. Round 11 repeated it and
found `endif`/`endwhile`/`endfor`, `clone`, `__call`, `get_class`, `is_a(`,
`class_exists` and `func_get_args` at zero: the entire alternative control-
structure syntax was a parse error, and the reflection surface did not know a
closure was an object. A curated corpus cannot report a construct nobody
captured, so a mode should be added for the family FIRST and the fix written
against what it reports.

Sampling the corpus is itself easy to get wrong. The mode is chosen from
`seed >> 7`, so consecutive seeds share one — seeds `1..6000` reach only the
first 47 of the 82 modes, and a survey over them will report every later mode's
constructs as absent. Sample per mode instead:

```sh
for m in $(perl -ne 'print "$1\n" if /name: "([a-z0-9_]+)",/' src/bin/parity_fuzz.rs); do
  seq 1 60 | xargs -P 12 -I{} target/debug/parity-fuzz --once --mode "$m" --seed {} \
    | perl -ne 'if(/^prog  : /){$p=1; s/^prog  : //} elsif(/^oracle: /){$p=0} print if $p'
done > corpus.txt
```

A clean divergence count only means something alongside the two numbers printed
under it. `skipped` counts cases that never reached a comparison — the reference
timed out, or either side failed to run — because a mode whose programs all time
out on the reference would otherwise report zero divergences forever. `barren`
counts cases where both sides agreed only by failing with nothing on stdout:
those ran and matched, but prove nothing about the behaviour they were written
to exercise, and two *different* failures are indistinguishable there. A run is
worth quoting when both are `0`.

## [0x06] BUILD

```sh
cargo build
cargo test
```

phplang is a standalone crate (an explicit empty `[workspace]` stops cargo
walking up to the meta parent). `fusevm` is pulled from crates.io with the `jit`
feature.

## [0x07] DOCUMENTATION

- **Docs hub** — <https://menketechnologies.github.io/phplang/>
- **Builtin reference** — <https://menketechnologies.github.io/phplang/reference.html>
- **Engineering report** — <https://menketechnologies.github.io/phplang/report.html>
- **fusevm** — <https://github.com/MenkeTechnologies/fusevm> (the shared VM)
- **Source** — <https://github.com/MenkeTechnologies/phplang>

## [0xFF] LICENSE

MIT — free and open source. See [LICENSE](LICENSE).