Setting up the brotli extension for PHP

The Brotli extension for PHP, integrates the Brotli compression algorithm for use in PHP. Brotli compression is similar to gzip but has a higher compression ratio - up to 30% bandwidth savings. However, it does have a slight drawback; it is slower. This can be worked around most effectively by pre-compressing resources before the web server needs them. Hence with a LAMP stack, using the Brotli PHP extension provides easy performance gains.

Brotli has been found to have significant performance gains for end user most especially those with lower quality internet such as much of rural North America, mobile users and users in developing markets. One high quality analysis and large scale implementation that has been well documented was done in early 2017. Browser support is not yet universal although it is rapidly increasing. In April 2017, support was ~56% of users, as of December 2017, that support level is now up to 72%. CanIUse table showing browser support as of 2017-12-05 for brotli.

For large scale sites there may be many extra considerations such as does your CDN support brotli or will you have to do various tricks to get it to work. But for small to medium sites, usually, it will just work. With Drupal 8, all you need is the the Advanced Aggregates module and the Brotli PHP extension installed and it handles the rest of it - fully automatically for Apache servers. For other PHP based sites, you'll probably have to make use of the functions yourself, but that is beyond the scope of this tutorial (although I can assist with that.)


  • Some command line comfort.
  • Modern Ubuntu or Debian install (other nix variants will also work, but there may be differences).
  • User with sudo privileges. If you don't have that, see Creating a Sudo User.
  • PHP 7.1. Any modern PHP version will work, but in a few of the commands, you'll have to change 7.1 to match your version. The source doesn't matter although I am somewhat assuming Ondřej Surý's PPA. If using a different source, paths may be slightly different.

Getting your development environment ready

If you've already built any PHP extensions, your environment is likely good to go. If, however, you've never built any PHP extensions, you will likely need to do a bit of setup. The setup on Debian based systems is very easy. So you will likely have to install the PHP development extensions. From here on, you'll be working in the command line, so open bash (or your preferred command line).

To install the PHP development extensions, just run:

sudo apt install php7.1-dev

confirming that you do want to install the possibly large number of required packages. Depending on prior installations, your connection speed etc, this may take a while to install and setup.

Building the extension

Now, you need to clone the repository and it's sub repositories.

git clone --recursive --depth=1
cd php-ext-brotli

Next, it needs to be set up for your version of PHP, build scripts configured and the extension gets built. That may sound complicated, but it is very easy and needs no hand coding or user intervention. Just run:

sudo make install clean

This will build and move the module file to /usr/lib/php/20160303/. If using a different PHP version, the date in that path will change to the PHP API version date. Now to enable it, there are a few different methods you can use. In my opinion the best one, is creating an ini file for it so that it can easily be enabled and disabled. So in your command line run:

sudo nano /etc/php/7.1/mods-available/brotli.ini

Add the line and save it (ctrl-O). Now to enable it you can run

sudo phpenmod brotli

Just want to know it is installed correctly from the command line? Run:

php -a
echo is_callable('brotli_compress');

That should return 1.

Advanced Users/Options

Multiple PHP Versions

Depending on your system, or needs, you may want to build for multiple versions of PHP. If so, this can easily be done. Just install the PHP development files for each version you want to target, for example:

sudo apt-install php7.0-dev php7.1-dev php7.2-dev

and run the standard build steps outlined but with a couple of minor adjustments for each version. - Use phpize7.x for each version - Use ./configure --with-php-config=php-config7.x - Creating the brotli.ini in /etc/php/7.x/mods-available/ for your current version.

Quick Code

Know what you're doing and just want copy & paste commands without a bunch of verbiage?

sudo apt install php7.1-dev -y
git clone --recursive --depth=1
cd php-ext-brotli
sudo make install clean
sudo nano /etc/php/7.1/mods-available/brotli.ini

Add the line, save and run sudo phpenmod brotli

Add new comment

The content of this field is kept private and will not be shown publicly.

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.