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 thePATH
). This ensuresphp
,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
2
3
4
5
- 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
2
3
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 asmcrypt
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
- Open ServBay GUI: Launch the ServBay application.
- Go to Website Management: Click the Websites tab in the sidebar.
- 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.
- 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).
- Root Directory: Set the directory where your site files are stored. It’s recommended to use a subdirectory under ServBay’s default path:
- 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
.
- Check PHP error logs: PHP errors are usually logged at
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 respectivephp.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.