Navigating Docker and PHP with PECL: Trials, errors, and the eventual solution

Working with Docker can be a rewarding but occasionally frustrating experience, especially when dealing with development libraries and extensions that rely on external repositories. In this article, I’ll walk you through the trials and errors I encountered while setting up PECL and APCu in a PHP 8.2 Docker container. The process was full of lessons, dead ends, and ultimately, a working solution.

The goal: Installing APCu via PECL in Docker

The main goal was to install APCu (Alternative PHP Cache User), a PHP extension designed for in-memory caching, using PECL in a Docker container running PHP 8.2. Simple enough, right? Little did I know, it would take a few trials and errors to get it working in this environment.

The base Docker image I was using was:

FROM [AWS-ECR-ID].dkr.ecr.ap-southeast-2.amazonaws.com/php-apache:php8.2.12-apache2.4.56-bullseye

I started with a standard bullseye base image and assumed PECL and APCu would be easy to install. However, reality quickly set in as I encountered roadblocks with missing packages and broken repository links.

Step 1: Initial approach—using PECL directly

My first approach was to install PECL directly, assuming it would be available out-of-the-box or easily installable. I attempted to install PECL along with APCu using a simple Dockerfile:

RUN pecl install apcu && docker-php-ext-enable apcu

The first roadblock: missing php-pear and php-dev

This command failed with a message that php-pear and php-dev were not available in the bullseye repository. These packages are essential for compiling PHP extensions like APCu, so I needed to find a way to get them installed. After some research, I decided to add the Ondřej Surý repository for updated PHP packages.

Step 2: Adding Ondřej Surý’s repository

Adding the Sury repository seemed like a logical next step to ensure PHP 8.2-related packages would be available. Here’s what I added to my Dockerfile:

RUN apt-get update && apt-get install -y lsb-release apt-transport-https ca-certificates curl && \
   curl -sSL https://packages.sury.org/php/README.txt | bash && \
   apt-get update

This repository gave me access to up-to-date PHP packages, including php-pear and php-dev. Or so I thought.

The second roadblock: Still no php-pear or php-dev

Despite adding the repository, I encountered the same issue—php-pear and php-dev still weren’t available. I quickly realised that they may have been deprecated or simply unavailable for my base image configuration. I was back to square one.

Step 3: Exploring go-pear.phar

I knew PEAR could still be installed manually, so I decided to download go-pear.phar, a script used to install PEAR. Here’s the next iteration of the Dockerfile:

RUN apt-get update && apt-get install -y --no-install-recommends wget && \
   wget https://pear.php.net/go-pear.phar && \
   php go-pear.phar && \
   pecl channel-update pecl.php.net

The third roadblock: SSL certificate errors

This attempt failed due to SSL certificate errors when trying to download go-pear.phar from https://pear.php.net. The certificate wasn’t trusted, and the connection was blocked. While I could have manually fixed the certificate issue, I decided to bypass SSL certificate checks for simplicity.

Step 4: Bypassing SSL certificate checks

At this point, I modified the command to bypass SSL certificate validation using the --no-check-certificate flag with wget. The Dockerfile now looked like this:

RUN apt-get update && apt-get install -y --no-install-recommends wget && \
   wget --no-check-certificate https://pear.php.net/go-pear.phar && \
   php go-pear.phar && \
   pecl channel-update pecl.php.net

This successfully bypassed the SSL certificate issue. However, after some further research, I found a GitHub mirror for the go-pear.phar file that seemed more reliable and didn’t involve bypassing SSL checks.

Step 5: The final working solution—using a GitHub mirror

I replaced the pear.php.net download link with a GitHub mirror, which worked perfectly without SSL errors. Here’s the final working version of the Dockerfile:

RUN apt-get update && apt-get install -y --no-install-recommends wget && \
   wget --no-check-certificate https://raw.githubusercontent.com/pear/pearweb_phars/master/go-pear.phar && \
   php go-pear.phar && \
   pecl channel-update pecl.php.net

This method successfully installed PEAR and allowed me to update PECL channels and install APCu.

The wrap

The journey to installing APCu via PECL in Docker taught me several important lessons:

1. Packages are not always available in base images: Even though you expect packages like php-pear and php-dev to be available, that’s not always the case with custom base images like the one I was using from AWS;
2. SSL certificate errors are common: When dealing with external repositories or download sources, SSL certificate issues can arise. It’s important to have a fallback solution, like bypassing certificate checks or finding alternative download sources; and
3. Stay flexible with repository sources: The Sury repository provided an updated set of PHP packages, but it wasn’t the solution for everything. Using a GitHub mirror for go-pear.phar was ultimately the most reliable way forward.
   Conclusion

Docker is a fantastic tool, but it can present unique challenges, especially when dealing with PHP extensions and external repositories. By staying persistent and trying alternative approaches, I was able to find a working solution.

Hopefully, this breakdown of my experience helps others avoid some of the pitfalls I encountered. Docker, PECL, and APCu can work seamlessly together — if you know how to navigate the roadblocks.