# php2vala-bindgen

This copy is built as part of the main `php2vala` Meson project from
`src_bindgen/meson.build`. It uses the freshly built `php2vala_exe` target from
that same build, so `meson compile -C build` produces both binaries:

```text
build/php2vala
build/src_bindgen/php2vala-bindgen
```

Canonical binding generator for php2vala library metadata.

It currently consumes Vala `.vapi` files and writes:

- `stub.php` for PHP authoring, editor completion, and php2vala symbol lookup
- Vala package and namespace metadata in the stub docblocks

`php2vala-bindgen` is the only binding generator project in this workspace.

## Build

Build from the parent `php2vala` project. The bindgen target intentionally uses
the freshly built `php2vala_exe` target instead of `find_program('php2vala')`, so
it does not depend on an already installed php2vala binary.

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

The built binary is `build/src_bindgen/php2vala-bindgen`.

## Example

```sh
build/src_bindgen/php2vala-bindgen \
  --input ../valaphp-libadwaita/build/vala-libadwaita-wrapper/valaphp-libadwaita-wrapper-0.1.vapi \
  --output ../valaphp-libadwaita/build/vala-libadwaita-wrapper/generated/stub.php \
  --php-namespace ValaPhp.LibadwaitaWrapper \
  --vala-namespace ValaPhpAdw \
  --pkg valaphp-libadwaita-wrapper-0.1
```

## Direct VAPI stub mode

For C libraries that already have a usable Vala `.vapi`, `php2vala-bindgen` can
produce a PHP stub directly from the VAPI. No handwritten Vala wrapper is needed
when the VAPI already exposes a convenient Vala class/function surface.

For `libmagic`, the generated PHP is declarative and uses docblock metadata:

```php
/**
 * @php \ValaPhp\LibMagic\Magic
 * @vala LibMagic.Magic
 * @pkg libmagic
 */
class Magic {
    /**
     * @vala-constructor __construct
     */
    public function __construct(int $flags = 0) {}

    /**
     * @vala-method file
     */
    public function file(string $filename): ?string {}
}
```

The stub is not the runtime implementation. It is metadata for php2vala. php2vala
uses `@vala`, `@pkg`, `@vala-constructor`, and `@vala-method` to emit a Vala
forwarder class. valac then resolves the target through the VAPI and links the
native library.

For this metadata to survive tokenization, bindgen emits method metadata as
normal multi-line docblocks directly before `public function ...`.

Direct VAPI mode also emits PHP constant classes for VAPI enums. If the VAPI
uses a C prefix such as `cprefix = "MAGIC_"`, bindgen reads the declared C
header and resolves the actual `#define` values instead of guessing from enum
order. This matters for libmagic because `MIME_TYPE`, `CONTINUE`, and
`MIME_ENCODING` are bit flags with header-defined values.

Example generated surface:

```php
class Flags {
    public const NONE = 0x0000000;
    public const MIME_TYPE = 0x0000010;
    public const MIME_ENCODING = 0x0000400;
}
```
