# PHPEFC TODO

Current open work only. Completed implementation history belongs in SVN log, tests,
README files, or architecture docs — not here.

## Finish before committing the current slice

- Review and commit the current PHPEF library/stacktrace/default-stacktrace work in
  logical SVN changesets. Do not mix new features into that commit.
- Keep `pwphpbytecode` libraries out of PHPEF `elib` semantics. `(library)` in
  `meson.build.pw` means PHPEF-native library only.

## Near-term compiler/runtime correctness

1. **Include/require activation semantics inside multi-source `ebin` and `elib` units**
   - Inside one PHPEF compilation unit, PHP files must be activated by PHP
     include/require order. This applies to application binaries (`ebin`) and
     PHPEF libraries (`elib`) alike.
   - For example, `elib = library1/main.php + library1/helper.php -> library1`
     compiles both files, but `helper.php` becomes PHP-visible when `main.php`
     includes it, not by eager registration of every source file.
   - PHPEF library boundaries are different from PHP includes: crossing from an
     `ebin` to a linked `elib`, or from one `elib` to another `elib`, should not
     require PHP include activation by the caller. The linked/included PHPEF unit
     is responsible for its own activation/init semantics.
   - Duplicate PHP-visible declarations must become visible/fatal according to
     PHP activation order, not by eager global registration.
   - Add strict PHP-vs-PHPEF compare fixtures before optimizing direct calls.

2. **PHP function-call diagnostics and wrapper coverage**
   - Keep diagnostics distinguishing:
     - PHP function exists, but PHPEF has no `phpfunc_*` wrapper/lowering yet;
     - function is unavailable in the selected PHP runtime/extension set;
     - only explicit `zendcall_*` escape hatch exists.
   - Add wrappers only with tests against Embed or PHP CLI semantics.

3. **PHP-vs-PHPEF runtime diagnostic parity**
   - Error/warning text currently differs between PHP CLI and PHPEF for some
     runtime failures. Do not fix these with one-off lowerings for individual
     functions or paths.
   - Design a generic diagnostic strategy that carries source file/line and
     warning/error category through the runtime boundary, then add focused
     PHP-vs-PHPEF fixtures for the affected cases.
   - Until that exists, compare tests may normalize/relax diagnostic details when
     the observable program behavior and exit status are otherwise equivalent.

4. **Declared type metadata**
   - Preserve PHP parameter and return declarations in PHPIR/ValaIR metadata.
   - Keep the Zval ABI correct first; use metadata later for optimizers/direct
     method signatures.

5. **PHP exception object model**
   - Replace ad-hoc exception metadata helpers with a real PHP Throwable object
     represented as a Zval. See `docs/php-exception-object-model.md`.

6. **Runtime value semantics**
   - Core: PHP-compatible numeric strings, scalar conversions, arrays, object
     identity, references, copy-on-write/separation.
   - Runtime changes need PHP-vs-PHPEF comparison tests.
   - Array/reference/COW design target for later:
     - separate PHP variable slots from reference cells and Zval payloads;
     - normal assignment is logical by-value, with arrays/strings allowed to share
       immutable payloads until `separate_for_write()`;
     - `=&` aliases slots to the same cell, so writes mutate the shared cell;
     - object assignment copies the object handle, not object state;
     - nested array writes must separate the modified path so `$b = $a;
       $b[0]["x"] = 2;` leaves `$a` unchanged, while references stay aliased.

7. **Native runtime composition**
   - `phpfunc_constant()` and later native runtime packages need explicit
     ownership/fallback metadata when multiple runtimes provide the same wrapper.

8. **`declare(strict_types=1)` / `Declare_` handling**
   - PHPEFC currently rejects `PhpParser\\Node\\Stmt\\Declare_` during
     `phpast2phpir`; a temporary compare test with `declare(strict_types=1);`,
     `function foo(int $x): void { ... }`, and `foo("123");` failed at compile
     time with `Unsupported PHP statement for phpast-ir-v0 at line 2`.
   - First slice: accept `declare(strict_types=1);` in PHPIR instead of treating
     it as an unsupported statement. Preserve it as source-file metadata.
   - Semantics target: `strict_types` is primarily a call-site flag for scalar
     parameter coercion/checking. The same typed function can be called from
     strict and non-strict files with different behavior.
   - Return-type strictness must follow PHP semantics for the function definition
     file, not the caller file.
   - Add PHP-vs-PHPEF compare fixtures before optimizer work: strict call should
     throw `TypeError` for `foo("123")` when `foo(int $x)`; non-strict call should
     coerce compatibly where PHP does.

## Later PHPEF ELF features

- Embed binary assets/blobs as explicit pipeline descriptor inputs and linkable
  objects, with deterministic symbols/manifest and byte-exact tests.
- Continue hardening `.phpef_stacktrace` / `.debug_phpef` for stripped and
  optimized shared-library edge cases.

## Kernel-module family notes

- `phpkmc` may reuse PHPEFC frontend/PHPIR in userspace only.
- Kernel output must branch after PHPIR to a kernel-safe C IR/runtime; never link
  GLib, libphp, pwphpbytecode, or PHPEF userspace runtimes into `.ko` modules.
