TrueAsync Server 빠른 시작 ​

(PHP 8.6+, true_async_server 0.6+)

5분 안에: 확장 설치, 최소 핸들러, 응답 확인.

서버는 모든 사전 빌드 패키지에서 TrueAsync PHP와 함께 제공됩니다. 인스톨러, Docker 이미지, Windows ZIP을 통해 TrueAsync PHP가 이미 설치되어 있다면 php.ini에서 확장을 활성화하기만 하면 됩니다 — 별도 빌드는 필요 없습니다. 직접 소스에서 빌드하고 싶다면(자체 PHP 버전, 자체 의존성 체인) 소스에서 빌드 섹션을 참고하세요.

Docker ​

가장 빠르게 시도하는 방법입니다. 미리 빌드된 이미지에는 TrueAsync가 적용된 PHP와 true_async_server 확장이 포함되어 있습니다.

docker run --rm -p 8080:8080 \
  -v $PWD/hello.php:/app/hello.php \
  -w /app \
  trueasync/php-true-async:latest \
  php hello.php

사용 가능한 태그:

태그와 과거 릴리스의 전체 목록은 다운로드 페이지에 있습니다.

Linux / macOS — 스크립트 설치 ​

스크립트가 소스를 내려받아 서버 확장과 함께 TrueAsync PHP를 빌드하고 모든 결과물을 ~/.php-trueasync/bin/에 둡니다.

# Linux (Ubuntu / Debian)
curl -fsSL https://raw.githubusercontent.com/true-async/releases/master/installer/build-linux.sh | bash

# macOS (Apple Silicon / Intel; Homebrew 필요)
curl -fsSL https://raw.githubusercontent.com/true-async/releases/master/installer/build-macos.sh | bash

설치 후 php --ri true_async_server로 프로토콜과 라이브러리 버전을 확인할 수 있습니다.

매개변수(bash 앞에 환경 변수로 전달하거나 비대화형 모드에서 사용):

curl -fsSL .../build-linux.sh | NO_INTERACTIVE=true bash

옵션과 설치 제어는 다운로드 페이지에 설명되어 있습니다.

Windows — ZIP ​

Windows x64용 TrueAsync PHP 사전 빌드 패키지에는 서버 확장이 포함되어 있습니다. GitHub Releases에서 ZIP을 내려받고 (php-trueasync-X.Y.Z-php8.6-windows-x64.zip 형식), 압축을 풀고, 디렉터리를 PATH에 추가한 뒤 php.ini에 다음을 활성화합니다.

extension=true_async_server

확인:

php --ri true_async_server

HTTP/3 outbound batching은 UDP_SEGMENT(Linux GSO)를 사용하며, Windows에는 동등한 것이 없습니다. Windows에서 HTTP/3 처리량은 더 낮습니다. HTTP/1.1, HTTP/2, TLS는 손실 없이 동작합니다.

확장 활성화 ​

모든 설치 방법에서 php.ini에 다음을 추가해야 합니다.

extension=true_async_server

그리고 확인:

php --ri true_async_server

출력에는 프로토콜(HTTP/1.1, HTTP/2, HTTP/3, TLS 1.2/1.3)과 런타임의 OpenSSL, nghttp2, ngtcp2, nghttp3, libuv 버전이 표시됩니다.

소스에서 빌드 ​

표준 빌드가 적합하지 않다면 직접 빌드할 수 있습니다.

요구 사항 ​

배포판의 OpenSSL/ngtcp2/nghttp3 패키지는 보통 너무 오래된 버전입니다. 단일 prefix(/usr/local 또는 /opt/h3) 아래에 OpenSSL 3.5 + ngtcp2 + nghttp3를 소스에서 빌드하고, ./configure 시 PKG_CONFIG_PATH로 지정하는 것을 권장합니다.

Linux ​

1. 의존성 ​

sudo apt-get install -y \
    build-essential autoconf bison re2c pkg-config \
    libcmocka-dev   # --enable-tests용

OpenSSL 3.5, ngtcp2 1.22+, nghttp3 1.15+는 작성 시점에 대부분의 배포판 저장소에 없으므로 /usr/local 아래에 빌드합니다.

# QUIC가 포함된 OpenSSL 3.5
git clone --branch openssl-3.5 https://github.com/openssl/openssl
cd openssl && ./Configure --prefix=/usr/local && make -j$(nproc) && sudo make install
sudo ldconfig

# ngtcp2 (OpenSSL crypto 백엔드)
git clone --recursive https://github.com/ngtcp2/ngtcp2
cd ngtcp2 && autoreconf -i \
  && ./configure --prefix=/usr/local --with-openssl --with-libnghttp3 \
                 PKG_CONFIG_PATH=/usr/local/lib/pkgconfig \
  && make -j$(nproc) && sudo make install

# nghttp3
git clone --recursive https://github.com/ngtcp2/nghttp3
cd nghttp3 && autoreconf -i \
  && ./configure --prefix=/usr/local && make -j$(nproc) && sudo make install

2. 확장 빌드 ​

git clone https://github.com/true-async/server true-async-server
cd true-async-server
phpize
./configure \
    --enable-http-server \
    --with-php-config="$(which php-config)" \
    PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
make -j$(nproc)
sudo make install

HTTP/2와 HTTP/3은 의존성이 있으면 자동으로 활성화됩니다 (H2는 libnghttp2 ≥ 1.57, H3은 libngtcp2 ≥ 1.22, libnghttp3 ≥ 1.15, OpenSSL ≥ 3.5). 끄려면 --disable-http2, --disable-http3.

추가 플래그:

이후 php.ini에서 확장을 활성화하고 확인하면 됩니다 — 위 확장 활성화 섹션을 참고하세요.

Windows ​

표준 PHP-SDK를 통한 빌드. OpenSSL 3.5, nghttp2, ngtcp2, nghttp3의 정적 .lib이 PHP-SDK 트리의 deps\ 아래에 있어야 합니다.

REM Visual Studio x64 Native Tools prompt에서
phpsdk_buildtree phpdev
git clone https://github.com/true-async/php-src.git
cd php-src
git clone https://github.com/true-async/server ext\true_async_server

buildconf.bat
configure.bat ^
    --disable-all ^
    --enable-cli ^
    --enable-async=shared ^
    --enable-http-server=shared ^
    --with-openssl=shared

nmake

빌드된 php_true_async_server.dll은 x64\Release_TS\(또는 NTS의 경우 Release\)에 나타납니다. 이를 ext\로 복사하고 php.ini에 extension=true_async_server를 추가하세요.

최소 서버 ​

<?php
// hello.php

use TrueAsync\HttpServer;
use TrueAsync\HttpServerConfig;

$server = new HttpServer(
    (new HttpServerConfig())
        ->addListener('0.0.0.0', 8080)
);

$server->addHttpHandler(function ($request, $response) {
    $response
        ->setStatusCode(200)
        ->setHeader('Content-Type', 'text/plain')
        ->setBody('Hello, World!');
});

$server->start();   // stop()까지 블로킹

실행:

php hello.php

확인:

curl -i http://localhost:8080/

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 13

Hello, World!

다음 단계 ​

• 구성: TLS, 타임아웃, 본문 한도
• Multi-worker: setWorkers(N)과 bootloader
• 예제: JSON-API, 정적 파일, multipart 업로드, fan-out
• HttpServer 레퍼런스