ServBay PHP Version Management: CLI and Website Environment Configuration Guide

ServBay is a powerful local web development tool designed for macOS, supporting multiple programming languages and databases. This guide details how to flexibly manage different PHP versions for various projects within ServBay—whether running scripts in the command line or serving websites. Mastering ServBay's PHP version management mechanisms will significantly boost your development efficiency and ensure proper environment isolation and stability for each project.

1. Command Line Environment: Managing Project-level PHP Versions with .servbay.config

By creating a .servbay.config file in your project’s root directory, you can specify a dedicated PHP version for each project on the command line. ServBay automatically loads the respective PHP environment based on your current terminal directory, achieving version isolation between projects and preventing global configuration conflicts.

1. Purpose and Principles of .servbay.config

• Project-level Version Control: ServBay supports simultaneous installation and operation of multiple PHP versions, from PHP 5.6 up to the latest stable and development releases. With .servbay.config, you can precisely specify the required PHP version per project.
• Non-Intrusive Switching: When you navigate (cd) into a directory containing a .servbay.config file in your terminal, ServBay automatically detects it and temporarily modifies environment variables for that session (primarily the PATH). This ensures php, composer, and similar commands point to the specified PHP executable. Once you leave the directory, the environment reverts to ServBay’s global default, with no side effects to your system settings.

2. How to Configure

Create a .servbay.config file in your project’s root directory, and specify the PHP version as follows:

# Specify the PHP version for this project (example: use PHP 8.3)
PHP_VERSION=8.3

# If your project also requires a specific Node.js version, specify it as well (example: use Node.js 20)
# NODE_VERSION=20

• The value for PHP_VERSION should be an installed PHP version identifier in ServBay, usually the major or major.minor version (e.g., 7.4, 8.1, 8.3, 8.5). Ensure the specified version is already installed and enabled in ServBay.
• NODE_VERSION works similarly if you need to specify a Node.js version for this project.

How to Verify:

Open a terminal in the directory containing the .servbay.config file, and run the following commands to confirm:

$ pwd # Confirm your present directory is the project root
$ php -v  # Check that the output shows the PHP version you set (e.g., PHP 8.3.x)
$ composer install  # Dependencies will install using the currently activated PHP version

If the PHP version doesn’t switch after editing .servbay.config, try closing and reopening your terminal, or run cd . to force ServBay to reload its configuration.

3. Notes and Advanced Tips

• Version Compatibility: If you encounter errors like "Class not found" or "Call to undefined function" when running project commands, check that your PHP version matches the range required by your dependencies (e.g., composer.json). Some older projects may rely on features or extensions removed in newer PHP versions (such as mcrypt in PHP 7.2).
• Global Defaults: If neither the current nor any parent directory has a .servbay.config file, ServBay falls back to the global default PHP version you configured in its GUI Settings.
• Multi-service Projects: .servbay.config can manage both PHP and Node.js versions (NODE_VERSION). This is useful for projects using PHP as backend and Node.js for frontend build tools (like Webpack or Vite).

4. Usage Example

Here's a demonstration of automatic PHP version switching between project directories, using .servbay.config:

Image caption: In ServBay, entering directories with different .servbay.config files and running php -v shows the terminal automatically switches to the PHP version specified in each file.

2. Website Environment: Managing PHP Versions via the ServBay GUI

ServBay’s graphical interface offers an intuitive way to assign an independent PHP version for each website. The website environment’s PHP version is independent from the CLI, letting you adapt to the unique requirements of each site.

1. Configuration Workflow

1. Open ServBay GUI: Launch the ServBay application.
2. Go to Website Management: Click the Websites tab in the sidebar.
3. Add or Edit a Website:
   • Click the + button in the lower left to add a new site.
   • Or select an existing website to edit its configuration.
4. Configure Site Properties:
   • Root Directory: Set the directory where your site files are stored. It’s recommended to use a subdirectory under ServBay’s default path: /Applications/ServBay/www/, e.g., /Applications/ServBay/www/your-website-name/public (for Laravel or Symfony projects).
   • Domain: Choose the local development domain to access your site, e.g., your-website-name.servbay.demo. ServBay automatically sets up local DNS and HTTPS certificates (via ServBay User CA or ServBay Public CA) for custom domains, greatly improving development and testing workflow.
   • PHP Version: Choose the desired PHP version for the site from the dropdown. ServBay lists all installed and enabled PHP versions (e.g., 7.4, 8.1, 8.3, 8.5).
5. Save Configuration: When done, click save. ServBay will apply changes automatically; this may require reloading or restarting related web server and PHP-FPM processes.

2. Technical Insights and Advantages

• Service Isolation: Each website’s PHP version typically runs as a separate PHP-FPM process pool. This ensures complete PHP environment isolation between sites—an error or memory issue in one site won’t affect others.
• Performance Optimization: All ServBay packages, including all PHP versions, are optimized for both ARM64 (Apple Silicon) and X86_64 architectures, ensuring high performance on any Mac hardware.
• Troubleshooting:
  • Check PHP error logs: PHP errors are usually logged at /Applications/ServBay/var/log/php/php_error.log.
  • Monitor PHP-FPM status: Use ServBay’s CLI tool, servbayctl, to check the status of a specific PHP version, e.g., servbayctl status php 8.3.

3. Web Server and Database Integration

ServBay offers maximum flexibility to allow choosing different web servers and databases based on project needs:

• Web Server Support: ServBay 1.7.0 and up let you easily switch the web server used by a site, supporting Apache, Nginx, and Caddy. These servers are tightly integrated with ServBay-managed PHP-FPM pools.
• Database Integration: ServBay supports installing and managing multiple versions of MySQL, MariaDB, PostgreSQL, MongoDB, and Redis. You can connect to any ServBay-managed database instance via site settings or directly from your project code. This makes it easy to meet requirements for specific database types or versions (e.g., some Laravel projects work best with MariaDB 11.x).

3. Cross-environment Collaboration & Best Practices

Understanding the independence and configuration methods for CLI and website PHP versions helps you make the best choice for different development workflows:

Scenario	CLI Configuration (.servbay.config)	Website Configuration (ServBay GUI)	Notes
Maintaining Legacy Systems	Set PHP_VERSION=5.6 in project root	Select PHP 5.6 for the website	Ensure needed PHP version/extensions for old projects are installed.
New Project Development (e.g., Laravel 11)	PHP_VERSION=8.3 (or higher), optionally NODE_VERSION=20	New website, root points to public folder, PHP 8.3+, set dev domain, enable HTTPS	Keep CLI tools (Composer, Artisan, Node build tools) and web PHP version consistent.
Testing Future PHP Versions	Set PHP_VERSION=8.5 in test project root	Add test website, select PHP 8.5	For early compatibility tests with new PHP releases.
Running Composer Commands	Ensure correct PHP_VERSION specified in .servbay.config	N/A (Composer mainly runs in CLI)	Composer uses the PHP version currently active in the terminal environment.

Notes

• CLI vs Web Environment Differences: Even using the same PHP version number, the CLI (command line) and web (PHP-FPM) environments may load different default settings and extensions. For example, the opcache extension is usually enabled by default in PHP-FPM for performance but may be disabled in CLI. If you notice differing behavior, check the respective php.ini files (each PHP version in ServBay has its own) and the loaded extensions list.
• Update ServBay Runtime: Keep your ServBay application and ServBay Runtime up-to-date. The ServBay team continuously updates packages, including new PHP versions and security patches. Updating ServBay also updates Runtime, giving you access to the latest features and improvements.

FAQ

Q: What if the PHP versions for CLI and website environments conflict?

A: Command line PHP (controlled by .servbay.config) and website PHP (managed via the ServBay GUI) are independent of each other. .servbay.config only affects which PHP version your terminal commands use; website settings determine which PHP-FPM version the web server uses for web requests. There’s no direct conflict. It is possible to use different PHP versions for the same project between CLI (for Composer or Artisan) and web (for the website itself), but for consistency—in both development and production—it's recommended to keep them the same.

Conclusion

Through the combination of the .servbay.config file and its intuitive UI, ServBay provides developers powerful and flexible PHP version management. Whether you're maintaining legacy projects that require older PHP versions, or developing new apps with the latest PHP releases, ServBay streamlines your workflow. By using these features wisely, you can ensure your local and production environments are closely aligned, leading to better efficiency and project stability.