This document contains information about adding non-Drupal PHP extensions or libraries to your application.
Cloud Platform includes a standard set of PHP extensions that are available on the infrastructure. Your application might, however, require additional PHP extensions to support its own desired features. Cloud Platform Enterprise and Site Factory subscribers can compile and deploy PHP extensions or libraries, and Acquia can enable them on your Cloud Platform environments.
The Apache infrastructure for your Cloud Platform environments serve everything
in the /docroot directory and ignore files that are not in /docroot.
Your repository contains a /library subdirectory that you can use for PHP
code libraries. This is located in the / directory of Git repositories.
The /library subdirectory is part of your default PHP include_path and
is outside of /docroot, so it will not be served by Apache.
If any PHP library does not work as expected, examine your environment’s
php-error.log.
Note
Acquia does not guarantee that any PHP extensions used in this manner function as expected, and Acquia does not assist with troubleshooting extensions that do not function as expected. For information about limitations, see Unsupported software.
Compiling PHP libraries
Important
This feature is incompatible with applications running on Cloud Next technologies. If your application requires custom extensions, contact your Acquia account team.
You must compile the PHP extensions (.so files) and libraries that you
require and commit them to your code repository. Here is an article that may
help you:
The compiled shared extension (the .so file) must itself contain any
libraries on which it depends. This is called static linking. The goal is that
when you run ldd on the .so file in the Cloud Platform environment, all
of the dependencies are met without manipulating the LD_LIBRARY_PATH.
Acquia does not provide support for this process. Here are two articles that
may help guide you in understanding the (frequently complex) issues involved:
You must compile them for the same operating system version that your Cloud Platform environments run. To determine the operating system version, connect to your environments with SSH and run this command:
lsb_release -c
Checking for dependencies
The compiled PHP extension must contain any dependent libraries not already
found on your infrastructure. To test this, navigate to the PHP extension’s
folder in your /library directory on your environment and run
ldd extension.so, being sure to replace extension.so with the name of
the actual .so file you have compiled. When you run ldd on the .so
file in the Acquia environment, all of the dependencies must be met without
manipulating the LD_LIBRARY_PATH.
The following is an example of a compiled extension that does not have the required libraries on the environment or statically linked to the compiled extension:
sitename@server-1234:/var/www/html/sitename.dev/library$ ldd ssh2.so
linux-vdso.so.1 => (0x00007fff071ff000)
libssh2.so.1 => not found
libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f2ea56b5000)
/lib64/ld-linux-x86-64.so.2 (0x00007f2ea5c92000)
In this example, one of the requirements was not found.
Deploying PHP extensions
Important
This feature is incompatible to applications running on Cloud Next technologies. If your application requires custom extensions, contact your Acquia account team.
You must deploy the version of code that contains this change to whichever
environments you need the code to be enabled on. For example, if you commit
your code to the master branch, the extension can be enabled only on
environments running master or a branch or tag pulled from master after
the change was submitted. Otherwise, the files will be missing.
For example, to use a custom PHP library called my.php with your
application, commit it to the /library directory in your Git repository,
and then use the following statement in your Drupal code, in the file where you
make a call to the custom library:
include_once "<path-to-library>/my.php";
Enabling PHP extensions
Once you have compiled and deployed your PHP extension, you need to get it
enabled on your Cloud Platform environments. To do so, create a Support ticket. The ticket must specify the location of the
compiled extensions, as
well as a brief summary of their intended purpose. Once Acquia has
reviewed and approved the request, we will modify the php.ini files in your
environments to point to each compiled extension in your code repository. This
typically takes one or two business days.
Enabling PHP IMAP or xdebug
The PHP IMAP and xdebug extensions are present. However, they are
disabled on Cloud Classic by default. To use either PHP IMAP or
xdebug, you do not need to compile and deploy it. You need to
create a Support ticket and request for
enabling it.
Unsupported software
Cloud Platform does not support the following software:
Moodle (not compatible with high availability)
piwik (Acquia has repeatedly seen this cause performance issues)
Any non-Drupal CMS
CA Single Sign-on (formerly CA SiteMInder)
You cannot install the following software on Cloud Platform:
Custom daemons or services, such as Jabber or Microsoft Exchange
Custom package installations that require
apt-get; you can still install custom executables using your code repository
Troubleshooting
To test if a PHP extension compiles correctly, run the following command:
php -n -d extension=/var/www/html/$AH_SITE_NAME/library/extension.so -r "phpinfo();"
In the following example, the PHP extension compiles with the debug flag:
example@staging-12345:/var/www/html/example.dev/docroot$ php -n -d extension=/var/www/html/$AH_SITE_NAME/library/extension.so -r "phpinfo();"
Warning: PHP Startup: extension: Unable to initialize module
Module compiled with build ID=API20210902,NTS,debug
PHP compiled with build ID=API20210902,NTS
These options need to match
in Unknown on line 0
phpinfo()
PHP Version => 8.1.22
[…]