PHPackages                             swoole/phpx - 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. [Utility & Helpers](/categories/utility)
4. /
5. swoole/phpx

ActiveLibrary[Utility & Helpers](/categories/utility)

swoole/phpx
===========

C++ wrapper for Zend API

v2.3.10(1w ago)8601471031Apache-2.0C++CI passing

Since Aug 22Pushed 1w ago71 watchersCompare

[ Source](https://github.com/swoole/phpx)[ Packagist](https://packagist.org/packages/swoole/phpx)[ RSS](/packages/swoole-phpx/feed)WikiDiscussions master Synced today

READMEChangelog (10)Dependencies (18)Versions (22)Used By (1)

[![Swoole Logo](logo.png)](logo.png)
====================================

[](#)

[![Twitter](https://camo.githubusercontent.com/938a48bafad518c277315ee27ebefa0a0ca9f7cde918eef1820810964ff6e9f5/68747470733a2f2f62616467656e2e6e65742f62616467652f69636f6e2f747769747465723f69636f6e3d74776974746572266c6162656c)](https://twitter.com/phpswoole)[![Discord](https://camo.githubusercontent.com/155081771f1f717ebd6be59f0cb88fb4ac65ee4a70fec13715509f7e280fdd50/68747470733a2f2f62616467656e2e6e65742f62616467652f69636f6e2f646973636f72643f69636f6e3d646973636f7264266c6162656c)](https://discord.swoole.dev)[![Build Status](https://github.com/matyhtf/phpx/workflows/libphpx/badge.svg)](https://github.com/matyhtf/phpx/actions?query=workflow%3Alibphpx)[![License](https://camo.githubusercontent.com/1d48dd9fe6bf24b648040a29de372f089b9340226a4fb00214784dfb402cdda1/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d617061636865322d626c75652e737667)](LICENSE)[![Latest Release](https://camo.githubusercontent.com/22f7562c52a318bba0347108dff68227ee0a71348346275c78ded9dbfa569ad1/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f73776f6f6c652f706870782e737667)](https://github.com/swoole/phpx/releases/)[![Codecov](https://camo.githubusercontent.com/da77b9df00ef9c58e2ca959ac951ffc72dca1a80b76e8e1c238f417bc6505503/68747470733a2f2f636f6465636f762e696f2f67682f73776f6f6c652f706870782f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/swoole/phpx)

C++ wrapper for Zend API

[简体中文](README-CN.md)

Requirements
------------

[](#requirements)

- PHP 8.2 or later
- Linux/macOS/Windows
- GCC 9 or later (with C++17 support)
- Composer

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

[](#installation)

### Build libphpx.so

[](#build-libphpxso)

```
# Standard build (Release mode)
cmake .
make -j 4
sudo make install
sudo ldconfig
```

### Debug Mode (for troubleshooting)

[](#debug-mode-for-troubleshooting)

```
# Clean previous builds
cmake --build . --target clean

# Configure Debug mode (includes debug symbols and runtime checks)
cmake -DCMAKE_BUILD_TYPE=Debug .

# Compile
make -j 4
sudo make install
sudo ldconfig
```

**Debug Mode Features:**

- ✅ Generates complete debug symbols
- ✅ Disables compiler optimizations for easier debugging
- ✅ Enables runtime error checking
- ✅ More detailed compilation output

Quick Start
-----------

[](#quick-start)

### Create a New Extension Project

[](#create-a-new-extension-project)

```
# Create extension project
composer create-project swoole/phpx-ext test
cd test
```

### Basic Usage Example

[](#basic-usage-example)

Here's a complete example demonstrating modern PHPX extension development:

```
#include "phpx_ext.h"

// Include auto-generated arginfo header (generated by gen_stub.php)
BEGIN_EXTERN_C()
#include "your_extension_arginfo.h"
END_EXTERN_C()

using namespace php;
using namespace std;

// Method implementation using PHPX_METHOD macro
PHPX_METHOD(MyClass, __construct) {
    // Initialize object properties
    _this.set("name", args[0].toString());
    _this.set("value", args[1].toInt());
    return nullptr;
}

PHPX_METHOD(MyClass, greet) {
    // Access object properties
    auto name = _this.get("name");
    auto value = _this.get("value");

    // Return formatted string
    return "Hello, " + name.toStdString() + "! Value: " + to_string(value.toInt());
}

PHPX_METHOD(MyClass, processData) {
    // Work with Array type
    Array input = args[0];
    Array result;

    // Iterate and transform
    for (auto &item : input) {
        result.append(item.value.toInt() * 2);
    }

    return result;
}

// Function implementation using PHPX_FUNCTION macro
PHPX_FUNCTION(my_extension_func) {
    // Variant - universal type container
    Variant str_var = "Hello PHPX";
    Variant int_var = 42;
    Variant float_var = 3.14159;

    // Array operations
    Array arr;
    arr.set("name", "PHPX");
    arr.set("version", 8.2);
    arr.set("features", Array{"C++17", "Type-safe", "Modern API"});

    // Object creation and method calls
    Object datetime = newObject("DateTime");
    auto formatted = datetime.call("format", {"Y-m-d H:i:s"});

    // Facade functions - direct PHP function calls
    php::var_dump(arr);                    // Debug output
    php::print_r(datetime);                // Print object

    // File operations
    auto content = php::file_get_contents("/etc/hosts");
    if (content.isString()) {
        echo("File length: ", content.length(), "\n");
    }

    // Array manipulation with references
    Array numbers{1, 2, 3, 4, 5};
    Reference ref = numbers.toReference();
    php::sort(ref);                        // Sort array
    php::array_push(ref, 6, 7, 8);        // Push elements

    RETURN_STRING("PHPX Demo Completed!");
}

// Extension entry point
PHPX_EXTENSION() {
    Extension *ext = new Extension("my_extension", "1.0.0");

    // Register lifecycle callbacks
    ext->onStart = [ext]() noexcept {
        // Register constants
        ext->registerConstant("MY_EXT_VERSION", 10000);

        // Register class with methods
        Class *c = new Class("MyClass");
        c->addProperty("name", "", ZEND_ACC_PUBLIC);
        c->addProperty("value", 0, ZEND_ACC_PUBLIC);
        c->registerFunctions(class_MyClass_methods);  // From arginfo header
        ext->registerClass(c);

        // Register standalone functions
        ext->registerFunction(PHPX_FN(my_extension_func));
    };

    // PHP info page configuration
    ext->info({"my_extension support", "enabled"},
              {
                  {"author", "Your Name"},
                  {"version", ext->version},
                  {"github", "https://github.com/your/repo"},
              });

    return ext;
}
```

**Key Features:**

- **PHPX\_METHOD/PHPX\_FUNCTION**: Modern macros for cleaner code
- **Extension/Class API**: Object-oriented extension registration
- **Lambda callbacks**: Flexible lifecycle management with `onStart`, `onShutdown`, etc.
- **Type-safe wrappers**: `Variant`, `Array`, `Object`, `String` classes
- **Facade functions**: Direct PHP function calls via `php::` namespace
- **Auto-generated arginfo**: Use `gen_stub.php` to generate type information

### Generate ArgInfo & Function Entries

[](#generate-arginfo--function-entries)

```
php vendor/swoole/phpx/bin/gen_stub.php your_stub_dir
```

### Build Your Extension

[](#build-your-extension)

```
cd test
cmake .
make -j 4
make install
```

### Load Your Extension

[](#load-your-extension)

Edit `php.ini` and add:

```
extension=test.so
```

### Test Your Extension

[](#test-your-extension)

Create a test file `test.php`:

```

```

Run it:

```
php test.php
```

Expected output:

```
Hello, World!

```

Advanced Usage
--------------

[](#advanced-usage)

### 1. Variant Type Usage

[](#1-variant-type-usage)

Variant is a universal type container that can hold any PHP value:

```
#include "phpx.h"

using namespace php;

// Create variants of different types
Variant str_var = "Hello PHPX";
Variant int_var = 42;
Variant float_var = 3.14159;
Variant bool_var = true;
Variant null_var;

// Type checking
if (str_var.isString()) {
    echo("String: ", str_var.toCString());
}

if (int_var.isInt()) {
    echo("Integer: ", int_var.toInt());
}

// Type conversion
auto str = int_var.toString();      // Convert to string
auto num = str_var.toInt();         // Convert to integer (0 if not numeric)

// Comparison
if (str_var.equals("Hello PHPX")) {
    echo("Match!");
}

// Serialization
Variant serialized = str_var.serialize();
Variant unserialized = serialized.unserialize();
```

### 2. Array Type Usage

[](#2-array-type-usage)

Array provides a C++ wrapper for PHP arrays with rich functionality:

```
#include "phpx.h"

using namespace php;

// Create arrays
Array arr;
arr.set("name", "PHPX");
arr.set("version", 8.2);
arr.set("features", Array{"C++17", "Type-safe", "Modern API"});

// Initialize with list
Array numbers{1, 2, 3, 4, 5};
Array map{{"key1", "value1"}, {"key2", "value2"}};

// Access elements
auto name = arr.get("name");
auto first = numbers[0];

// Check existence
if (arr.exists("name")) {
    echo("Name exists");
}

// Iterate array
for (auto &item : arr) {
    echo(item.key, ": ", item.value, "\n");
}

// Array operations
arr.append("new_element");          // Add element
arr.del("name");                    // Remove element
auto count = arr.count();           // Get count
auto keys = arr.keys();             // Get all keys

// Nested arrays
Array nested;
nested.set("level1", Array{
    {"level2", Array{"deep_value"}}
});
auto deep = nested.item("level1").item("level2");

// Reference for modification
Array nums{5, 2, 8, 1, 9};
Reference ref = nums.toReference();
php::sort(ref);                     // Sort in place
php::array_push(ref, 10, 11);       // Push elements
```

### 3. Object Type Usage

[](#3-object-type-usage)

Object wraps PHP objects and provides method calling capabilities:

```
#include "phpx.h"

using namespace php;

// Create object
Object datetime = newObject("DateTime");

// Call methods
auto formatted = datetime.call("format", {"Y-m-d H:i:s"});
echo("Current time: ", formatted.toCString());

// Set properties
Object stdclass = newObject("stdClass");
stdclass.set("name", "test");
stdclass.set("value", 42);

// Get properties
auto name = stdclass.get("name");
auto value = stdclass.get("value");

// Check property existence
if (stdclass.exists("name")) {
    echo("Property exists");
}

// Create object with constructor arguments
Object arrayObj = newObject("ArrayObject", {
    Array{1, 2, 3, 4, 5}
});

// Call method and get result
auto count = arrayObj.call("count");
echo("Count: ", count.toInt());

// Static method calls
auto result = Object::callStatic("DateTime", "createFromFormat", {
    "Y-m-d", "2024-01-01"
});
```

### 4. Facade Encapsulation API

[](#4-facade-encapsulation-api)

PHPX provides facade functions in the `php::` namespace for direct PHP function calls:

```
#include "phpx.h"
#include "phpx_func.h"

using namespace php;

// Debug and output
php::var_dump(some_variable);           // Debug output
php::print_r(some_variable);            // Print readable
php::echo("Hello", " ", "World");      // Echo strings

// File operations
auto content = php::file_get_contents("/path/to/file.txt");
php::file_put_contents("/path/to/file.txt", "content");

// Array manipulation (requires reference)
Array arr{5, 2, 8, 1, 9};
Reference ref = arr.toReference();

php::sort(ref);                         // Sort array
php::rsort(ref);                        // Reverse sort
php::shuffle(ref);                      // Shuffle
php::array_push(ref, 10, 11);          // Push elements
php::array_pop(ref);                    // Pop element
php::array_shift(ref);                  // Shift element
php::array_unshift(ref, 0);            // Unshift element

// String operations
auto upper = php::strtoupper("hello");
auto lower = php::strtolower("HELLO");
auto length = php::strlen("hello");
auto pos = php::strpos("hello world", "world");

// Math operations
auto max_val = php::max({1, 2, 3, 4, 5});
auto min_val = php::min({1, 2, 3, 4, 5});
auto sum = php::array_sum(Array{1, 2, 3, 4, 5});
auto rand_val = php::rand(1, 100);

// JSON operations
Array data{{"name", "PHPX"}, {"version", 8.2}};
auto json_str = php::json_encode(data);
auto decoded = php::json_decode(json_str, true);

// Other useful functions
php::sleep(2);                          // Sleep 2 seconds
auto time = php::time();                // Current timestamp
auto date = php::date("Y-m-d H:i:s");  // Formatted date
```

### 5. Built-in Class Facade Encapsulation

[](#5-built-in-class-facade-encapsulation)

PHPX provides facade classes for popular PHP extensions:

```
#include "phpx.h"
#include "phpx_class.h"

using namespace php;

// Redis example
Redis redis{};
redis.connect("127.0.0.1", 6379);

// String operations
redis.set("name", "PHPX");
redis.set("version", "8.2");
auto name = redis.get("name");
echo("Name: ", name.toCString());

// Check existence
if (redis.exists("name")) {
    echo("Key exists");
}

// Multiple operations
redis.mset({
    {"key1", "value1"},
    {"key2", "value2"},
    {"key3", "value3"}
});

auto values = redis.mget({"key1", "key2", "key3"});

// List operations
redis.rpush("mylist", "item1");
redis.rpush("mylist", "item2");
auto list_len = redis.llen("mylist");

// Hash operations
redis.hset("user:1", "name", "John");
redis.hset("user:1", "email", "john@example.com");
auto user_name = redis.hget("user:1", "name");

// Set expiration
redis.expire("name", 3600);  // Expire in 1 hour

// Delete keys
redis.del("key1", "key2");

// Close connection
redis.close();
```

**Note:** To use Redis facade, ensure the Redis extension is loaded in your PHP environment.

Documentation
-------------

[](#documentation)

For more detailed documentation, please check:

- [Architecture Guide](docs/architecture.md)
- [API Reference](docs/api-reference.md)
- [Quick Start Guide](docs/quickstart.md)
- [Testing Guide](docs/testing-guide.md)
- [Debugging Guide](docs/debugging-guide.md)

Examples
--------

[](#examples)

Check out the [examples directory](examples/) for more comprehensive examples including:

- Bloom filter implementation
- Queue data structure
- RocksDB integration
- GTK application
- And more!

Language
--------

[](#language)

- [English](README.md)
- [中文](README-CN.md)

License
-------

[](#license)

PHPX is open-sourced software licensed under the [Apache License 2.0](LICENSE).

###  Health Score

53

—

FairBetter than 96% of packages

Maintenance96

Actively maintained with recent releases

Popularity38

Limited adoption so far

Community32

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 96.6% 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 ~15 days

Recently: every ~3 days

Total

21

Last Release

7d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e1dea9261ba377a13a16e7e0f3883e73bda4094551ddea280e852f23a5d248c0?d=identicon)[Tianfeng.Han](/maintainers/Tianfeng.Han)

---

Top Contributors

[![matyhtf](https://avatars.githubusercontent.com/u/2017766?v=4)](https://github.com/matyhtf "matyhtf (702 commits)")[![owenliang](https://avatars.githubusercontent.com/u/7803472?v=4)](https://github.com/owenliang "owenliang (15 commits)")[![limingxinleo](https://avatars.githubusercontent.com/u/16648551?v=4)](https://github.com/limingxinleo "limingxinleo (2 commits)")[![Yurunsoft](https://avatars.githubusercontent.com/u/20104656?v=4)](https://github.com/Yurunsoft "Yurunsoft (2 commits)")[![kong36088](https://avatars.githubusercontent.com/u/11497913?v=4)](https://github.com/kong36088 "kong36088 (2 commits)")[![NathanFreeman](https://avatars.githubusercontent.com/u/33935209?v=4)](https://github.com/NathanFreeman "NathanFreeman (1 commits)")[![heyanlong](https://avatars.githubusercontent.com/u/3367958?v=4)](https://github.com/heyanlong "heyanlong (1 commits)")[![shiguangqi](https://avatars.githubusercontent.com/u/654869?v=4)](https://github.com/shiguangqi "shiguangqi (1 commits)")[![deminy](https://avatars.githubusercontent.com/u/865547?v=4)](https://github.com/deminy "deminy (1 commits)")

---

Tags

phpextensionembeddedZendAPI

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/swoole-phpx/health.svg)

```
[![Health](https://phpackages.com/badges/swoole-phpx/health.svg)](https://phpackages.com/packages/swoole-phpx)
```

###  Alternatives

[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

751291.4k43](/packages/civicrm-civicrm-core)[rubix/tensor

A library and extension that provides objects for scientific computing in PHP.

2801.6M5](/packages/rubix-tensor)[memio/spec-gen

phpspec extension for better code generation

67204.7k28](/packages/memio-spec-gen)[phpxmlrpc/polyfill-xmlrpc

A pure-php reimplementation of the API exposed by the native XML-RPC extension

12424.1k3](/packages/phpxmlrpc-polyfill-xmlrpc)

PHPackages © 2026

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