# Zval-Architektur

## Aktueller Stand

`Zval` ist aktuell in `phpef-runtime-core/src/phpef_runtime_core.vala` als Vala-`class` implementiert, nicht als `struct`. Der Typ-Tag heißt derzeit `ValueKind`.

Die Implementierung ist damit bewusst ein pragmatischer Bootstrap für zval-artige PHP-Werte im engine-unabhängigen Runtime-Core. Aktuell existieren neben Skalarwerten bereits kleine Array-/Object-Bootstrap-Pfade für Compiler- und Runtime-Bridge-Tests; sie sind aber noch keine vollständige PHP-Array-/Objektsemantik.

## Entscheidung: Zval als Fallback-Container

`Zval` bleibt vorerst bewusst eine `class`, weil es als PHP-`mixed`-/Fallback-Container gedacht ist. Dynamische Werte, PHP-semantische Sonderfälle und Übergänge, bei denen der Compiler die Wertform nicht statisch sicher kennt, können so einheitlich über `Zval` laufen.

Die langfristige Richtung ist aber nicht, jeden Wert immer als `Zval` zu führen. Statisch erkennbare Werte sollen später in generiertem Vala möglichst als native Vala-Typen laufen, zum Beispiel:

- `int64` für bekannte Integer-Pfade;
- `bool` für bekannte Bool-Pfade;
- ggf. `string` für bekannte String-Pfade;
- später ggf. spezialisierte Container für bekannte Arrays/Objekte, wenn das semantisch sauber ist.

`Zval` bleibt dann der Fallback für dynamische oder PHP-semantisch schwierige Fälle.

## `class` vs. `struct`

Die aktuelle `class`-Variante ist für den Bootstrap einfacher:

- Methoden und Fabriken lassen sich direkt modellieren;
- `null`/Nullable- und Referenzsemantik sind in Vala einfacher handhabbar;
- der Code bleibt für frühe Runtime- und Compiler-Experimente übersichtlich.

Der Preis ist, dass ein `Zval` als Klasse ein Heap-Objekt pro Wert ist und damit mehr Overhead als ein kleiner Wertcontainer hat.

Ein `struct` wäre näher an der Zend-Idee eines kleinen Wertcontainers mit Typ-Tag und Payload und könnte für primitive Werte günstiger sein. Dafür würden Ownership, Kopieren, Aliasing und spätere Copy-on-Write-Semantik deutlich komplexer, besonders sobald Strings, Arrays, Objekte oder PHP-Referenzen beteiligt sind.

Aktuelle Entscheidung: Die `class`-Implementierung wird akzeptiert, solange spätere native, statisch typisierte Pfade den Overhead für einfache Werte vermeiden können.

## Vala-Strings und PHP-COW

Native Vala-`string`-Zuweisung bildet kein PHP-Copy-on-Write im semantischen Sinn ab. Vala-Strings sollten hier praktisch immutable/value-artig behandelt werden: Eine Operation wie `b = b + "!"` erzeugt einen neuen String, statt einen PHP-artigen gemeinsamen String-Payload mit COW-Regeln zu mutieren.

PHP-Referenzen, Copy-on-Write und Aliasing dürfen deshalb nicht implizit Vala-Strings oder Vala-Arrays überlassen werden. Wenn diese Semantik benötigt wird, muss sie in `Zval` oder in einem separaten Payload-/Referenzmodell der PHPEF-Runtime explizit modelliert werden.

## Refcounting

GLib-/Vala-Refcounting regelt primär die Speicher-Lifetime von Objekten. Es ist nicht identisch mit PHP-Semantik.

PHP-Copy-on-Write, `&`-Referenzen und gemeinsam genutzte Payloads müssen als PHPEF-Semantik separat modelliert werden, falls und wo sie gebraucht werden. Vala-Refcounting kann dabei bei der Speicherverwaltung helfen, ersetzt aber nicht die PHP-Regeln.

## Orientierung an Zend

Zend ist weiterhin eine wichtige architektonische Orientierung: ein kleiner Wertcontainer mit Typ-Tag und Payload, dazu separate Regeln für Referenzen, Copy-on-Write und komplexe Payloads.

In PHPEF ist die aktuelle Vala-`class` ein pragmatischer Startpunkt. Die Zielrichtung ist eine Kombination aus nativen Vala-Pfaden für statisch erkennbare Werte und `Zval` als Fallback für dynamische PHP-Wertsemantik, nicht ein pauschales „alles immer Zval“.
