How do I install PECL modules in my Elastic Beanstalk environments?

Short description

To install PECL 7 modules, create a configuration file that includes commands to perform the following actions:

• Set up .ebextensions directory.
• Install dependencies.
• Install the PECL module.
• Create or modify configuration files.

Then, store the configuration file in the .ebextensions folder.

Note: For examples and requirements, see Advanced environment customization with configuration files (.ebextensions) and Extending Elastic Beanstalk Linux platforms.

Resolution

Set up the .ebextensions directory in the root of the source bundle for your application.

Elastic Beanstalk stores your configuration files in the .ebextensions folder. The Elastic Beanstalk environment uses only files that end with the .config extension.

Example:

|-- .ebextensions 
|        |-- redis/memcached.config 
|        |-- other .config files 
|-- other application files 

Create a configuration file in the .ebextensions directory

PHP 8.1 on Amazon Linux 2

For Redis modules, use the following configuration:

commands: 
  01_install_redis: 
    command: /usr/bin/yes 'no' | /usr/bin/pecl install redis 
    test: '! /usr/bin/pecl info redis' 
  02_remove_extension: 
    command: /bin/sed -i -e '/extension="redis.so"/d' /etc/php.ini 
  03_create_conf: 
    command: /bin/echo 'extension="redis.so"' > /etc/php.d/41-redis.ini

Note: In the preceding configuration file, 01_install_redis installs the Redis module and tests for installation success. 02_remove_extension removes the Redis extension from the /etc/php.ini file. 03_create_conf creates a configuration file with the name 41-redis.ini at /etc/php.d/.

For Memcached modules, use the following configuration:

packages: 
  yum: 
    libmemcached-devel: [] 
commands: 
  01_install_memcached: 
    command: /usr/bin/yes 'no'| /usr/bin/pecl install memcached 
    test: '! /usr/bin/pecl info memcached' 
  02_remove_extension: 
    command: /bin/sed -i -e '/extension="memcached.so"/d' /etc/php.ini 
  03_create_conf: 
    command: /bin/echo 'extension="memcached.so"' > /etc/php.d/41-memcached.ini 

Note: In the preceding configuration file, 01_install_memcached installs the Memcached module and tests for installation success. 02_remove_extension removes the Redis extension from the /etc/php.ini file. 03_create_conf creates a configuration file that's called 41-memcached.ini at /etc/php.d/.

It's a best practice to test new .ebextensions configurations in a non-production environment before you deploy to production.

For PHP 8.4 on Amazon Linux 2023

To install the available PECL modules, use the following YUM packages:

• php8.4-pecl-redis6
• php8.4-pecl-igbinary
• php8.4-pecl-msgpack
• php8.4-pecl-memcached
• php8.4-pecl-apcu

Important: By default, the php8.4-pecl-* YUM package installs modules to /usr/lib64/php8.4/modules/ instead of the default PHP extension directory /usr/lib64/php/modules/. This install causes the PHP to fail when you load the extensions.

To resolve the PHP failure, create symbolic links from the default PHP extension directory to the actual module location after you install the packages.

Configuration for Redis modules (with igbinary and msgpack):

packages: 
  yum: 
    php8.4-pecl-igbinary: [] 
    php8.4-pecl-msgpack: [] 
    php8.4-pecl-redis6: [] 
 
commands: 
  01_symlink_igbinary: 
    command: ln -sf /usr/lib64/php8.4/modules/igbinary.so /usr/lib64/php/modules/igbinary.so 
  02_symlink_msgpack: 
    command: ln -sf /usr/lib64/php8.4/modules/msgpack.so /usr/lib64/php/modules/msgpack.so 
  03_symlink_redis: 
    command: ln -sf /usr/lib64/php8.4/modules/redis.so /usr/lib64/php/modules/redis.so 

Note: In the preceding configuration file, the packages section uses YUM to install the Redis, igbinary, and msgpack modules. The YUM packages automatically create the .iniconfiguration files in /etc/php.d/. The 01_symlink_igbinary creates a symbolic link for the igbinary module from /usr/lib64/php8.4/modules/ to /usr/lib64/php/modules/. The 02_symlink_msgpack creates a symbolic link for the msgpack module. The 03_symlink_redis creates a symbolic link for the Redis module.

Configuration for Memcached modules:

packages: 
  yum: 
    php8.4-pecl-memcached: [] 
 
commands: 
  01_symlink_memcached: 
    command: ln -sf /usr/lib64/php8.4/modules/memcached.so /usr/lib64/php/modules/memcached.so 

Note: In the preceding configuration file, the packages section uses YUM to install the Memcached module. The 01_symlink_memcached creates a symbolic link for the memcached module.

Verify that you loaded the modules correctly

Connect to your instance and run the following commands.

To check for PHP startup errors:

php -v

Expected output:

packages: 
  yum: 
    php8.4-pecl-memcached: [] 
 
commands: 
  01_symlink_memcached: 
    command: ln -sf /usr/lib64/php8.4/modules/memcached.so /usr/lib64/php/modules/memcached.so 

To list loaded modules:

php -m | grep -iE "redis|igbinary|msgpack|memcached|apcu"

Expected output (for Redis with igbinary and msgpack):

igbinary 
msgpack 
redis

To check the Redis version:

php -r "echo 'Redis version: ' . phpversion('redis') . PHP_EOL;"

Troubleshoot your modules

If you didn't correctly create symbolic links, then PHP can't load the modules, and you get an error message similar to the following:

"PHP Warning: Unable to load dynamic library 'redis.so' (tried: /usr/lib64/php/modules/redis.so - No such file or directory)"

To resolve this error, run the following command to check that the modules exist in /usr/lib64/php8.4/modules/:

ls -la /usr/lib64/php8.4/modules/

Your modules exist if you have the following output:

If the directory doesn't exist or modules are missing, then verify the packages section in your .ebextensions configuration file and redeploy your application.

To check that the symbolic links exist in /usr/lib64/php/modules/, run the following command:

ls -la /usr/lib64/php/modules/ | grep -iE "redis|igbinary|msgpack"

To confirm that you have the correct symlink commands in your .ebextentsions configuration file, check that you have the following output:

lrwxrwxrwx. 1 root root 37 igbinary.so -> /usr/lib64/php8.4/modules/igbinary.so 
lrwxrwxrwx. 1 root root 36 msgpack.so -> /usr/lib64/php8.4/modules/msgpack.so 
lrwxrwxrwx. 1 root root 34 redis.so -> /usr/lib64/php8.4/modules/redis.so 

If you don't have symbolic links, then confirm that your .ebextensions configuration file includes the commands section with the symbolic link commands.

Always test a new .ebextensions configuration in a non-production environment before you deploy to production.