https://github.com/ktav-lang/php
PHP bindings for Ktav — a plain configuration format with three rules, zero indentation, and zero quoting. FFI over the reference Rust crate — no PHP extension to compile, prebuilt binaries for Linux/macOS/Windows.
https://github.com/ktav-lang/php
bindings composer config config-format configuration ffi ktav parser php rust
Last synced: 2 months ago
JSON representation
PHP bindings for Ktav — a plain configuration format with three rules, zero indentation, and zero quoting. FFI over the reference Rust crate — no PHP extension to compile, prebuilt binaries for Linux/macOS/Windows.
- Host: GitHub
- URL: https://github.com/ktav-lang/php
- Owner: ktav-lang
- License: mit
- Created: 2026-04-25T20:21:48.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-25T21:12:19.000Z (2 months ago)
- Last Synced: 2026-04-25T22:29:10.798Z (2 months ago)
- Topics: bindings, composer, config, config-format, configuration, ffi, ktav, parser, php, rust
- Language: PHP
- Size: 42 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# ktav — PHP bindings
**Languages:** **English** · [Русский](README.ru.md) · [简体中文](README.zh.md)
PHP bindings for the [Ktav configuration format](https://github.com/ktav-lang/spec).
Thin wrapper around the reference Rust parser, loaded at runtime through
the **[PHP FFI extension](https://www.php.net/manual/en/book.ffi.php)** —
no PHP extension to compile, no PECL install. Plain Composer
dependency, the native binary is fetched on first call.
Requires **PHP 7.4+** with `ext-ffi` enabled (default in CLI; web SAPIs
need `ffi.enable=1` in `php.ini`).
## Install
```bash
composer require ktav-lang/ktav
```
## Quick start
### Parse — read typed values straight off the array
```php
use Ktav\Ktav;
$src = <<
$dbHost = $cfg['db']['host']; // string
$dbTimeout = $cfg['db']['timeout']; // int
```
### Build & render — construct a document in code
```php
$doc = [
'name' => 'frontend',
'port' => 8443,
'tls' => true,
'ratio' => 0.95,
'upstreams' => [
['host' => 'a.example', 'port' => 1080],
['host' => 'b.example', 'port' => 1080],
],
'notes' => null,
];
$text = Ktav::dumps($doc);
```
A complete runnable example lives in [`examples/basic.php`](examples/basic.php).
## API
| Method | Purpose |
| --- | --- |
| `Ktav::loads(string $src): mixed` | Parse a Ktav document. |
| `Ktav::dumps(array $value): string` | Render an associative array as Ktav text. |
| `Ktav::nativeVersion(): string` | Version of the loaded `ktav_cabi`. |
`KtavException` is thrown on any parse / render failure; the message is
the UTF-8 string produced by the native parser.
## Type mapping
| Ktav | PHP |
| ---------------- | ---------------------------------------------------- |
| `null` | `null` |
| `true` / `false` | `bool` |
| `:i ` | `int` if it fits, else `string` (PHP has no native bigint — wrap your own GMP / BCMath if you need arithmetic). |
| `:f ` | `float` |
| bare scalar | `string` |
| `[ ... ]` | sequential `array` |
| `{ ... }` | associative `array` (insertion order preserved) |
To emit an arbitrary-precision integer, wrap the digit string yourself:
`['big' => ['$i' => '9999999999999999999']]` — same envelope used on the
wire between PHP and the native side.
## How the native library is resolved
On first call:
1. **`KTAV_LIB_PATH`** env var, if set.
2. **User cache** — `/ktav-php/v/`, downloaded
on a previous call.
3. **GitHub Release download** — fetched once from
`github.com/ktav-lang/php/releases/download/v/` and
cached under (2). Requires network on first call after install.
`` is `%LOCALAPPDATA%` on Windows, `~/Library/Caches` on
macOS, `$XDG_CACHE_HOME` or `~/.cache` on Linux.
## Runtime support
- PHP 7.4 / 8.0 / 8.1 / 8.2 / 8.3+. Tested on the LTS lines on every CI run.
- Prebuilt binaries for: `linux/amd64`, `linux/arm64`, `darwin/amd64`,
`darwin/arm64`, `windows/amd64`, `windows/arm64`.
- Linux distros must use glibc 2.17+ (zigbuild baseline). Alpine
(musl) support is planned.
## License
MIT — see [LICENSE](LICENSE).
## Other Ktav implementations
- [`spec`](https://github.com/ktav-lang/spec) — specification + conformance suite
- [`rust`](https://github.com/ktav-lang/rust) — reference Rust crate (`cargo add ktav`)
- [`csharp`](https://github.com/ktav-lang/csharp) — C# / .NET (`dotnet add package Ktav`)
- [`golang`](https://github.com/ktav-lang/golang) — Go (`go get github.com/ktav-lang/golang`)
- [`java`](https://github.com/ktav-lang/java) — Java / JVM (`io.github.ktav-lang:ktav` on Maven Central)
- [`js`](https://github.com/ktav-lang/js) — JS / TS (`npm install @ktav-lang/ktav`)
- [`python`](https://github.com/ktav-lang/python) — Python (`pip install ktav`)