# phpef-runtime-native-standard

Native PHPEF implementations for PHP functions that belong to PHP's `standard`
extension.  The generic embed-backed wrappers remain in `phpef-runtime-embed`;
PHPEFC's resolver may prefer this package when it exposes the same `phpfunc_*`
wrapper with compatible PHP/Zval semantics.

## Unified `phpef-runtime-*` function API

All `phpef-runtime-*` packages (`embed`, `native-*`, and future domain runtimes) use the same public Vala/VAPI naming and resolving scheme. PHPEFC must be able to resolve embed and native candidates with the same `Php2ValaFuncResolver` code path; runtime-specific packages only differ by VAPI metadata such as `typed_fast_path native` vs `typed_fast_path static_php_call`.

When a function or language construct is moved from `phpef-runtime-embed` into a `phpef-runtime-native-*` package, the native package must expose every corresponding Embed variant with the exact same public wrapper name/signature: the base Zval-compatible wrapper and all typed/derived wrappers. For example, native `echo` must provide both `phpfunc_echo(PhpefRuntimeCore.Zval value)` and `phpfunc_echo_typed_void_arg1_string(string value)`. Do not add only the typed fast path while leaving the Zval-compatible ABI behind in Embed.

Implementation layout rule: keep `src/phpef_runtime_native_standard.vala` focused on public exported wrapper functions. Do not add private/internal helper implementations there. Shared implementation code belongs in separate source files or generated build sources such as `src/standard_math_helpers.vala` and build-generated `standard_constant_helpers.vala`, included by Meson but not exposed as public VAPI ABI.

### Zval-compatible PHP wrappers

```text
phpfunc_<phpname>(Zval...)
```

- Return type is `PhpefRuntimeCore.Zval`.
- Arguments are `PhpefRuntimeCore.Zval` / `Zval?` as needed for PHP default/nullability behavior.
- Semantics should match PHP/Zend for the selected runtime. Native wrappers must be covered against the embed wrapper before they are treated as interchangeable.
- Public `phpfunc_*` wrappers are resolver/ABI endpoints and should not call each other. Shared implementation code belongs in internal, non-VAPI helper functions/files.
- Example: `phpfunc_microtime(Zval? as_float = null)`.

### Typed fast paths

```text
phpfunc_<phpname>_typed_<returntype>_arg1_<type>_arg2_<type>...
```

- Return and argument types are scalar Vala types (`string`, `int`, `double`, `bool`, `void`, ...), normalized by PHPEFC for matching.
- Multiple typed variants for the same PHP function are allowed when each variant has a distinct signature suffix.
- The VAPI must carry an adjacent metadata comment before PHPEFC may optimize to the wrapper, for example:

```vala
// PHPEF typed_fast_path native; source php_function; PHP function: foo; typed_signature _typed_int_arg1_string
public static int phpfunc_foo_typed_int_arg1_string(string value);
```

For embed-backed static typed calls, use `typed_fast_path static_php_call` and include the boundary name when relevant. For native direct implementations, use `typed_fast_path native`.

### Special typed fast paths with argument-dependent return type

When the PHP return type depends on a literal argument value, encode that literal in the typed suffix:

```text
phpfunc_<phpname>_typed_<returntype>_argN_<type>_<literal>
```

Example:

```vala
// PHPEF typed_fast_path native; source php_function; PHP function: microtime; typed_signature _typed_double_arg1_bool_true; role current_time_seconds
public static double phpfunc_microtime_typed_double_arg1_bool_true();
```

Here `arg1_bool_true` describes the PHP call shape (`microtime(true)`). The native Vala wrapper does not have to receive that argument if the literal is fully represented by the selected specialization. PHPEFC derives the PHP name and typed signature from the `phpfunc_*_typed_*` name and uses the VAPI comment only as optimizer policy/metadata.

## Current `microtime()` coverage

`phpef-runtime-native-standard` currently implements both the Zval-compatible `phpfunc_microtime(Zval? as_float = null)` wrapper and the special typed `phpfunc_microtime_typed_double_arg1_bool_true()` fast path. The comparison tests exercise:

- string-returning Zval forms: `microtime()`, `microtime(false)`, `microtime(null)`, `microtime(0)`, `microtime('0')`;
- float-returning Zval forms: `microtime(true)`, `microtime(1)`, `microtime('1')`;
- special typed form: `phpfunc_microtime_typed_double_arg1_bool_true()`, compared against embed `microtime(true)` for time proximity.

## Current `echo` coverage

Native `echo` mirrors the Embed ABI variants rather than only exposing the optimized typed form:

- Zval-compatible base wrapper: `phpfunc_echo(PhpefRuntimeCore.Zval value)`;
- typed string wrapper: `phpfunc_echo_typed_void_arg1_string(string value)`.

Both names intentionally match `phpef-runtime-embed`; PHPEFC/`library-embed2native` may then make the runtime choice explicit by qualifying the call as `PhpefRuntimeEmbed.*` or `PhpefRuntimeNativeStandard.*`.

