PHPackages                             quillphp/quill-core - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. quillphp/quill-core

ActiveLibrary[API Development](/categories/api)

quillphp/quill-core
===================

High-performance binary engine for the Quill PHP Framework

0.0.3(2mo ago)0179↓92.9%1MITRustPHP ^8.3CI passing

Since Apr 5Pushed 2mo agoCompare

[ Source](https://github.com/quillphp/quill-core)[ Packagist](https://packagist.org/packages/quillphp/quill-core)[ RSS](/packages/quillphp-quill-core/feed)WikiDiscussions main Synced today

READMEChangelog (4)DependenciesVersions (4)Used By (1)

Quill-Core
==========

[](#quill-core)

**The high-performance native engine behind the Quill PHP Framework.**

[![CI](https://github.com/quillphp/quill-core/actions/workflows/ci.yml/badge.svg)](https://github.com/quillphp/quill-core/actions/workflows/ci.yml)[![Release](https://camo.githubusercontent.com/3f46ce2767e77134f9cc80c2d6b4c70c2b83ece9c5cca8c61d03c5e8a1b10cf6/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f7175696c6c7068702f7175696c6c2d636f7265)](https://github.com/quillphp/quill-core/releases)[![Rust](https://camo.githubusercontent.com/e8d5f86c088b16551924c61a566c7b9525e3452f9e10173dfba715081d137ac0/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f727573742d312e37352b2d6f72616e67652e737667)](https://www.rust-lang.org)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)

---

**Quill-Core** is the specialized native library that offloads heavy lifting from PHP userland to a thread-safe, memory-safe Rust engine. Built for sub-microsecond overhead, it powers the routing, validation, and shared-state management of the Quill PHP Framework.

Key Features
------------

[](#key-features)

- **Blazing Fast Routing**: Uses a Radix-tree based router (`matchit`) for O(1) matching in both PHP and CLI modes.
- **Shared-State Broker (SSB)**: A thread-safe, atomic Key-Value store shared across all PHP workers — no Redis required for simple state.
- **Native DTO Validation**: Decouples validation from PHP userland, performing schema checks at native speeds using the `validator` crate.
- **Ultra-Fast JSON**: Powered by `sonic-rs` for high-performance compaction and boundary-crossing transformations.
- **FFI-First & Hardened**: Seamlessly integrates via PHP `FFI` with robust null-pointer guards and memory safety.
- **Multi-Worker Ready**: Native support for pre-fork socket sharing (`dup(2)`).

---

Architecture Overview
---------------------

[](#architecture-overview)

Quill Core owns the entire I/O stack. PHP never touches a socket — it only executes business logic, orchestrated by the native engine through a lock-free FFI bridge.

### Multi-Worker Model

[](#multi-worker-model)

The parent process compiles routes and pre-binds the TCP port **before** forking. Each child inherits the socket via `dup(2)` and independently initialises its own Rust runtime — while sharing a global **Shared-State Broker** (SSB) in the Rust heap.

 ```
flowchart TD
    A[PHP App] -->|compile manifest| B["quill_router_build()"]
    A -->|register DTOs| C["quill_validator_register()"]
    A -->|pre-bind port| D["quill_server_prebind()"]

    B --> Router[(matchit\nradix trie)]
    C --> Validator[(ValidatorRegistry)]
    D --> Sock[[Shared Socket fd]]

    SSB[(Shared-State Broker\nAtomic DashMap)]

    Sock -.->|"dup(2)"| W1 & W2 & WN

    subgraph W1 ["Worker 1"]
        direction LR
        AX1["Axum / Tokio"] |"mpsc"| PH1[PHP Loop]
    end
    subgraph W2 ["Worker 2"]
        direction LR
        AX2["Axum / Tokio"] |"mpsc"| PH2[PHP Loop]
    end

    PH1 & PH2 |FFI / SSB| SSB
```

      Loading ### Request Lifecycle

[](#request-lifecycle)

 ```
sequenceDiagram
    participant C  as Client
    participant AX as Axum / Tokio
    participant RT as matchit Router
    participant VL as ValidatorRegistry
    participant SSB as Shared-State Broker
    participant PHP as PHP Poll Loop

    C->>+AX: HTTP Request
    AX->>RT: match_route(method, path)
    RT-->>AX: RouteMetadata

    opt has DTO
        AX->>VL: validate(dto, body)
        VL-->>AX: JSON  —or—  400
    end

    AX->>PHP: mpsc::send(PendingRequest)
    PHP->>PHP: execute handler

    opt use shared state
        PHP->>SSB: quill_shared_incr("visitors")
        SSB-->>PHP: new value
    end

    PHP->>AX: quill_server_respond(id, json)
    AX-->>-C: HTTP Response
```

      Loading ---

Shared-State Broker (SSB)
-------------------------

[](#shared-state-broker-ssb)

One of Quill-Core's most powerful features is the built-in **Shared-State Broker**. It provides a lock-free, thread-safe Key-Value store that lives in the Rust engine's memory space but is accessible from any PHP worker.

- **Atomic Operations**: Support for atomic increments/decrements (e.g., `quill_shared_incr`).
- **Low Latency**: Sub-microsecond access times compared to millisecond latencies of external stores like Redis.
- **Zero Configuration**: No separate service or configuration required.
- **Data Types**: Stores arbitrary JSON values, allowing for complex data sharing.

### Example Usage (via FFI)

[](#example-usage-via-ffi)

```
// Increment a global visitor count
$count = $ffi->quill_shared_incr("visitors", 11, 1);

// Store complex state
$ffi->quill_shared_set("session_1", 9, json_encode(['ip' => '127.0.0.1']), 18);

// Atomic key removal
$ffi->quill_shared_remove("session_1", 9);
```

---

Installation
------------

[](#installation)

### Option 1: Using Pre-built Binaries (Recommended)

[](#option-1-using-pre-built-binaries-recommended)

You can download the optimized shared libraries (`.so` or `.dylib`) and the required C-header (`quill.h`) directly from the [GitHub Releases](https://github.com/quillphp/quill-core/releases) page.

### Option 2: Building from Source

[](#option-2-building-from-source)

If you are contributing or need a custom build, you can compile from source using `cargo`:

```
# Clone the repository
git clone https://github.com/quillphp/quill-core.git
cd quill-core

# Build the shared library (bin/ folder)
./scripts/build.sh --release
```

---

Integration with Quill PHP
--------------------------

[](#integration-with-quill-php)

By default, the Quill PHP framework will automatically discover the core library if it's placed in any of these locations:

1. `build/libquill.so` (Local Development)
2. `vendor/quillphp/quill-core/bin/libquill.so` (Composer Integration)
3. `/usr/local/lib/libquill.so` (Global System Level)

You can override the discovery behavior using the **`QUILL_CORE_BINARY`** environment variable:

```
export QUILL_CORE_BINARY=/path/to/your/libquill.so
```

---

Performance & Hardening
---------------------------

[](#performance--hardening)

### Ultra-Fast JSON

[](#ultra-fast-json)

Quill-Core uses **`sonic-rs`**, a SIMD-accelerated JSON library, to perform compaction and validation. This allows the core to process large payloads with minimal CPU cycles before passing them to PHP.

### FFI Hardening

[](#ffi-hardening)

The FFI boundary is designed for production stability:

- **Null-Pointer Guards**: Every C-string and pointer passed from PHP is checked for null before dereferencing.
- **Memory Safety**: Uses Rust's ownership model to ensure that memory allocated in the native engine is correctly managed and freed.
- **Thread Safety**: The Shared-State Broker uses `DashMap` (a concurrent hash map) to allow multiple PHP workers to read and write simultaneously without global locks.

---

FFI API Reference
-----------------

[](#ffi-api-reference)

For developers building custom integrations, Quill-Core exports the following C-compatible functions:

### Router & JSON

[](#router--json)

- `quill_router_build(json, len)`: Compiles a JSON manifest into a Radix-tree.
- `quill_router_match(...)`: Matches a method/path and returns handler metadata.
- `quill_router_dispatch(...)`: High-level matching and DTO validation in one call.
- `quill_router_free(router)`: Frees a router instance.
- `quill_json_compact(input, len, out, max)`: SIMD-accelerated JSON compaction.

### Native Validator

[](#native-validator)

- `quill_validator_new()`: Creates a new validator registry.
- `quill_validator_register(registry, name, n_len, schema, s_len)`: Registers a DTO schema.
- `quill_validator_validate(registry, name, n_len, input, i_len, out, max)`: Performs validation.
- `quill_validator_free(registry)`: Frees a validator instance.

### Shared-State Broker (SSB)

[](#shared-state-broker-ssb-1)

- `quill_shared_set(key, k_len, val_json, v_len)`: Store a JSON value.
- `quill_shared_get(key, k_len, out_buf, max)`: Retrieve a JSON value.
- `quill_shared_incr(key, k_len, delta)`: Atomic increment/decrement.
- `quill_shared_remove(key, k_len)`: Delete a key-value pair.
- `quill_shared_keys(out_buf, max)`: List all keys in the broker.

### Server

[](#server)

- `quill_server_prebind(port)`: Pre-bind a TCP socket (call before fork).
- `quill_server_listen(...)`: Start the Axum/Tokio worker thread.
- `quill_server_poll(...)`: Fetch the next pending request for PHP.
- `quill_server_respond(...)`: Send a response back to the native engine.

---

Native DTO Validation
---------------------

[](#native-dto-validation)

Quill-Core implements a powerful, low-latency validation engine in Rust. It supports rules like:

- **Type Safety**: `Numeric`, `Boolean`, `Regex`.
- **Consistency**: `Required`, `Email`, `Min`/`Max` (for numbers), `MinLength`/`MaxLength` (for strings).
- **Default Values**: Automatically inject default values for missing optional fields before they reach PHP.

By moving validation to the native layer, you reduce PHP CPU cycles and memory allocations for invalid requests.

---

Development & Testing
-------------------------

[](#development--testing)

We maintain strict code quality standards to ensure consistency and performance.

```
# Run unit tests
cargo test

# Run Clippy (linter)
cargo clippy -- -D warnings

# Apply formatting
cargo fmt --all
```

---

License
-------

[](#license)

This project is open-sourced under the **MIT License**.

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance85

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

3

Last Release

89d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/4742b2ad737c14793d6b0a418e6da90b446153a4d7ba120a1f3c07e2a2951d28?d=identicon)[quillphp](/maintainers/quillphp)

---

Top Contributors

[![fr3on](https://avatars.githubusercontent.com/u/26393383?v=4)](https://github.com/fr3on "fr3on (25 commits)")

---

Tags

apidtoffiphprustweb-server

### Embed Badge

![Health badge](/badges/quillphp-quill-core/health.svg)

```
[![Health](https://phpackages.com/badges/quillphp-quill-core/health.svg)](https://phpackages.com/packages/quillphp-quill-core)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35916.4M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24016.2M20](/packages/hubspot-api-client)[pocketmine/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

172445.0k15](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram

Telegram driver for BotMan

93459.5k6](/packages/botman-driver-telegram)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)