How to Load Third-Party PHP Extensions in ServBay

ServBay is a powerful local web development environment that comes with many commonly used PHP extensions pre-installed. Typically, users only need to configure and enable extensions via Packages -> Languages -> PHP Version -> Extensions within ServBay.

However, developers may occasionally need to load third-party or custom-compiled PHP extensions not included with ServBay by default. This article will provide detailed step-by-step instructions on how to load such extensions for a specific PHP version within ServBay, using ionCube Loader as an example. The process also applies to other Zend extensions or any .so extension files you have compiled.

Special Note about Zend Extensions: ionCube Loader is a Zend extension, which interacts more deeply with PHP’s Zend Engine. Therefore, you must use the zend_extension directive when configuring it, instead of the regular extension directive meant for standard extensions. Be sure to distinguish and use them correctly.

Prerequisites

• You have ServBay installed and running on macOS.
• You have administrator privileges to access system files and ServBay configuration.
• You are familiar with using the Terminal app on macOS.
• You have obtained the third-party PHP extension file you want to load (typically a .so file), and this file is fully compatible with your target PHP version in ServBay, matching its version, architecture (Intel or Apple Silicon), and compilation options (like NTS/ZTS).

Note: Architecture compatibility is critical

ServBay provides native PHP packages for both Intel (x86_64) and Apple Silicon (ARM64, such as M1/M2/M3/M4 chips) architectures. When loading .so extension files, it is vital to ensure that the compiled architecture of your .so file matches the architecture of the corresponding PHP package in ServBay.

Do not mix files of different architectures. Incompatibility will prevent PHP from starting or cause it to crash.

You can use the file command to check the architecture of an executable or .so file:

1. Check the architecture of the ServBay-supplied PHP package (replace 8.3 with the PHP version you're using):

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

   Sample output:

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable arm64 # Indicates Apple Silicon ARM64 architecture

   or

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable x86_64 # Indicates Intel x86_64 architecture

2. Check the architecture of your downloaded or compiled .so extension file (replace xdebug.so with your extension filename):

   file xdebug.so

   Sample output:

   xdebug.so: Mach-O 64-bit bundle arm64 # Indicates Apple Silicon ARM64 architecture

   or

   xdebug.so: Mach-O 64-bit bundle x86_64 # Indicates Intel x86_64 architecture

   Ensure that the architecture reported in step 1 and step 2 are an exact match.

Step-by-Step Instructions

Step 1: Download the Third-Party Extension File (Taking ionCube Loader as an Example)

1. Visit the official ionCube Loader download page. Choose the version appropriate for your macOS architecture. For macOS ARM64 (Apple Silicon M series chips), download the Darwin ARM64 version. You can use the link below as a sample (make sure to check the official site for the latest version): https://downloads.ioncube.com/loader_downloads/ioncube_loaders_dar_arm64.tar.gz
2. After downloading, you will get a .tar.gz archive, e.g., ioncube_loaders_dar_arm64.tar.gz.

Step 2: Identify the Target PHP Version & ServBay Extension Directory

1. Open the ServBay application.

2. In the side navigation, click Packages under Languages.

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

4. Identify the extension installation directory (extension_dir) for this PHP version in ServBay. This is the standard location for .so files. The path depends on your ServBay installation, PHP version, and compilation options.

   The most reliable way is to check via the terminal:

   Open the Terminal application and run the following command (replace /Applications/ServBay/package/php/8.3/current/bin/php with the actual path to your target PHP version’s binary):

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

   The output will show extension_dir => /path/to/extension/directory. For example:

   extension_dir => /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831

   Make note of this exact path for later steps.

Step 3: Extract and Place the Loader File

1. Open the Terminal app.

2. Use the cd command to navigate to the directory where you downloaded the .tar.gz file (commonly ~/Downloads):

   cd ~/Downloads

3. Extract the downloaded file:

   tar -zxvf ioncube_loaders_dar_arm64.tar.gz

   This will create a new ioncube directory.

4. Enter the ioncube directory:

   cd ioncube

5. In this directory, you will see .so files for different PHP versions, e.g., ioncube_loader_dar_8.3.so. Locate the file that matches your target PHP version (as determined in step 2, e.g. 8.3).

6. Copy this matching .so file to the PHP extension directory you identified earlier. For example, if your target directory is /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/ 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 /Applications/ServBay/.../no-debug-non-zts-20230831/ with the actual extension directory path you found in step 2 using the php -i command.
   • Ensure you copy the .so file that exactly matches your target PHP version, and that its architecture matches the PHP package’s architecture (see Architecture Compatibility in prerequisites).

Step 4: Configure PHP in ServBay

1. Return to the ServBay application.

2. Make sure Languages is selected in the left pane, and click the PHP version you wish to configure (e.g., PHP 8.3) in the right list.

3. In the configuration section that expands on the right, go to the PHP tab.

4. Scroll down to find the Additional Parameters textbox.

5. Add the following line to this textbox to specify the ionCube Loader filename:

   zend_extension = ioncube_loader_dar_8.3.so

   • Important: Replace ioncube_loader_dar_8.3.so with the actual filename you copied into the extension directory.
   • Use zend_extension and not extension because ionCube Loader is a Zend extension.
   • Since the .so file is in the extension_dir, only the file name is needed—no need to provide the full path.
   • If there are other directives in this textbox, add this one on a new line.

   (Screenshot is for reference only and may vary slightly by version)

6. Click the Save button at the bottom right to save your settings.

Step 5: Restart PHP Service

After clicking Save in ServBay, it will automatically detect the configuration change and attempt to smoothly restart the relevant services (including PHP). Usually, no extra manual restart is required.

Step 6: Verify the Extension Was Loaded Successfully

You can confirm ionCube Loader was loaded using either of these common methods:

1. Via the Command Line:

   • Open Terminal.

   • Run the following command to list loaded PHP modules (use the full path to your PHP binary):

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

     If successful, you should see a line like ionCube Loader.

   • You can also use php -v to check PHP version info. If ionCube Loader is loaded, it will be displayed below the Zend Engine version info:

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

     Example output after successful loading (version numbers may differ):

     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.

     Note the line with the ionCube PHP Loader ...

2. Via the phpinfo() Function:

   • In your website's root directory (e.g., /Applications/ServBay/www/servbay.demo/ or any other configured site path), create a new PHP file such as info.php.
   • In this file, add:

     <?php
     phpinfo();
     ?>

   • In your browser, open this file (e.g., http://servbay.demo/info.php; replace with your own site domain).
   • On the opened phpinfo() page, search for "ionCube" (use your browser's find function, typically Cmd + F or Ctrl + F). If loaded, you will see a dedicated ionCube Loader section with version, license, and other details.

If either of these verification steps displays ionCube Loader information, the extension is successfully loaded.

Common Issues & Troubleshooting

• PHP fails to start or crashes: The most common cause is that the extension file's architecture does not match the PHP package's architecture. Closely follow the steps in the prerequisites to make sure they're identical. Incompatible PHP versions or build options may also cause this.
• extension_dir path error: Make sure you copied the .so file to the actual extension_dir path for this PHP version in ServBay. Use php -i | grep extension_dir to get the exact path.
• Directive misconfiguration: Double-check the directives you added to Additional Parameters in ServBay. For Zend extensions, you must use zend_extension = filename.so; for regular extensions, use extension = filename.so. The filename must match exactly (including case) with what you placed in extension_dir.
• File permission issues: Ensure the ServBay running user (usually your macOS user) has read access to the copied .so file and its directory. Normally, this is not an issue, but if you modified permissions manually, check them.
• ServBay did not restart: Although ServBay will usually restart automatically, if the changes take no effect, try manually stopping and starting the relevant services from the ServBay interface or restart the application.
• Unable to find extension info in phpinfo(): Ensure you are viewing the correct phpinfo() page for the PHP version and site managed by ServBay where you configured the extension. If you have multiple PHP versions or websites, make sure you are checking the right environment.

Summary

By following the detailed steps above, you should be able to successfully load ionCube Loader or other third-party .so PHP extensions for a specific PHP version managed by ServBay. The keys to success are accurately identifying your target PHP version, finding the correct extension installation directory (extension_dir), placing a compatible extension file there, and referencing its name with the proper directive (zend_extension or extension) in ServBay’s Additional Parameters configuration. If you encounter issues, carefully review each stage as described in the troubleshooting section, especially architecture compatibility and file paths.