How to Load Third-Party PHP Extensions in ServBay

ServBay comes with a set of commonly used PHP extension modules that users can easily configure and enable in the language - PHP version - extensions section.

However, there are times when users need to load modules that are not included with ServBay. This article will explain how to achieve this.

ServBay allows users to flexibly load third-party extensions for its managed PHP environment. This document will use ionCube Loader as an example to guide you through the entire process. This approach also applies to loading other Zend extensions or user-compiled PHP extensions (.so files).

Note: ionCube Loader is a Zend extension, so you need to use the zend_extension directive in the configuration, not the extension directive.

Prerequisites

• You have installed and are running ServBay.
• You have administrative privileges to access system files and the ServBay configuration interface.
• You are familiar with using the Terminal application on macOS.

Note

ServBay provides native architecture PHP packages for both Intel and Silicon (M1/M2/M3/M4) chips. When loading .so files, make sure the compiled architecture of the loaded .so file matches the architecture of the ServBay package.

Files with differing architectures cannot be mixed; an architecture mismatch will crash PHP.

1. Determine the architecture of the PHP package that comes with ServBay:

file /Applications/ServBay/package/php/8.3/current/bin/php

The output will be similar to:

php: Mach-O 64-bit executable arm64 # Silicon Arm64 architecture
php: Mach-O 64-bit executable x86_64 # Intel x86 architecture

2. Determine the architecture of the so file you need to install:

file xdebug.so

The output will be similar to:

xdebug.so: Mach-O 64-bit bundle arm64 # Silicon Arm64 architecture
xdebug.so: Mach-O 64-bit bundle x86_64 # Intel x86 architecture

Steps to Follow

Step 1: Download ionCube Loader

1. Visit the official download page for ionCube Loader. For macOS ARM64 (Apple Silicon M series chips), download the Darwin ARM64 version. You can directly use the following link (check for updates): https://downloads.ioncube.com/loader_downloads/ioncube_loaders_dar_arm64.tar.gz
2. After downloading, you will receive a .tar.gz compressed file, such as ioncube_loaders_dar_arm64.tar.gz.

Step 2: Identify the Target PHP Version and Extension Directory

1. Open the ServBay application.

2. In the left navigation bar, click on Languages.

3. In the right list, find the PHP version for which you want to install ionCube Loader (for example, in this case PHP 8.3). Note down this version number.

4. ServBay's PHP extensions are typically located in a specific path. Based on ServBay's standard installation structure and screenshot examples, the extension directory for PHP 8.3 may look like: /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/

   • /Applications/ServBay/package/php/ is the base path for ServBay PHP packages.
   • 8.3/ is the main version directory.
   • 8.3.16/ is the specific PHP version directory (adjust according to your installed version).
   • lib/php/extensions/ is the parent directory for extensions.
   • no-debug-non-zts-xxxxxxxx/ is the directory for the specific API version and compile options (this directory name will change with PHP versions).

   Important: You need to determine or find this exact path based on the actual PHP version and architecture installed in ServBay. You can also find it using a terminal command (ensure you use the PHP path managed by ServBay):

   /Applications/ServBay/package/php/8.3/current/bin/php -i | grep extension_dir

   Replace /Applications/ServBay/package/php/8.3/current/bin/php with the actual path of the php executable for your target PHP version. The command output will show extension_dir => /path/to/extension/directory.

Step 3: Extract and Place the Loader Files

1. Open the Terminal application.
2. Use the cd command to navigate to the directory where you downloaded the .tar.gz file (usually the Downloads directory).

   cd ~/Downloads

3. Extract the downloaded file:

   tar -zxvf ioncube_loaders_dar_arm64.tar.gz

   This will create a directory named ioncube.
4. Enter the ioncube directory:

   cd ioncube

5. In this directory, you will see corresponding .so files for different PHP versions, such as ioncube_loader_dar_8.3.so. Find the file that matches your target PHP version (as determined in Step 2, such as 8.3).
6. Copy this matching .so file to the PHP extension directory you identified in Step 2. Assuming the target directory is the path given earlier and you want to install the Loader for PHP 8.3:

   cp ioncube_loader_dar_8.3.so /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/

   • Be sure to replace the target path with the actual extension directory path for your PHP version.
   • Make sure to copy the .so file that matches the exact PHP version.

Step 4: Configure PHP in ServBay

1. Go back to the ServBay application interface.

2. Ensure Languages is selected on the left, then click the PHP version you want to configure (for example, PHP 8.3) in the right list.

3. In the expandable configuration area on the right, click the PHP tab (as indicated by the arrow in the image below).

4. Scroll down to find the Additional Parameters text box.

5. In this text box, add the following line (as indicated by the arrow in the image below), specifying the relative path of the ionCube Loader file:

   zend_extension = ioncube_loader_dar_8.3.so

   • Again, emphasize: The so file must be strictly placed in the extension_dir path obtained in Step 3. Please check carefully.
   • Use zend_extension instead of extension because ionCube Loader is a Zend extension.
   • If there are other configurations already in this text box, add this directive on a new line.

   

6. Click the Save button in the lower right corner to save the configuration.

Step 5: Restart PHP Service

After clicking the save button, ServBay has automatically restarted the PHP service.

Step 6: Verify if the Load was Successful

You can verify if ionCube Loader has loaded successfully in two ways:

1. Via Command Line:

   • Open the terminal.

   • Run the following command (ensure to use the full path of the target PHP version):

     /Applications/ServBay/package/php/8.3/current/bin/php -m | grep -i ioncube

     If loading was successful, you should see an output similar to ionCube Loader.

   • You can also run php -v to see version information, which usually shows related information after loading ionCube:

     /Applications/ServBay/package/php/8.3/current/bin/php -v

     Sample output:

     PHP 8.3.16 (cli) (built: Jan 31 2025 15:09:39) (NTS)
     Copyright (c) The PHP Group
     Zend Engine v4.3.16, Copyright (c) Zend Technologies
         with the ionCube PHP Loader v14.4.0, Copyright (c) 2002-2024, by ionCube Ltd.

2. Via phpinfo():

   • Create a PHP file containing <?php phpinfo(); ?> (for example, info.php) and place it in the root directory of your website.
   • Access this file through your browser (e.g., http://your-local-site.test/info.php).
   • Search for "ionCube" in the phpinfo() output page. If loaded successfully, you will see a dedicated ionCube Loader information block showing version and other details.

Summary

By following the above steps, you should be able to successfully load the ionCube Loader or other third-party PHP extensions for the specific PHP version managed by ServBay. The key is to find the correct extension file, determine the correct PHP extension directory, and add the proper directive in the ServBay configuration (zend_extension or extension). If you encounter issues, please carefully check the paths, file permissions, and whether the PHP service has been restarted.