PHP TRUE ASYNC is an experimental PHP extension that provides a true asynchronous, tightly integrated at the core level.

• Features
• Installation
  • Unix / macOS
  • Windows
• Adapted PHP Functions
• Quick Start
• Documentation
• Contributing
• License
• Links

Coming soon!

PHP TRUE ASYNC is supported for PHP 8.5.0 and later. LibUV is the primary reactor implementation for this extension.

# Build the image
docker build -t true-async-php .

# Run interactively
docker run -it true-async-php bash

# Check TrueAsync module
docker run --rm true-async-php php -m | grep true_async

• PHP 8.5.0+
• LibUV ≥ 1.45.0 (required) - Fixes critical UV_RUN_ONCE busy loop issue that could cause high CPU usage

Prior to libuv 1.44, there was a critical issue in uv__io_poll()/uv__run_pending logic that could cause the event loop to "stick" after the first callback when running in UV_RUN_ONCE mode, especially when new ready events appeared within callbacks. This resulted in:

• High CPU usage due to busy loops
• Performance degradation in async applications
• Inconsistent event loop behavior affecting TrueAsync API reliability

The fix in libuv 1.44 ensures that UV_RUN_ONCE properly returns after processing all ready callbacks in the current iteration, meeting the "forward progress" specification requirements. This is essential for TrueAsync's performance and reliability.

1. Clone the PHP repository:

   for example, basic directory name is php-src:

   git clone https://github.com/true-async/php-src -b true-async-api ./php-src
   

2. Clone the True Async extension repository:

   to the ext directory of your PHP source:

   git clone https://github.com/true-async/php-async ./php-src/ext/async
   

3. Install PHP development tools:

   Make sure you have the necessary development tools installed. On Debian/Ubuntu, you can run:

   sudo apt-get install php-dev build-essential autoconf libtool pkg-config
   

   For macOS, you can use Homebrew:

   brew install autoconf automake libtool pkg-config
   

4. Install LibUV::

IMPORTANT: LibUV version 1.45.0 or later is required.

For Debian/Ubuntu:

# Check if system libuv meets requirements (≥1.45.0)
pkg-config --modversion libuv

# If version is too old, install from source:
wget https://github.com/libuv/libuv/archive/v1.45.0.tar.gz
tar -xzf v1.45.0.tar.gz
cd libuv-1.45.0
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
sudo make install
sudo ldconfig

For macOS:

# Homebrew usually has recent versions
brew install libuv

Please see the LibUV installation guide for more details.

5. Configure and build:

   ./buildconf
   ./configure --enable-async
   make && sudo make install
   

   We can use --enable-debug to enable debug mode, which is useful for development.

   Note: The --enable-experimental-async-api option is no longer needed as the Async API is now enabled by default in the core.

1. Install php-sdk:
   Download and set up php-sdk for building PHP extensions on Windows.

2. Install and build LibUV:
   You can use vcpkg or build libuv from source.

3. Copy LibUV files to PHP SDK directories:

   1. Copy everything from 'libuv\include' to '%PHP_SDK_PATH%\deps\include\libuv\'
   2. Copy 'libuv.lib' to '%PHP_SDK_PATH%\deps\lib\'
   

   %PHP_SDK_PATH% is your php-sdk installation root.

4. Configure and build the extension with PHP:

   cd \path\to\php-src
   buildconf
   configure --enable-async
   nmake
   

   Note: The --enable-experimental-async-api option is no longer needed as the Async API is now enabled by default in the core.

50+ PHP functions have been adapted to work asynchronously when used within coroutines:

• gethostbyname() - resolve hostname to IP address
• gethostbyaddr() - resolve IP address to hostname
• gethostbynamel() - get list of IP addresses for hostname

• PDO MySQL - async-compatible PDO operations
  • PDO::__construct(), PDO::prepare(), PDO::exec() - non-blocking
  • PDOStatement::execute(), PDOStatement::fetch() - async data access
• MySQLi - async-compatible MySQLi operations
  • mysqli_connect(), mysqli_query(), mysqli_prepare() - non-blocking
  • mysqli_stmt_execute(), mysqli_fetch_*() - async result fetching

• curl_exec() - execute cURL request
• curl_multi_exec() - execute multiple cURL handles
• curl_multi_select() - wait for activity on multiple cURL handles
• curl_multi_getcontent() - get content from multi handle
• curl_setopt(), curl_getinfo(), curl_error(), curl_close() - async-aware

• socket_connect(), socket_accept() - connection operations
• socket_read(), socket_write() - data transfer
• socket_send(), socket_recv() - data exchange
• socket_sendto(), socket_recvfrom() - addressed data transfer
• socket_bind(), socket_listen() - server operations
• socket_select() - monitor socket activity

• file_get_contents() - get file/URL contents
• fread(), fwrite() - file I/O operations
• fopen(), fclose() - file handle management
• stream_socket_client(), stream_socket_server() - socket streams
• stream_socket_accept() - accept stream connections
• stream_select() - monitor stream activity
• stream_context_create() - async-aware context creation

• proc_open() - open process with pipes
• exec() - execute external command
• shell_exec() - execute shell command
• system() - execute system command
• passthru() - execute and pass output directly

• sleep() - delay execution (seconds)
• usleep() - delay execution (microseconds)
• time_nanosleep() - nanosecond precision delay
• time_sleep_until() - sleep until timestamp

• ob_start() - start output buffering with coroutine isolation
• ob_flush(), ob_clean() - buffer operations with isolation
• ob_get_contents(), ob_end_clean() - get/end buffer with isolation

All functions automatically become non-blocking when used in async context, allowing other coroutines to continue execution while waiting for I/O operations to complete.

<?php

// Spawn multiple concurrent coroutines
Async\spawn(function() {
    echo "Starting coroutine 1\n";
    sleep(2); // Non-blocking in async context
    echo "Coroutine 1 completed\n";
});

Async\spawn(function() {
    echo "Starting coroutine 2\n";
    sleep(1); // Non-blocking in async context
    echo "Coroutine 2 completed\n";
});

echo "All coroutines started\n";

<?php

$start = microtime(true);

// Start multiple DNS lookups concurrently
Async\spawn(function() {
    $ip = gethostbyname('github.com'); // Non-blocking
    $ips = gethostbynamel('github.com'); // Get all IPs
    echo "GitHub: $ip (" . count($ips) . " total IPs)\n";
});

Async\spawn(function() {
    $ip = gethostbyname('google.com'); // Non-blocking
    $hostname = gethostbyaddr($ip); // Reverse lookup
    echo "Google: $ip -> $hostname\n";
});

Async\spawn(function() {
    $content = file_get_contents('http://httpbin.org/ip'); // Non-blocking
    echo "External IP: " . json_decode($content)->origin . "\n";
});

$elapsed = microtime(true) - $start;
echo "All operations completed in: " . round($elapsed, 3) . "s\n";

<?php

$urls = [
    'https://httpbin.org/delay/1',
    'https://httpbin.org/delay/2',
    'https://httpbin.org/delay/1'
];

$start = microtime(true);

foreach ($urls as $i => $url) {
    Async\spawn(function() use ($url, $i) {
        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 10);
        
        $response = curl_exec($ch); // Non-blocking
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        echo "Request $i: HTTP $httpCode\n";
    });
}

$elapsed = microtime(true) - $start;
echo "All requests completed in: " . round($elapsed, 3) . "s\n";

<?php

// Concurrent database queries with PDO MySQL
Async\spawn(function() {
    $pdo = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    
    // All operations are non-blocking in async context
    $stmt = $pdo->prepare("SELECT * FROM users WHERE active = ?");
    $stmt->execute([1]);
    
    while ($row = $stmt->fetch(PDO::FETCH_ASSOC)) {
        echo "User: {$row['name']}\n";
    }
});

// MySQLi concurrent operations
Async\spawn(function() {
    $mysqli = new mysqli('localhost', $user, $pass, 'test');
    
    // Non-blocking query execution
    $result = $mysqli->query("SELECT COUNT(*) as total FROM orders");
    $row = $result->fetch_assoc();
    echo "Total orders: {$row['total']}\n";
    
    $mysqli->close();
});

echo "Database queries started\n";

<?php

// Execute multiple commands concurrently
Async\spawn(function() {
    $output = shell_exec('sleep 2 && echo "Command 1 done"'); // Non-blocking
    echo $output;
});

Async\spawn(function() {
    $output = shell_exec('sleep 1 && echo "Command 2 done"'); // Non-blocking
    echo $output;
});

echo "Commands started\n";

<?php

// Each coroutine has isolated output buffer
Async\spawn(function() {
    ob_start(); // Isolated buffer
    echo "Output from coroutine 1\n";
    echo "More output from coroutine 1\n";
    $buffer1 = ob_get_contents();
    ob_end_clean();
    
    echo "Coroutine 1 captured: $buffer1";
});

Async\spawn(function() {
    ob_start(); // Separate isolated buffer
    echo "Output from coroutine 2\n";
    $buffer2 = ob_get_contents();
    ob_end_clean();
    
    echo "Coroutine 2 captured: $buffer2";
});

echo "Buffers are isolated between coroutines\n";

• Documentation (coming soon)

Pull requests and suggestions are welcome!
Please read CONTRIBUTING.md before starting.

MIT

• 🛠️ php-src/true-async-api
• 🔌 php-async
• 📄 php-true-async-rfc

PHP TRUE ASYNC — modern async PHP, today!