How to Install Thread-Safe (TS) PHP with Swoole on Ubuntu

PHP is a powerhouse for web development, but when you're building applications that need to handle concurrent requests efficiently - think multi-threaded servers and extensions like Swoole - standard PHP installations fall short.

In this guide, we'll walk through installing thread-safe PHP on Ubuntu 24. We'll use the official PHP source to compile it with the necessary flags. This process assumes you're comfortable with the terminal.

For my environment, I will be using a fresh instance of WSL (Windows Subsystem for Linux).

For my day-to-day work, I have created a bash script to build and install everything in one go. Let's try to compose the script in this guide at the end.

Make sure to have sudo rights and run commands with sudo if necessary.

Install latest updates

apt update -y

Install SSH server

If you are using WSL, you may skip this step.

apt install openssh-server -y

Preparing working directory

For our installation and project setup, we will need to set up a workspace folder with certain permissions. And it is important to set it outside of our home directory to avoid further permission issues.

I will use the “workspace” folder located at the root of our file system, so I can easily find or navigate to it.

mkdir /workspace
cd /workspace
chmod -R 777 ./

Installing PostgreSQL

We need to install it first, as we will need it for our manual builds for PHP and Swoole.

Follow these instructions to install the PostgreSQL database service.

apt update
install -y postgresql postgresql-contrib
systemctl start postgresql.service

Installing PHP

Regular PHP installation with the terminal apt-get command will not get us PHP with threads. We can only build it from source. But first, we need to install dependencies before we build something.

apt install -y pkg-config build-essential autoconf bison re2c postgresql postgresql-contrib libpq-dev \
               libcurl4-openssl-dev openssl libssl-dev libxml2-dev libsqlite3-dev zlib1g-dev libonig-dev

I will use the “workspace” folder located at the root of our file system, so I can easily find or navigate to it.

mkdir /workspace
cd /workspace
chmod -R 777 ./

Let's pull the specific version of PHP from the official source code repository.

wget "https://github.com/php/php-src/archive/php-8.4.7.tar.gz"
tar --extract --gzip --file "php-8.4.7.tar.gz"
rm -f "php-8.4.7.tar.gz"
cd "php-src-php-8.4.7"

Now we need to configure the build and set up some flags.

These flags can get you certain features. I encourage you to learn about it and configure it for your needs.

./buildconf --force
./configure \
--enable-zts --with-openssl --with-zlib --enable-bcmath --with-curl \
--enable-mbstring --with-pdo-mysql --with-pdo-pgsql --with-pgsql --enable-sockets --enable-soap

In this scenario, "--enable-zts" sets our build configurations to support thread-safe mode and includes all necessary extensions with it.

"\" at the end of a line means the line break and command continuing on the next line.

When copying and pasting, ensure that you have copied the entire command with multiple lines.

Now we are ready to build.

make -j4
make install

Last commands may take a while, so be patient.

After successful build and installation, you should be able to use the “php” command in your terminal.

php -v

Install PHP essentials and additional extensions if needed.

In my case, I need redis and inotify.

apt install -y composer php-pear
pecl install inotify
pecl install redis
echo 'extension=inotify.so' | tee -a /usr/local/lib/php.ini
echo 'extension=redis.so' | tee -a /usr/local/lib/php.ini

Installing Swoole

Swoole is a complete async solution that has built-in support for async programming via fibers/coroutines, a range of multi-threaded I/O modules (HTTP Server, WebSockets, GRPC, TaskWorkers, Process Pools), and support for popular PHP clients like PDO for MySQL, Redis, and CURL.

You can use sync or async, coroutine, or fiber API to write applications or create thousands of lightweight fibers within one Linux process.

Swoole enhances the efficiency of your PHP applications and brings you out of the traditional stateless model, enabling you to focus on the development of innovative products at high scale, bringing event loops and asynchronous programming to the PHP language.

There is also Open Swoole - a fork of the original Swoole project.

Some preparation.

apt-get install -y  libc-ares-dev libpq-dev

Fetching the source code, building, and installing.

Swoole also has a set of features that are configurable with flags during the build. Please study those if you need a custom build.

wget https://github.com/swoole/swoole-src/archive/refs/tags/v6.0.2.tar.gz
tar --extract --gzip --file v6.0.2.tar.gz
rm -f v6.0.2.tar.gz
cd swoole-src-6.0.2
phpize && \
./configure \
--enable-openssl --enable-swoole-curl --enable-cares --enable-swoole-pgsql --enable-swoole-thread
make
make install

Adding Swoole extensions into our PHP ini file.

echo 'extension=swoole.so' | tee -a /usr/local/lib/php.ini

Installing NGINX

Now, I need a proxy and a static files server. My choice is NGINX. Execute these commands to install it.

apt install -y nginx
ufw app list
ufw allow 'Nginx HTTP' && \
ufw allow 'Nginx HTTPS'
ufw app list

“ufw” - works with the firewall and sets all necessary permissions.

I also need a local certificate to test my websites locally with SSL.

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -subj "/C=US/ST=LA/L=Mirage/O=Dis/CN=www.example.com" \
-keyout /etc/ssl/private/nginx-selfsigned.key -out /etc/ssl/certs/nginx-selfsigned.crt

Installing Redis

If you need Redis server, follow these commands.

apt install -y redis-server

Installing Node.js

If you are working with JavaScript on your server, you will also need Node.js.

Execute these commands to install it.

apt update
apt install -y nodejs npm

Finalizing

Wrapping up, combining all of those commands into one script and executing all at once.

Discover the source code here

And all you need to do is execute this simple multiline command.

Production

sudo rm -f server.sh && \
sudo wget --no-cache --no-cookies https://raw.githubusercontent.com/fluffy-space/win-ubuntu-vbox/main/scripts/server.sh && \
sudo bash server.sh --prod

Development

sudo rm -f server.sh && \
sudo wget --no-cache --no-cookies https://raw.githubusercontent.com/fluffy-space/win-ubuntu-vbox/main/scripts/server.sh && \
sudo bash server.sh

You can modify the script for your needs, put it into the GitHub repository, and use it in a similar way.

Thank you, and feel free to ask questions.