# VALAPHP status

Stand: 2026-05-20

Diese Datei ist der Wiedereinstiegspunkt, wenn die Chat-/Session-Historie nicht mehr voll im Kontext liegt.

Zentrale Architekturvorgaben stehen in `PROJECT_GUIDELINES.md`.

## Zielbild

php2vala transpiliert PHP-Dateien nach Vala. PHP-Funktionen werden je nach Runtime-Flag gegen native valaphp-runtime-* Pakete oder gegen valaphp-runtime-embed gemappt. `--embed-runtime` ist Default und nutzt nur Embed, `--native-runtime` nutzt strikt nur native Bindings, und `--both-runtimes` nutzt zuerst native Bindings und dann Embed als Fallback.

Langfristige Struktur:

- valaphp-runtime-core: gemeinsame Typen, Fehler-/Source-Location-Helfer und Operatoren.
- valaphp-runtime-embed: Fallback ueber PHP Embed SAPI / libphp.so.
- valaphp-runtime-std, -json, -serialize, -math und spaeter weitere native Module pro C-Library oder sinnvoller Funktionsgruppe.
- php2vala: Transpiler, der per VAPI entscheidet, ob eine Funktion nativ oder ueber Embed gemappt wird.
- Native Runtime-Funktionen liegen einzeln als `src/functions/<funktion>.vala`,
  wenn eine Vala-Datei reicht. Unterordner unter `src/functions/` sind fuer
  Funktionen mit Begleitdateien wie `.c`/`.h`, mehreren Quellen oder eindeutig
  zusammengehoerigem Zusatzcode reserviert.

## Wichtige Entscheidungen

- Fehler sollen mit Throw-Time-Stacktrace geworfen werden: StacktraceError.throw(Php.with_php_source(...)).
- PHP-Source-Datei und Zeile werden in generierten Calls als letzte Argumente uebergeben.
- Embed-Normalfall: zentrale src/functions/embed_functions.vala plus ein generischer src/call/zval_array_to_zval.* Helper: Funktionsname + Php.zval-Array rein, Php.zval bzw. Output-String raus.
- Spezialfaelle duerfen nur noch eigene Funktionsordner haben, wenn sie nicht sinnvoll ueber call_user_function() mit zval-Array abbildbar sind.
- Shared Code gehoert nicht unter src/functions, sondern z. B. unter src/functions_sharedcode.
- Sprachkonstrukte gehoeren nicht unter src/functions; aktueller Ort: valaphp-runtime-embed/src/constructs/embed_constructs.vala.
- valaphp-runtime-embed ist auf PHP-Slot 8.3 gepinnt: Meson-Option php_slot, Default 8.3.
- phpinfo() soll plain text liefern. Dafuer wird vor php_embed_init() php_embed_module.phpinfo_as_text = 1 gesetzt.
- Funktionsvarianten haben zwei getrennte Achsen: `*_static`/`*_zval` beschreibt die Signaturform; native/embed beschreibt die Implementierung. Embed-Code darf also static und zval Varianten haben, und native Runtime-Module duerfen ebenfalls static und zval Varianten haben.
- `token_get_all()` und `token_name()` sind bewusst Embed/libphp-only. Eine native Nachimplementierung der PHP-Tokenizer-Semantik ist nicht sinnvoll; diese Funktionen sollen in den nativen Runtimes uebersprungen und in der Funktionsdoku als "native intentionally skipped" gefuehrt werden.

## Aktueller Stand der Pakete

### valaphp-runtime-core

Enthaelt Php.zval, Php.ValueType, Php.with_php_source(...) und Operatoren. Arithmetik liegt gesammelt unter src/operators/arithmetic; Division hat dort Php.div_static(...) und Php.div_zval(...). Operatoren sollen hier bleiben, nicht in Embed.

### valaphp-runtime-embed

Haengt an valaphp-runtime-core und libphp.so aus PHP Slot 8.3.

Wichtige Dateien:

- src/php_embed_runtime.c/.h: PHP Init, SAPI-Konfiguration, generische call_user_function-Bruecke, zval-Konvertierung, Output-Capture.
- src/call/zval_array_to_zval.*: einheitlicher call_user_function()-Wrapper fuer normale PHP-Funktionen.
- src/functions/embed_functions.vala: zentrale Vala-Mappings fuer normale PHP-Funktionen.
- src/constructs/embed_constructs.vala: Embed-only Konstrukte wie echo.
- valaphp-runtime-core/src/constructs/constructs.vala: runtime-uebergreifende Sprachkonstrukte isset, empty, exit, die.

Aktuell gemappte Embed-Funktionen/Konstrukte:

- JSON/Serialization: json_decode, json_encode, json_last_error_msg, serialize, unserialize
- Debug/Output: print_r, var_dump, var_export, phpinfo
- Typen: gettype, is_array, is_object, is_null, is_string, is_int, is_integer, is_long, is_float, is_double, is_real, is_bool, is_numeric
- String/Process/Math: strlen, trim, ltrim, rtrim, strval, intval, boolval, substr, exec, shell_exec, file_get_contents, round
- Tokenizer: token_get_all, token_name
- Sonstiges: count

Besonderheiten:

- count(stdClass) wird in Vala vorvalidiert, weil PHP 8 in Embed sonst einen Fatal/TypeError ausgibt.
- isset/empty/exit/die werden in generiertem Code ueber Php.* aus valaphp-runtime-core erzeugt, damit sie nicht an Embed/libphp haengen.
- exit/die in main werden als return Php.exit_* erzeugt.
- exit/die in lokalen generierten Funktionen werden als Process.exit(Php.exit_*(...)) erzeugt.

### Native Module

- valaphp-runtime-std: native Standardfunktionen wie echo, flush, microtime,
  number_format, print_r, var_dump, exit/die und einfache String-/Shell-Helfer.
- valaphp-runtime-json: native JSON-Funktionen auf json-glib; json-glib ist private Dependency.
- valaphp-runtime-serialize: native serialize ueber Php.zval.
- valaphp-runtime-math: native round/floor.

Alle Runtime-Meson-Dateien nutzen das Schema php_public_vapi_pkg_names / php_private_vapi_pkg_names.

## php2vala Stand

Aktueller Struktur-Split:

- src/model.vala: Datenmodelle und Fehlerdomain
- src/source_parser.vala: PHP-Tags, lokale Funktionsbloecke, Statement-Sammlung
- src/runtime_bindings.vala: VAPI-Scan und Embed-Fallback-Mappings
- src/runtime_metadata.vala: Runtime-Dependency-/Mapping-Metadaten
- src/generated_zval_runtime.vala: generierte generische zval-Helfer
- src/cli.vala: CLI
- src/main.vala: verbleibende Transpilerlogik

Aktuelle Semantik:

- Default ist `--optimize-cross-file-func-vars`: zval-ABI bleibt erhalten, statische ABI darf dateiuebergreifend ueber Stub-Metadaten genutzt werden.
- `--optimize-local-vars` schaltet den alten statischeren Pfad explizit ein.
- Der zval-first Pfad erzeugt direkte `PhpEmbed.<funktion>_zval(...)` Aufrufe.
- Statische `include`/`require` Statements mit String-Literal werden
  compile-time expandiert, damit Multifile-PHP fuer Embed und Native denselben
  Transpile-Kontext nutzt.
- Einfache Klassen ohne Properties/Vererbung werden als compile-time Subset
  unterstuetzt: sie werden als echte Vala-Klassen ausgegeben,
  `Class::method()` wird zu `Class.method()`, und
  `$obj = new Class(); $obj->method();` wird als Vala-Objekt/Methodenaufruf
  erzeugt.

- `--embed-runtime` erzwingt PhpEmbed.* und ist Default.
- `--native-runtime` erlaubt nur native Php.* Bindings und keinen Embed-Fallback.
- `--both-runtimes` bevorzugt native Php.* Bindings und nutzt PhpEmbed.* nur als
  Fallback, wenn keine native Bindung existiert.
- Generierte Vala-Dateien enthalten am Anfang Runtime-Dependencies und Funktionsmapping.
- Generierte Binaries unterstuetzen --debug--php2vala.
- Kommentare werden uebernommen: //, # als Vala //, und mehrzeilige /* ... */.
- Unbekannte Funktionen/Konstrukte erzeugen klare php2vala: Unsupported ... Fehler.
- Lokale PHP-Funktionen ohne Parameter werden vorab erkannt, aus main herausgenommen und als Vala-Helfer vor main erzeugt.
- Parser-Extraktion nutzt PHPs eigenen Tokenizer ueber Embed/libphp (`token_get_all()`/`token_name()`), damit Funktions-/Klassenbloecke robuster erkannt werden als mit Zeilenheuristiken. Beim Testen besonders auf originale PHP-Zeilennummern in Fehlermeldungen achten.

Bekannte Einschraenkungen:

- Lokale PHP-Funktionen mit Parametern sind noch nicht unterstuetzt.
- return in lokalen PHP-Funktionen ist noch nicht sauber implementiert.
- if/else, foreach, PHP-Array-Literale und komplexe Array-Schreibzugriffe sind noch naechste grosse Sprachthemen.
- Der Transpiler ist noch kein vollstaendiger PHP-Parser.

## Build/Install Hinweise

Install macht Sebastian selbst. Lokale Tests sollten ueber normale Meson-/Vala-Suchpfade laufen:

~~~sh
CCACHE_DISABLE=1 meson compile -C build
~~~

Tests gegen nicht installierte Runtime-Builds sollen explizit ueber
\`PKG_CONFIG_PATH\`, \`VALAFLAGS=--vapidir=...\` oder \`valac --vapidir=...\`
konfiguriert werden. php2vala selbst sucht keine projektspezifischen
Workspace-Pfade.

Embed/Core testen:

~~~sh
valac \
  --pkg valaphp-runtime-embed \
  --pkg valaphp-runtime-core \
  test.embed.vala -o test.embed.bin --debug
~~~

Run:

~~~sh
./test.embed.bin
~~~

Die Speed-/Transpiler-Tests liegen unter `tests/`; der aktuelle Benchmark-Pfad
ist `tests/php2vala-test-speed/compile.sh`. Das Script baut gegen die lokalen
Build-Verzeichnisse und pinnt fuer die Test-Binaries `valac --cc=gcc-15`.
Wenn Symbole fehlen, sind die neuen Libraries/VAPIs vermutlich noch nicht
gebaut oder installiert.

## Naechste sinnvolle Schritte

1. Runtime-API weiter vereinheitlichen: jede PHP-Funktion soll eine `*_static`
   Variante fuer echte Vala-Typen und eine `*_zval` Variante fuer
   PHP-kompatible zval-in/zval-out-Aufrufe haben.
2. Den lokalen Var-Optimizer als separaten, per Flag deaktivierbaren Pass bauen.
3. Eine kleine Regression-Test-Suite anlegen, damit neue Mappings nicht alte Beispiele brechen.

## Optimierungsnotizen fuer naechste Runden

- Tokenizer-Funktionen nicht nativ nachbauen: `token_get_all()`/`token_name()` bleiben Embed/libphp-Fallbacks.
- Bekannte Regressionstests nach Parser-/Optimizer-Aenderungen:
  - `tests/php2vala-test-speed/benchmark.php`
  - `tests/php2vala-test-speed/benchmark2.php`
  - `tests/multifile/multifile.php`
  - `tests/multifile-v2/multifile.php`
- Bei Fehlerausgaben immer pruefen, dass die originale PHP-Datei und Zeile erhalten bleiben, insbesondere fuer Top-Level-Code, lokale Funktionen und Klassenmethoden.
- PHP-Tags nicht per globalem String-Replace entfernen: `<?php`, `<?` und `?>` duerfen nur als echte PHP-Tags behandelt werden, nicht wenn sie in String-Literalen vorkommen.

Aktueller Mini-Fortschritt:

- `--optimize-cross-file-func-vars` ist der Default in php2vala; `--no-optimize-local-vars` schaltet auf zval-first zurueck.
- `valaphp-runtime-embed` enthaelt fuer vorhandene Embed-Funktionen `*_static` und `*_zval` Varianten.
- Der zval-first Pfad erzeugt direkte `PhpEmbed.<funktion>_zval(...)` Aufrufe und keine PHP-Funktionswrapper wie `php2vala_explode()` mehr.
- `transpile_show_mem_usage_compat()` ist entfernt; show_mem_usage.php laeuft ueber den regulaeren zval-first Parserpfad und die erzeugte Vala-Datei kompiliert.

## app-misc_show_mem_usage Analyse

Datei: /home/peters/SVN/gentoo-pw-programs/app-misc_show_mem_usage/src/show_mem_usage.php

Aktuelle Blocker fuer sauberes Funktionieren:

1. Lokale Funktionen mit Parametern und Defaults sind noch nicht unterstuetzt. Betroffen sind print_mem($mem,$len=0), get_total_mem_slabtop($cmd), get_total_mem_zram($cmd), get_total_mem_smem($cmd), get_total_mem_free($cmd), get_total_mem_dmesg($cmd), print_copyright().
2. Kontrollfluss im Funktionskoerper fehlt noch weitgehend fuer diese Datei: for, foreach, if/elseif/else, continue.
3. Array-/Hash-Zugriffe und verschachtelte Zuweisungen werden fuer diese Datei gebraucht: $cmd["a"], $matrix[$i][$t], $ret[$caption_b][$caption_a], $ret[$caption_b."/".$caption_a], @$ret2[$key] += $val2.
4. Fehlende PHP-APIs im Embed-Fallback: flush, number_format, explode, str_replace, stripos, class_exists. empty ist schon da, count ist schon da, shell_exec ist schon da.
5. String-/Vergleichslogik mit !== false und aehnlichen Checks muss im Ausdruckstranslator robust sein.

Empfohlene Reihenfolge:

1. Parameterisierte lokale Funktionen freischalten.
2. for/foreach/if/continue fuer den einfachen PHP-Subset pflegen.
3. Array-Indexing und Zuweisungen sauber abbilden.
4. Erst danach die fehlenden PHP-APIs als Embed-Mappings nachziehen.

## Kosten-/Kontextnotiz

Die OpenClaw/Codex-Session lief am 2026-05-20 mit openai/gpt-5.5 und sehr grossem gecachtem Kontext um 200k Tokens. Fuer spaetere Arbeit: erst diese Datei lesen, dann gezielt Code/Tests pruefen, statt alte Chat-Historie mitzuschleppen.
