docs(backend): add backend-neutral IR design document

- Document recommended pipeline from PHP Parser AST to backend-specific code generation - Define Bound AST structure preserving PHP syntax shape with resolved semantic information - Specify PHP Semantic IR close to PHP runtime semantics with suggested instruction families - Outline Runtime ABI operations for consistent
2 months ago · fc5ad87f55
parent 441091fbc5
commit fc5ad87f55
1 changed files with 307 additions and 0 deletions
--- a/docs/BACKEND_NEUTRAL_IR.md
+++ b/docs/BACKEND_NEUTRAL_IR.md
@ -0,0 +1,307 @@
 # Backend-Neutral IR for C++, WASM and JavaScript
 TypePHP currently lowers PHP AST directly to C++ code. This works for the
 current C++/Zend backend, but it couples PHP semantic analysis, temporary value
 management, reference behavior, runtime calls and C++ code formatting in one
 stage.
 If TypePHP needs to support targets such as WASM or JavaScript, the compiler
 should introduce a backend-neutral semantic IR before backend-specific code
 generation.
 ## Recommended Pipeline
 ```text
 PHP Parser AST
    -> Bound AST
    -> PHP Semantic IR
    -> Backend Lowering
        -> C++/Zend Runtime IR -> C++
        -> JavaScript Runtime IR -> JS
        -> WASM Runtime IR -> wasm/wat/import calls
 ```
 The important rule is that the semantic IR must describe PHP behavior, not C++
 implementation details.
 It should not contain:
 - `php::Var`
 - `php::Ref`
 - `php::Array`
 - `zend_*`
 - `zval*`
 - C++ expression fragments
 Those belong to the C++ backend only.
 ## Bound AST
 The Bound AST should preserve PHP syntax shape while attaching resolved semantic
 information.
 It should contain:
 - Resolved names for functions, classes, methods, properties and constants.
 - Scope information for locals, globals, statics and closure captures.
 - Declared and inferred types.
 - By-reference information for parameters, returns and assignments.
 - Call target classification: AOT function, native call, internal function,
  dynamic call or unsupported target.
 - L-value and R-value classification for reads, writes, `isset`, `unset` and
  reference access.
 - Target capability diagnostics, such as whether `eval`, `include`, resources or
  reflection are allowed for the selected backend.
 Most unsupported syntax should be rejected in this phase or during IR
 validation, not during backend code generation.
 ## PHP Semantic IR
 The semantic IR should be close to PHP runtime semantics. It should not be too
 low-level at first, because PHP references, arrays, dynamic calls and exception
 flow are difficult to recover after early lowering.
 Example:
 ```text
 %value = load_local $value
 %class = load_local $name
 %ok = instanceof %value, %class
 return %ok
 ```
 For a more complex expression:
 ```text
 %services = load_prop this, "services"
 %closure = make_closure closure#1 captures [$name]
 %filtered = call_func "array_filter", [%services, %closure, ARRAY_FILTER_USE_BOTH]
 %values = call_func "array_values", [%filtered]
 %result = coalesce_dim %values, 0, null
 return_checked %result, ?object
 ```
 Suggested instruction families:
 - `LoadLocal`, `StoreLocal`
 - `LoadGlobal`, `StoreGlobal`
 - `LoadProp`, `StoreProp`, `PropRef`
 - `LoadDim`, `StoreDim`, `DimRef`
 - `CallFunc`, `CallMethod`, `CallStatic`
 - `NativeCall`
 - `MakeClosure`
 - `InstanceOf`
 - `Isset`, `Empty`, `Coalesce`
 - `Cast`, `TypeCheck`, `TypeAssert`
 - `ToReferenceExact`
 - `Return`, `ReturnRef`, `ReturnChecked`
 - `Throw`, `TryCatchFinally`
 - `Branch`, `Jump`, `Label`
 - `ForeachInit`, `ForeachNext`
 - Explicit unsupported nodes for `eval`, `include`, `resource` operations and
  other target-dependent features.
 ## Runtime ABI
 Multiple backends should implement the same PHP semantic runtime ABI.
 Example ABI operations:
 ```text
 rt_call_function(name, args)
 rt_call_method(receiver, method, args)
 rt_call_static(class, method, args)
 rt_get_property(object, name)
 rt_set_property(object, name, value)
 rt_get_property_ref(object, name)
 rt_get_dim(value, key)
 rt_set_dim(value, key, value)
 rt_get_dim_ref(value, key)
 rt_to_bool(value)
 rt_instanceof(value, class_name)
 rt_make_reference(value)
 rt_deref(value)
 rt_throw(value)
 ```
 The C++ backend can map these operations to the existing `php::Var`, `php::Ref`
 and Zend-based runtime. JavaScript and WASM can map them to their own runtime
 representations.
 ## Value Model
 The IR should use abstract value identities instead of physical backend types.
 Useful concepts:
 - `ValueId`
 - `RefId`
 - `ArrayId`
 - `ObjectId`
 - `ClassId`
 - `FunctionId`
 - `CallableId`
 - `ExceptionId`
 The backend decides how these are represented. For example:
 - C++/Zend can use `php::Var`, `php::Ref`, `zval*` and `zend_class_entry*`.
 - JavaScript can use tagged JS objects and boxed references.
 - WASM can use handles and runtime imports.
 ## Semantics That Must Stay Explicit
 The following PHP semantics must remain explicit in the Bound AST or semantic
 IR. They should not be lowered too early:
 - `isset` is not the same as a normal read.
 - `empty` is not just `!toBool(value)`.
 - `??` uses `isset` semantics, not only null comparison.
 - `foreach` by value and by reference are different.
 - Return by reference must be represented as `ReturnRef`.
 - Call-by-reference arguments must preserve reference slots.
 - Array element and object property references must use explicit `DimRef` and
  `PropRef` operations.
 - PHP arrays are ordered maps, not native JS arrays or C++ vectors.
 - Object property visibility and typed property checks are runtime semantics.
 - Dynamic calls must preserve symbol lookup behavior.
 - `eval`, `include`, resources, reflection and extension-dependent behavior must
  be explicit so each backend can accept, reject or emulate them.
 ## Target Capability Matrix
 Each backend should declare a feature set. The compiler should validate IR
 against the selected target before code generation.
 Example:
 ```text
 Feature                C++/Zend     JavaScript       WASM
 function call          yes          yes              yes
 class/object           yes          partial          partial
 array COW              Zend         runtime          runtime
 reference              Zend         boxed refs       boxed refs
 internal PHP funcs     yes          shim/import      import
 resource               yes          no/partial       no
 eval/include           partial      no/partial       no
 reflection             yes          partial          no/partial
 extension classes      yes          shim             no
 ```
 This should be represented in code as target capability metadata, for example:
 ```text
 target: cpp-zend | js | wasm
 ```
 Unsupported behavior should produce deterministic diagnostics in the validation
 phase.
 ## JavaScript Backend Notes
 JavaScript is a practical first non-C++ backend because it is dynamic and can
 host a PHP-like runtime in user space.
 Main runtime requirements:
 - PHP array as ordered map.
 - PHP references as boxes.
 - PHP object/class model with visibility checks.
 - PHP weak typing and cast helpers.
 - PHP exception model.
 - Closure capture semantics.
 - Dynamic function, method and static method calls.
 - Binary-safe string representation, because JS strings are not byte strings.
 - Integer handling policy, because JS numbers are doubles.
 The initial JS backend should target a strict PHP subset before trying to support
 resources, reflection, extensions, `eval` or real stream behavior.
 ## WASM Backend Notes
 WASM is less suitable for directly expressing dynamic PHP semantics. It should be
 planned as a runtime-backed target.
 Possible routes:
 1. PHP -> C++ -> WASM
   This is the shortest path and reuses the current C++ backend, but Zend
   embedding is heavy and many OS/resource features are limited in WASM
   environments.
 2. PHP Semantic IR -> WASM + runtime imports
   This is cleaner but more expensive. The generated WASM should call imported
   runtime functions for dynamic PHP operations such as arrays, objects,
   references and dynamic calls.
 The second route is preferable long term. The first route may be useful for an
 early proof of concept.
 ## Migration Strategy
 Do not rewrite the whole compiler at once.
 Recommended steps:
 1. Introduce target capability metadata.
 2. Add Bound AST metadata without changing existing C++ output.
 3. Add semantic IR data structures and `--dump-ir`.
 4. Lower a small expression subset to IR first.
 5. Implement `Semantic IR -> C++` for that subset.
 6. Keep mixed mode: unsupported IR nodes can temporarily fall back to the old
   direct AST-to-C++ path.
 7. Gradually migrate high-risk constructs:
   - `??`
   - ternary
   - `instanceof`
   - nullsafe access
   - function, method and static calls
   - `return`
   - `foreach`
   - `try/catch/finally`
   - reference assignment and return-by-reference
 The current `beforeStmtLines` and `afterStmtLines` mechanism should eventually
 be replaced by explicit IR instruction ordering. This avoids hidden side effects
 inside expression parsing and prevents formatting or comment text from changing
 generated program behavior.
 ## Testing Strategy
 Add IR snapshot tests in addition to PHPT output tests.
 Example:
 ```text
 --IR--
 function main(): void
  %0 = load_local $value
  %1 = load_local $name
  %2 = instanceof %0, %1
  return %2
 ```
 This separates frontend semantic correctness from backend code generation
 correctness.
 Recommended test categories:
 - PHP AST -> Bound AST diagnostics.
 - Bound AST -> Semantic IR snapshots.
 - Semantic IR -> C++ output behavior.
 - Target capability rejection tests.
 - Backend-specific runtime conformance tests.
 ## Key Design Constraint
 The central IR must be a PHP semantic IR, not a C++ builder IR.
 If the IR is designed around `php::Var`, `php::Ref` and Zend symbols, C++ will
 remain the compiler's semantic core and future JavaScript/WASM targets will be
 hard to implement.
 If the IR describes PHP behavior and leaves physical representation to backend
 lowering, C++, JavaScript and WASM can evolve as separate backends.