Skip to content

Getting Started

This guide will show you how to get started with LSPHP (PHP with LiteSpeed API) on your linux machine.

We will cover:

  • different methods depending on operating system
  • compiling PHP from source
  • installing LSPHP on your control panel environments
  • configuring LSPHP with LiteSpeed Web Server

Installation

Native

LiteSpeed Repository

The easiest way to get up and running with PHP is to use the LiteSpeed Repository. The LiteSpeed Repository comes with prebuilt PHP packages with LiteSpeed support built in.

Here is a list of some of the features you get when you use our LiteSpeed Repository, instead of compiling PHP manually:

  • PHP versions 5.6*, 7.0*, 7.1*, 7.2*, 7.3*, 7.4*, 8.0, 8.1, 8.2 and 8.3.
  • CentOS and RHEL versions 7*, 8 and 9.
  • Ubuntu versions 18.04*, 20.04, 22.04 and 24.04.
  • Debian versions 9*, 10, 11 and 12.
  • Contains most up-to-date versions of LSAPI. (Do not have to wait for a new PHP version to be released.)
  • Easily install multiple versions of PHP (by default installed to different locations).
  • Contains all frequently used PHP packages.
  • Contains multiple possible MySQL support packages (via native driver or client library).
  • Contains multiple opcode caching options: APCu, Xcache, Zend Opcache.

Footnote

* These PHP versions are dependent on the OS. Newer OS's might not support the older end-of-life (EOL) versions.

Prerequisites

Before you can install LSPHP there are a couple of prerequisite packages and repositories that need to be installed via the operating system's package manager. This can be accomplished by running the following command in a terminal:

$ sudo wget -O - https://repo.litespeed.sh | sudo bash
Packages

It is not a requirement to search through the LSPHP packages and extensions we offer before installing, but it does come in handy to know what you can install and then have the option to install everything at the same time. To find out all the LSPHP packages and extensions we offer you can run the following:

$ sudo dnf search lsphp

$ sudo dnf search lsphp

$ sudo yum search lsphp

$ sudo apt-cache search lsphp
Install

Now that you have installed the prerequisites you can go ahead with the actual installataion process.

If you searched our repository then you can use the names of the packages and extensions you found to install what you need.

For example, to install LSPHP81 and LSPHP81-mysql via the command line you would run the following:

$ sudo dnf install lsphp81 lsphp81-common lsphp81-mysqlnd

$ sudo dnf install lsphp81 lsphp81-common lsphp81-mysqlnd

$ sudo yum install lsphp81 lsphp81-common lsphp81-mysqlnd

$ sudo apt-get install lsphp81 lsphp81-common lsphp81-mysql

This will install lsphp81 and lsphp81-mysql into the following location: /usr/local/lsws/lsphp81/bin/lsphp.

Once it has been installed you can continue to the setup section.

Portsnap

In this section we will show you how to install LSPHP on FreeBSD using portsnap which manages FreeBSD's Ports collection.

Setup

Start by updating your FreeBSD server ports tree using the portsnap command: 

$ sudo portsnap fetch update # This will fetch the ports and any updates
$ sudo portsnap extract # This will extract the ports to be compiled
$ sudo portsnap fetch update # This will make sure everything is up to date

Install

First you will need to edit the Makefile for Make to build the LSPHP binary. This can be achieved by running the following commands: 

$ sudo cd /usr/ports/lang/php73 # Replace 73 with the version you wish to install
$ sudo nano Makefile # You can replace nano with your favorite text editor
# Find the line `--with-password-argon2=${LOCALBASE} \`
#and after it add `--with-litespeed \`
$ sudo make
$ sudo make install
When you run the Make commands it may take awhile as it will compile multiple dependencies for you that PHP requires. Overall it is a simple process of just hitting yes. Once make is finished it will install the LSPHP binary in the following location. 
/usr/ports/lang/php81/work/stage/usr/local/bin/

Next let's move it to a more suitable location for dealing with LiteSpeed. This is accomplished by running these commands: 

$ sudo mkdir -p /usr/local/lsws/lsphp81/bin/
$ sudo cp /usr/ports/lang/php81/work/stage/usr/local/bin/lsphp /usr/local/lsws/lsphp81/bin/
The LSPHP binary will now be located at /usr/local/lsws/lsphp81/bin/lsphp.

After the LSPHP binary is fully compiled you can continue to the Setup section.

Source

Here we will take a look at how to compile PHP + LSAPI from source. This can be useful for custom setups and for platforms where our LiteSpeed Repo is not available.

Prerequisites

PHP has many dependencies that are needed when compiling and these often change depending on what extensions and functions you compile PHP with. So before you can compile you will need to install some default packages that are needed for a semi feature rich PHP.

In a command line run the following:

$ sudo yum install patch gcc glibc libstdc++ binutils libtool autoconf make bison pam-devel libcap-devel openssl-devel tcp_wrappers-devel bzip2-devel curl-devel db4-devel gmp-devel httpd-devel libstdc++-devel sqlite-devel sqlite2-devel liyuybedit-devel pcre-devel libtool gcc-c++ libtool-ltdl-devel libevent-devel libc-client-devel cyrus-sasl-devel openldap-devel mysql-devel postgresql-devel unixODBC-devel libxml2-devel net-snmp-devel libxslt-devel libxml2-devel libjpeg-devel libpng-devel freetype-devel libXpm-devel t1lib-devel libmcrypt-devel libtidy-devel freetds-devel aspell-devel recode-devel enchant-devel firebird-devel gdbm-devel tokyocabinet-devel

$ sudo dnf install patch gcc glibc libstdc++ binutils libtool autoconf make bison pam-devel libcap-devel openssl-devel tcp_wrappers-devel bzip2-devel curl-devel db4-devel gmp-devel httpd-devel libstdc++-devel sqlite-devel sqlite2-devel liyuybedit-devel pcre-devel libtool gcc-c++ libtool-ltdl-devel libevent-devel libc-client-devel cyrus-sasl-devel openldap-devel mysql-devel postgresql-devel unixODBC-devel libxml2-devel net-snmp-devel libxslt-devel libxml2-devel libjpeg-devel libpng-devel freetype-devel libXpm-devel t1lib-devel libmcrypt-devel libtidy-devel freetds-devel aspell-devel recode-devel enchant-devel firebird-devel gdbm-devel tokyocabinet-devel

$ sudo dnf install patch gcc glibc libstdc++ binutils libtool autoconf make bison pam-devel libcap-devel openssl-devel tcp_wrappers-devel bzip2-devel curl-devel db4-devel gmp-devel httpd-devel libstdc++-devel sqlite-devel sqlite2-devel liyuybedit-devel pcre-devel libtool gcc-c++ libtool-ltdl-devel libevent-devel libc-client-devel cyrus-sasl-devel openldap-devel mysql-devel postgresql-devel unixODBC-devel libxml2-devel net-snmp-devel libxslt-devel libxml2-devel libjpeg-devel libpng-devel freetype-devel libXpm-devel t1lib-devel libmcrypt-devel libtidy-devel freetds-devel aspell-devel recode-devel enchant-devel firebird-devel gdbm-devel tokyocabinet-devel

$ sudo apt-get build-essential pkg-config openssl libssl-dev openssl-blacklist openssl-blacklist-extra  bison autoconf automake libtool re2c flex libxml2-dev libssl-dev libbz2-dev libcurl4-openssl-dev libdb5.1-dev libjpeg-dev libpng12-dev libXpm-dev libfreetype6-dev libt1-dev libgmp3-dev libc-client2007e-dev libldap2-dev libmcrypt-dev libmhash-dev freetds-dev zlib1g-dev libmysqlclient-dev libncurses5-dev libpcre3-dev unixODBC-dev libsqlite0-dev libaspell-dev libreadline6-dev librecode-dev libsnmp-dev libtidy-dev libxslt-dev libt1-dev

This will install the basic dependencies for the semi feature rich PHP that you will compile in the next section.

Compile

Now that the dependencies have been installed you can work on compiling PHP.

Info

You can change 7.3.11 in the following commands with the version of PHP you wish to compile.

First, you will need to download and extract PHP. This can be done by running the following in a command line:

$ sudo cd /tmp
$ sudo wget https://www.php.net/distributions/php-7.3.11.tar.gz
$ sudo tar -xf php-7.3.11.tar.gz
$ sudo cd php-7.3.11

Now that PHP has been download and extracted, in the source code folder run ./configure with “--with-litespeed” and other configuration options. For example, you can run the following:

$ sudo ./configure  '--prefix=/usr/local/lsws/lsphp73' '--with-libdir=lib64' '--with-zlib' '--with-gd' '--enable-shmop' '--enable-sockets' '--enable-sysvsem' '--enable-sysvshm' '--with-curl' '--with-openssl' '--with-gettext' '--with-mcrypt' '--enable-mbstring=all' '--enable-mbregex' '--with-png-dir=/usr' '--with-jpeg-dir=/usr' '--with-kerberos' '--enable-ftp' '--with-imap=/usr' '--with-imap-ssl' '--with-mysql=/usr' '--with-mysqli=/usr/bin/mysql_config' '--enable-pcntl' '--with-freetype-dir=/usr' '--with-pdo-mysql=/usr' '--with-litespeed'

Info

It is absolutely required to run ./configure with --with-litespeed if you want to build PHP with LSAPI. the other options are not required but we do recommend setting a --prefix so PHP does not install to the default location and break any system PHPs you may already have installed. This --prefix can be changed to whatever you want the path to be.

Now that PHP is configured to be compiled you can compile it. This is accomplished by running these commands in a terminal:

$ sudo make
$ sudo make install

Info

During the make process it is possible to run into dependency issues depending on the configuration options you have set. We recommend searching Stack Overflow to install these missing dependencies as this is a very common and operating system specific issue that others have probably already solved.

Once make install is finished then LSPHP is all set to go. You can continue to the Setup section.

Setup

Setting up PHP on LiteSpeed Web Server is simple with the induction of the PHP section starting in LSWS version 5.3. For control panel environments the PHP is auto detected and if needed can be overridden on a per setup basis. This setup will show you how to manually setup the PHP section to work with the binaries on your system to serve PHP files.

Settings

Using the PHP method requires LiteSpeed Web Server 5.3 or higher. You will only need to set up all of your PHP rules in the new PHP section of LSWS. Here are the various settings to configure that we offer for each section.

PHP Global Configuration
Title Value Description
Detached Mode Yes Run PHP handler processes detached from the main LiteSpeed worker process.
Default PHP Versions Not Set A list of PHP versions to use as the default ".php" handler when a ".php" handler has not been explicitly set through a script handler or the Handled suffixes configuration.
Control Panel Auto Detect Auto detect PHP handlers based on the control panel used.
CloudLinux Alt PHP Not Set Detect cloudlinux alt PHP handlers.
SuEXEC Handlers Not Set List of file suffixes associated with handlers in suEXEC mode.
Enable CRIU No Enable Checkpoint/Restore In Userspace (CRIU) functionality.
CRIU Dump Min Reqs 2 Minimum number of requests before triggering a CRIU dump.
CRIU Debug Yes Turn on CRIU debug logging.

Notes

Enable CRIU should be set to No unless you know how to troubleshoot CRIU.

PHP Handlers
Title Value Description
Handler ID php81 A unique ID used to associate this PHP handler's command to it's handled suffixes. The ID itself will also be treated as a handled suffix.
Command /usr/local/lsws/bin/lsphp81/bin/lsphp Command used to start the PHP handler.
Handled Suffixes php Extra file "suffixes" to be handled by this handler.
Notes blank Add notes for yourself.

Notes

Each Handler ID value needs to be unique. Handled Suffixes should be unique as well.

Notes is not a required field

PHP Handler Defaults
Title Value Description
Max Connections 35 Specifies the maximum number of concurrent connections that can be established between the server and an external application.
Environment PHP_LSAPI_CHILDREN=35 Specifies extra environment variables for the external application.
Initial Request Timeout 60 Specifies the maximum time in seconds the server will wait for the external application to respond to the first request over a new established connection.
Retry Timeout 0 Specifies the period of time that the server waits before retrying an external application that had a prior communication problem.
Connection Keepalive Timeout 1 Specifies the maximum time in seconds to keep an idle persistent connection open.
Response Buffering No Specifies whether to buffer responses received from external applications.
Back Log 100 Specifies the backlog of the listening socket. Required if Start By Server is enabled.
Run On Startup Yes (Detached mode) Specifies whether to start the external application at server start up.
Max Idle Time 10 Specifies the maximum idle time before an external application is stopped by the server, freeing idle resources.
Priority 0 Specifies priority of the external application process.
Memory Soft Limit 2047M Specifies the memory consumption limit in bytes for an external application process or an external application started by the server.
Memory Hard Limit 2048M Much The same as Memory Soft Limit (bytes), except the soft limit can be raised up to the hard limit from within a user process.
Process Soft Limit 400 Limits The total number of processes that can be created on behalf of a user.
Process Hard Limit 500 Much The same as Process Soft Limit, except the soft limit can be raised up to the hard limit from within a user process.

Notes

Max Connections and PHP_LSAPI_CHILDREN values need to match. In this case both need to equal 35.

Setup

GUI

Here are the step-by-step instructions for how to set up the PHP section via our GUI:

  1. Go to your WebAdmin Console (https://YOUR_SERVER_IP:7080) and log in.
  2. Navigate to Configuration > Server > PHP.
  3. While on this page be sure to fill in all the required fields. For default values and recommended values you can hover over the tooltip icon or reference this section here. Once everything is filled out be sure to hit Save. !webadmin-extapp-php
  4. Now that everything has been set up, navigate to Actions and press the icons next to Restart Detached PHP Processes and then Apply Changes / Graceful Restart. !webadmin-restart

That is it! PHP is now fully set up and pages ending in the suffixes you put for your PHP Handler will use the PHP Handlers > Command to process the page.

Command Line

It is possible to set up the use of the PHP section manually via a terminal. Open /usr/local/lsws/conf/httpd_config.xml with your favorite editor (nano, vim, emacs, etc). An example when using, vi:

$ sudo vi /usr/local/lsws/conf/httpd_config.xml

Then in the main <httpServerConfig></httpServerConfig> block, add the following:

<phpConfig>
  <detachedMode>1</detachedMode>
  <controlPanel>auto</controlPanel>
  <criuEnabled>0</criuEnabled>
  <criuDumpReqs>2</criuDumpReqs>
  <criuDebug>1</criuDebug>
  <phpHandler>
    <id>php81</id>
    <command>/usr/local/lsws/lsphp81/bin/lsphp</command>
    <suffixes>php</suffixes>
  </phpHandler>
  <maxConns>35</maxConns>
  <env>PHP_LSAPI_CHILDREN=35</env>
  <initTimeout>60</initTimeout>
  <retryTimeout>0</retryTimeout>
  <pcKeepAliveTimeout>1</pcKeepAliveTimeout>
  <respBuffer>0</respBuffer>
  <backlog>100</backlog>
  <runOnStartUp>3</runOnStartUp>
  <extMaxIdleTime>60</extMaxIdleTime>
  <memSoftLimit>2047M</memSoftLimit>
  <memHardLimit>2048M</memHardLimit>
  <procSoftLimit>400</procSoftLimit>
  <procHardLimit>500</procHardLimit>
</phpConfig>

Notes

It is possible that the <phpConfig></phpConfig> block is already there inside of <httpServerConfig></httpServerConfig>. In this case just change/append to this section using the values here.

Inside of <phpHandler></phpHandler> make sure each <id></id> is unique or it can cause issues when you restart LiteSpeed Web Server.

To have the changes you have just made to /usr/local/lsws/conf/httpd_config.xml take effect inside of LiteSpeed Web Server run the following: 

$ sudo touch /usr/local/lsws/admin/tmp/.lsphp_restart.txt
$ sudo systemctl restart lsws