Installing PHP-CPP on RunCloud.io

I’ll be honest – when I’ve wanted to create my own PHP extensions, I’ve simply hidden away from it. It seems daunting, hugely overcomplicated, and a real drain on my time. Then, I stumbled upon PHP-CPP:

A C++ library for developing PHP extensions. It offers a collection of well documented and easy-to-use classes that can be used and extended to build native extensions for PHP.

This C++ library makes building PHP extensions fun. Extensions built on top of PHP-CPP are easy to understand and simple to maintain, and your code looks great – and it gives a huge boost to your application!

Easy to understand? Simple to maintain? I’m sold! On the face of it, it looks relatively easy to set up – but, as is often the case, my use case makes it not so easy.

Introducing RunCloud.io

RunCloud.io is a fantastic control panel for servers which allows you to configure websites, databases, set security rules, view server health statistics, and so much more. For websites, you can switch between a variety of PHP versions, change PHP settings, set up SSL/TLS, to name just a few. All very useful.

But there lays the problem. PHP being set up and managed by another person, and multiple versions of PHP being available means that your binaries and directories aren’t in the typical places, or aren’t named what you might expect. So, installing custom PHP extensions can be a little fiddly.

Installing PHP-CPP

This walkthrough will assume you are using PHP 7.4 (check by going to Servers > Server Name > Settings > PHP-CLI Version in the RunCloud control panel, and also note that individual web applications can use different versions of PHP), Ubuntu 20.04 and RunCloud as your control panel.

Install the latest PHP development files:

sudo apt install php7.4-dev

Download the latest version of PHP-CPP from GitHub:

git clone https://github.com/CopernicaMarketingSoftware/PHP-CPP.git

Within the PHP-CPP directory, execute these two commands:

make
make install

PHP should now be set up, so we’ll test it by compiling one of the example extensions provided by PHP-CPP. Upload the contents of the Examples\FunctionReturnValue folder to your server, then within the FunctionReturnValue directory, execute these two commands:

make
make install

It will most likely show you a cp: missing destination file error – this is fine, it’s failed to copy the file to a directory which doesn’t exist, but it’s still compiled the extension.

Find the location of the PHP extension_dir, which should return something like this:

root@dev:~# /RunCloud/Packages/php74rc/bin/php -i | grep extension_dir
extension_dir => /RunCloud/Packages/php74rc/lib/php/extensions/no-debug-non-zts-20190902 => /RunCloud/Packages/php74rc/lib/php/extensions/no-debug-non-zts-20190902

Finally, we copy functionreturnvalue.so, which is the custom extension we just compiled, to the correct location and ask PHP to load it:

cp functionreturnvalue.so /RunCloud/Packages/php74rc/lib/php/extensions/no-debug-non-zts-20190902
echo "extension=functionreturnvalue.so" > /etc/php74rc/conf.d/functionreturnvalue.ini

We can now restart PHP and check that it’s loaded:

root@dev:~# systemctl restart php74rc-fpm

root@dev:~# /RunCloud/Packages/php74rc/bin/php -m | grep my_function_return_value
my_function_return_value

my_function_return_value is the extension name as defined in functionreturnvalue.cpp, so we can see that it’s correctly loaded!

To finish, we create a simple PHP file which calls the custom method within our new extension. Save the file, and upload it to your website:

<?php echo my_return_value_function(); ?>

You should see 42 as the output.

Now that’s pretty easy, right? The PHP-CPP documentation is fairly thorough, so I look forward to digging deeper and creating some more advanced extensions.