Compiling and Installing Custom PHP Modules in ServBay

ServBay is a powerful local web development environment for both macOS and Windows. It integrates a wide range of software packages to meet the diverse needs of modern web developers. Preinstalled stacks include PHP, Node.js, Python, Go, Java, databases (MySQL, PostgreSQL, MongoDB), caching (Redis), and web servers (Caddy, Nginx, Apache), all with multi-version support. You can effortlessly switch environments to match your project requirements.

Although ServBay comes with many popular PHP modules, there may be scenarios where you need to compile and install additional modules to expand PHP's capabilities or integrate specific third-party services.

This guide provides a detailed walkthrough on compiling and installing custom modules for your desired PHP version in ServBay. We'll use the popular imagick image processing module and the sqlsrv Microsoft SQL Server database driver as examples, covering the entire process so you can easily extend the PHP environment in ServBay.

Prerequisites

Important Note

The most critical step before compiling any PHP module is to initialize the build environment and correctly set system environment variables according to ServBay’s official documentation. This forms the foundation for successful compilation of ServBay packages, including PHP modules. Skipping or improperly performing this operation will almost certainly result in failures during compilation, such as missing commands, libraries, or header files.

ServBay’s environment initialization script sets essential environment variables like PATH (pointing to ServBay's build tools), SERVBAY_PACKAGE_FULL_PATH (root directory of ServBay packages), and CPU_NUMBER (for multi-core compilation). These are crucial for subsequent build commands.

For detailed steps on initializing the ServBay build environment, please refer to the documentation: Rebuilding Packages with ServBay. Be sure to thoroughly understand and strictly follow the setup as described there.

Before proceeding with module compilation, ensure that you have successfully completed ServBay’s build environment initialization and the necessary environment variables are set in your current command-line session.

The Importance of Specifying PHP Version

A key feature of ServBay is its support for installing and running multiple PHP versions simultaneously. This flexibility allows developers to easily switch PHP environments for different projects. However, when compiling PHP modules, you must target a specific PHP version. The tools used to prepare the build and retrieve version configuration—phpize and php-config—are tightly bound to the version you plan to compile against.

• phpize: Prepares the PHP extension build environment, reading the module's config.m4 file to generate a standard configure script—the usual starting point for C/C++ compilation.
• php-config: Supplies detailed configuration information for a particular PHP installation, such as compiler flags, include paths, library directories, extension install paths, etc. The configure script uses php-config to ensure the extension is built and linked to the correct PHP version.

Thus, when using phpize, php-config, or any related build commands, always specify the full path to the PHP version you intend to use.

Example Paths

To compile a module for ServBay PHP 8.3:

macOS:

• phpize: /Applications/ServBay/package/php/8.3/current/bin/phpize
• php-config: /Applications/ServBay/package/php/8.3/current/bin/php-config

Windows:

• phpize: C:\ServBay\package\php\8.3\current\bin\phpize
• php-config: C:\ServBay\package\php\8.3\current\bin\php-config

Choosing the correct version ensures the compiled module is compatible with your target PHP environment, avoiding build errors and runtime "missing symbol" issues.

This documentation uses PHP 8.3 in ServBay for the examples. Replace paths in commands with the exact PHP version you need in your own ServBay installation.

Compiling the PHP imagick Module

The imagick module is a widely-used PHP extension that leverages the powerful ImageMagick command-line library, providing extensive image manipulation capabilities. With imagick, you can perform resizing, cropping, format conversion, watermarking, image composition, and more—all directly in PHP. The steps below detail how to compile and install the imagick module for your chosen PHP version in ServBay:

Step 1: Install ImageMagick Dependencies

imagick depends on the system-wide ImageMagick library.

macOS

Recommended installation via Homebrew. If you haven't installed Homebrew, visit Homebrew Official Site for instructions.

Open Terminal and run:

brew install imagemagick

Windows

On Windows, download and install ImageMagick manually from the ImageMagick download page.

During installation, select the version with development libraries and add the install path to your system's environment variables.

Step 2: Obtain the imagick Module Source Code

Download the imagick module source package from PECL. Visit the PECL imagick page for the version you need (usually the latest stable release). For example, using version 3.7.0:

wget https://pecl.php.net/get/imagick-3.7.0.tgz

Step 3: Extract Source Package and Enter Directory

After downloading, extract the tarball and switch to the source directory:

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

Step 4: Prepare the Build Environment (phpize)

From the source directory, use the correct PHP version’s phpize tool to prep the build environment. Always use the full path for your target PHP version. Assuming PHP 8.3 and the SERVBAY_PACKAGE_FULL_PATH variable are set:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

If successful, phpize will generate the configure script and other necessary build files based on the config.m4 file in the source.

Step 5: Configure Build Options

Now run the newly created configure script, specifying the path to your desired PHP version’s php-config program via --with-php-config:

./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

This runs several checks (including searching for ImageMagick libraries and headers), and generates the Makefile for compilation. If you see errors, check if required dependencies are missing or paths are incorrect.

Step 6: Compile and Install the Module

Once configured, compile with make, using ${CPU_NUMBER} for parallel builds, then install:

make -j ${CPU_NUMBER}
make install

make install copies the built extension file to the version-specific PHP extensions directory in ServBay:

• macOS: /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/
• Windows: C:\ServBay\package\php\8.3\current\lib\php\extensions\no-debug-non-zts-YYYYMMDD\

The exact path depends on your PHP version and build settings.

Step 7: Enable the Module

After installing the module file, enable it in the configuration for your target PHP version via ServBay’s GUI:

• Launch ServBay
• In the left menu, navigate to Languages > PHP > PHP 8.3
• Go to the PHP tab, scroll down to "Additional Parameters," and enter extension=imagick.so
• Click Save. ServBay automatically restarts PHP to load the newly added module.

Step 8: Verify the Module Is Loaded

After enabling the module, restart the PHP service in ServBay for changes to take effect. You can do this from the ServBay admin panel (find the PHP version, click restart) or via ServBay CLI tools (see the ServBay docs).

To check if imagick is loaded, run:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep imagick

This uses the specific PHP executable in ServBay. The -m flag lists all loaded PHP modules. If successful, you’ll see imagick in the output.

For more detailed verification, create a PHP file (e.g., info.php) in your web root containing <?php phpinfo(); ?>. ServBay’s default web root:

• macOS: /Applications/ServBay/www
• Windows: C:\ServBay\www

Then view http://localhost/info.php or your configured ServBay domain in the browser, and search for "imagick" in the phpinfo() output to confirm it’s enabled and check its version/settings.

Compiling PHP sqlsrv/pdo_sqlsrv Modules

The sqlsrv and pdo_sqlsrv modules are official PHP extensions for connecting to and using Microsoft SQL Server databases. They require the Microsoft ODBC driver. To connect PHP in ServBay to SQL Server, you’ll need to compile/install these modules as follows:

Note: Critical Prerequisites

Before compiling and installing the sqlsrv module, you must first install Microsoft's SQL Server ODBC driver and related tools. ServBay does not include these—they must be installed manually.

macOS

Install dependencies via Homebrew (see Homebrew Official Site if needed).

To install Microsoft ODBC drivers and tools (you may need to agree to the EULA by setting HOMEBREW_ACCEPT_EULA=Y):

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18

These will typically install under /opt/homebrew/ for Apple Silicon Macs, or /usr/local/ for Intel Macs. You'll need to reference the correct paths during compilation.

Windows

Download and install the ODBC Driver for SQL Server from Microsoft:

• Visit Microsoft ODBC Driver for SQL Server
• Download and install the version suitable for your system
• Ensure the driver is correctly installed and accessible.

Do not proceed until these dependencies are successfully installed.

Tip

sqlsrv and pdo_sqlsrv are separate modules and must be compiled individually, but the steps are very similar. Below, we'll use sqlsrv as an example.

Step 1: Install Microsoft ODBC Drivers and Tools

(As outlined above, ensure you've used Homebrew to install msodbcsql18 and mssql-tools18.)

Step 2: Obtain the sqlsrv Module Source Code

Download the sqlsrv and pdo_sqlsrv source packages from PECL. Visit the PECL sqlsrv page for the latest or desired version. Example using 5.12.0:

wget https://pecl.php.net/get/sqlsrv-5.12.0.tgz  # sqlsrv
wget https://pecl.php.net/get/pdo_sqlsrv-5.12.0.tgz  # pdo_sqlsrv

Step 3: Extract Source Package and Enter Directory

Extract the package and switch to the source directory:

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# Same applies for pdo_sqlsrv; example continues with sqlsrv.

Step 4: Prepare the Build Environment (phpize)

Use the full path to your desired PHP version’s phpize:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

Step 5: Configure Build Options (including Dependency Paths)

Because sqlsrv relies heavily on Homebrew’s Microsoft ODBC and unixODBC libraries, set LDFLAGS and CPPFLAGS environment variables to ensure the build scripts find the required headers and libraries, then run configure with the proper PHP config path.

Adjust paths based on your Homebrew location (/usr/local for Intel Macs, /opt/homebrew for Apple Silicon). Using /opt/homebrew as the example:

export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}" # Add /opt/homebrew/include to ensure all headers are found
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

• LDFLAGS: Tells the linker where to find library files, such as -L/opt/homebrew/lib.
• CPPFLAGS: Points to header file locations; -I/opt/homebrew/opt/unixodbc/include for unixODBC headers, -I/opt/homebrew/include for other necessary headers. ${CPPFLAGS}/${LDFLAGS} preserve additional flags set by ServBay or your shell.

Step 6: Compile and Install the Module

Once configured and the Makefile is created, run:

make -j ${CPU_NUMBER}
make install

make install will copy the built sqlsrv.so and pdo_sqlsrv.so extensions (if compiled together) into the PHP extension directory for that ServBay PHP version.

Step 7: Enable the Module

After installation, enable the module in your target PHP version via ServBay's GUI:

• Launch ServBay
• Navigate to Languages > PHP > PHP 8.3
• Go to the PHP tab, scroll down to "Additional Parameters," and enter extension=sqlsrv.so and extension=pdo_sqlsrv.so
• Click Save; ServBay will restart PHP and apply the module changes

Step 8: Verify the Module Is Loaded

After enabling, be sure to restart the PHP service in ServBay.

To verify that sqlsrv and pdo_sqlsrv are loaded:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep sqlsrv
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep pdo_sqlsrv

If loaded, sqlsrv and pdo_sqlsrv will show up in the output. You can also confirm using the output from a phpinfo() page.

Frequently Asked Questions (FAQ)

• Q: Compilation fails with "Cannot find autoconf" or similar errors?
  • A: Almost certainly, ServBay’s build environment was not properly initialized. Go back to the "Prerequisites" section above and carefully follow the Rebuilding Packages with ServBay documentation—ensure build tools (autoconf, automake, libtool, etc.) are installed and referenced correctly. Usually, re-running ServBay's environment script and restarting your terminal resolves this.
• Q: configure script fails to find a library or header file?
  • A: This means a required system library/header is missing or its path is not found:
    • For imagick, verify that the ImageMagick development libraries are installed (brew install imagemagick).
    • For sqlsrv, always confirm that Microsoft's ODBC drivers (msodbcsql18) and mssql-tools18 have been installed via Homebrew. Check that LDFLAGS and CPPFLAGS properly reference the Homebrew library and header paths (e.g. /opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include).
    • Ensure ServBay’s environment settings include the Homebrew paths (if dependencies were installed via Homebrew), or manually add Homebrew’s bin/lib/include folders to your PATH.
• Q: make or make install fails?
  • A: Possible causes:
    • Missing build dependencies: Review error output—install any missing files or libraries.
    • Configuration errors: Double check that --with-php-config points to the correct ServBay PHP version.
    • Permission issues: Installing files into ServBay’s extension directory may require appropriate permissions. Try sudo make install if needed (only if you understand the risks).
    • Source issues: Confirm the downloaded module source is complete and not corrupt.
• Q: The .so module file is present and enabled in .ini, but php -m or phpinfo() does not show it?
  • A:
    • Most likely: The ServBay PHP service has not been restarted. After editing .ini, use ServBay's panel or CLI to fully restart the target PHP version. Just refreshing the web page or restarting only the web server (Caddy/Nginx) is not enough—the PHP service itself must be restarted.
    • Check .ini file syntax for typos or formatting errors (extension=modulename.so).
    • Confirm extension_dir in php.ini points to the correct ServBay PHP extension directory. make install uses the path given by php-config --extension-dir.
    • Module is corrupted or incompatible: recompile, making sure you used compatible source and PHP versions, and check ServBay’s PHP logs for errors.

Summary

By carefully following this guide, you should be able to successfully compile and install custom PHP modules like imagick and sqlsrv in your ServBay local development environment. The essentials are:

1. Fully initialize the ServBay build environment—this is the foundation for all further compilation tasks.
2. Precisely specify and use the correct PHP version paths—always use the full path for phpize and php-config to target the desired PHP version.
3. Resolve all external module dependencies—install required system libraries or tools (ImageMagick, Microsoft ODBC driver, etc.) and correctly specify their paths during configuration (using environment variables like LDFLAGS, CPPFLAGS).
4. Correctly enable extensions—create or update .ini files with extension=modulename.so in your target PHP's conf.d directory.
5. Restart the ServBay PHP service—to activate new module settings.

ServBay is a robust, all-in-one development environment that flexibly supports a vast array of development stacks—beyond PHP, it also offers built-in support for MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust, and more. It provides valuable features such as real SSL certificate application via ACME, easy CORS configuration, automated data backup (including settings, sites, databases, SSL certs), database root reset, and ServBay User CA/Public CA for local HTTPS development—empowering you to build efficient and functional local workflows.

We hope this guide enables you to expand your ServBay PHP environment with the features you need, streamlining your web development. Should you run into other challenges, consult the ServBay official documentation or community support.