The information in this post is about a project in motion. The final delivery may differ from what is discuss here, especially as we consider the feedback you have.
Update: the changes discussed in this article are delayed until a future version of cPanel & WHM. They are not in version 11.34.
The Typical cPanel PHP Setup
Unlike perl, a typical cPanel & WHM server does not have a single installation of PHP. Rather, typically you will find PHP interpreters in the following locations:
The /usr/local/cpanel location is deployed as part of cPanel & WHM. It is a static implementation generated as part of our build process. This location is often referred to as ‘internal PHP.’ The binaries, and all dependencies, are downloaded and installed using the cpanelsync infrastructure.
EasyApache handles the PHP installations found in /usr and /usr/local. These are most frequently used by applications served by Apache, however it is possible to use these implementations with applications integrated with the cpanel interface (note: not however with webmail or WHM). These are compiled from source on demand.
The /var/cpanel/3rdparty instance is also installed as part of cPanel & WHM, however it is built by scripts/makecpphp. Because makecpphp uses EasyApache to build, the /var/cpanel/3rdparty interpreter is customizable. This installation also needs considered when discussing the internal PHP.
The internal PHP changes in the following ways:
- It is delivered via pre-built RPMs
- The version is upgraded to 5.3
- We added support for using Zend Guard Loader with the internal PHP (you could do this before, but had to perform the changes manually)
- PEAR dependencies for Horde and the other internal PHP apps are provided by RPM
- scripts/makecpphp is removed. The preferred way of customizing the internal PHP is by rebuilding our source RPM (note: we’ll be providing documentation on doing this).
- The loaders are no longer managed by scripts/phpextensionmgr. They are still in Tweak Settings, but are now installed via RPM
- The Tweak Settings option allows for specifying more than a single loader to use with the internal PHP
Changes to extensions
Prior versions of cPanel & WHM built the internal PHP (the one in /usr/local/cpanel) using the following configure options
--enable-static --with-mcrypt --with-ldap --with-iconv --enable-mbstring --with-mbstring=all --enable-mbstr-enc-trans --with-gd --with-dom --enable-mbregex --with-zlib --with-jpeg --with-png --with-imap --enable-ftp --with-gettext --with-xml --enable-track-vars --enable-sockets --with-mysql=/usr --with-pgsql --enable-cgi
Some of those configure flags didn’t actually do anything, they were hold-overs from PHP 4. We removed ones that were no longer valid (such as enable-mbstr-enc-trans) and added the following:
--with-imap-ssl --enable-sockets --with-pdo-mysql --with-pgsql --with-pdo-pgsql --with-openssl --with-kerberos --with-curl --with-curlwrappers --with-tidy --with-pcre-regex --with-bz2 --enable-zip
If you would like other extensions enabled or shipped by default, please let us know.
For the MySQL extension(s) we are providing a “static” version of the MySQL client library, version 5.0, which installs to /usr/local/cpanel/3rdparty. This client works with all versions of MySQL supported with cPanel & WHM. Changing your MySQL version will not require rebuilding the PHP mysql extension.
We also provide a client library for PostgreSQL, and some other dependencies, as RPMs.
What this means for Upgrades
During upgrade the older internal implementation is removed. Since it’s possible people have installed custom extensions or modules into /usr/local/cpanel/3rdparty we don’t remove directories that still contain items after we removed what ships with cPanel & WHM.
It is recommended you examine locations such as /usr/local/cpanel/3rdparty/lib/php after the upgrade. If that location exists it indicates the upgrade found items it was not expecting. Please review any items found there.
The PHP RPMs install to the prefix /usr/local/cpanel/3rdparty/php/53. To ensure existing applications continue to function after the upgrade we symlink the PHP binary, and several other files to the places in /usr/local/cpanel/3rdparty they existed in 11.32 and older. We expect this to only be the case for one version of the product. Successive versions of cPanel & WHM will not guarantee that backwards compatibility.
Once a system is using the newer version of cPanel & WHM the install in /var/cpanel/3rdparty will no longer be used by the product. If you are not using it in your own applications it is strongly suggested to remove the /var/cpanel/3rdparty directory structure from your server after the upgrade.
What this means for fresh installs
Fresh installs will have the following PHP installations:
- The /usr and /usr/local installations done by EasyApache
The /var/cpanel/3rdparty installation will not be done, nor will it be used.
Environment and Use
In cPanel & WHM 11.32 and older when using a PHP application within the context of cPanel & WHM, for example Horde Webmail, the PHP interpreter to use was determined by a variety of factors, including the presence of the /var/cpanel/usecpphp flag file. For the most part these applications would use one of:
Beginning with this version only the /usr/local/cpanel/3rdparty/php/53/bin/php location will be used to fulfill these requests. This means the /var/cpanel/3rdparty installation of PHP is no longer used. It is strongly recommended, once you are sure nothing in your own applications relies upon it, to remove /var/cpanel/3rdparty after upgrading.
This change also means the /var/cpanel/usecpphp flag file is no longer used. In addition the Cpanel::cpPHP perl module used to determine which php binary would be used by cPanel & WHM is deprecated.
The cPanel::cpPHP module will be shipped with cPanel & WHM, however calling its functions will result in a message being logged to the cPanel error log (/usr/local/cpanel/logs/error_log). The intent of the log message is so admins can identify applications using the deprecated module, so the application can be updated.
The default include path, both in the PHP binary and in php.ini is /usr/local/cpanel/3rdparty/php/53/lib/php:/opt/cpanel/php/53/lib/php.
The install path for the pear and pecl utilities is /opt/cpanel/php/53/lib/php.
What Comes as RPMs?
Internal test builds are currently using:
- PHP 5.3.10
Before shipping we will update the PHP version to the latest 5.3 available.
We are also providing the following PEAR and PECL packages as RPMs:
The versions in the above lists are not final, expect some of them to change before delivery. If there is something you want added to the list, please let us know.
How do I install PEAR or PECL modules for the Internal PHP?
PEAR modules can be installed using /usr/local/cpanel/3rdparty/php/53/bin/pear. The modules install to /opt/cpanel/php/53/lib.
To install PECL modules you need to have GCC installed (which it normally is on a cPanel & WHM server). You should be able to install pecl modules using /usr/local/cpanel/3rdparty/php/53/bin/pecl. As with PEAR these modules are installed to /opt/cpanel/php/53/lib.
What if I need an extension cPanel does not provide in the cPanel-PHP RPM?
If you have a need to customize the cPanel-PHP RPM, we’d really like to hear from you. Knowing the needs of our customers and users keeps us better informed and guides what we release. It’s quite possible the extensions and changes you want for the PHP RPM are useful to many. Adjusting the RPM we deliver can spread the good, so to speak.
Customizing the cPanel-PHP RPM deployed to your servers is an option for you as well. I’ll cover this in more detail in a later article. In short going this route will result in replacing the RPM we provide with your own. For changes you need now, rather than later, this will often be your best option.
This is the third article in our series on migrating to pre-built RPMs. Other articles, written and pending are:
- Switching from compile-on-demand to binary packages
- Providing the perl stack as RPMs
- rpm.versions system
- Changes to how cPanel & WHM are updated to make it more robust
Discuss this article on our forum.