PHP Missing ext-intl / ext-gd / ext-zip - Specific Extension Gaps in CI

Code uses a class or function from a specific extension - Collator/NumberFormatter (intl), imagecreatetruecolor (gd), or ZipArchive (zip) - but that extension is not enabled on the runner. Each fails with a distinct undefined-class or undefined-function error.

What this error means

A runtime fatal naming Collator, IntlDateFormatter, an image* function, or ZipArchive as undefined. php -m on the runner does not list intl/gd/zip, even though your local PHP has them.

PHP Fatal error:  Uncaught Error: Class "Collator" not found in
/app/src/Sort.php:14            # ext-intl missing
# or
PHP Fatal error:  Uncaught Error: Call to undefined function imagecreatetruecolor()
# ext-gd missing
# or
PHP Fatal error:  Uncaught Error: Class "ZipArchive" not found   # ext-zip missing

Common causes

The specific extension is not enabled

Minimal PHP images ship core extensions only. intl, gd, and zip are common omissions, so their classes/functions are undefined at runtime.

The extension binary exists but is not loaded

Some images include the .so but do not load it. php -m omits it, so PHP still treats the symbols as undefined.

How to fix it

Enable the exact extensions in CI

List the specific extensions on setup-php so they are loaded.

- uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'
    extensions: intl, gd, zip

Install them in a Docker image

apt-get update && apt-get install -y libicu-dev libpng-dev libzip-dev
docker-php-ext-install intl gd zip
php -m | grep -E 'intl|gd|zip'

Assert the extension before using it

1. Run php -m early and grep for intl/gd/zip.
2. Use extension_loaded('intl') to fail fast with a clear message.
3. Declare ext-intl/ext-gd/ext-zip in composer.json so installs fail loudly.

How to prevent it

• Enable every required extension in CI via setup-php to mirror production.
• Declare ext-* requirements in composer.json.
• Run php -m early in CI to assert the extensions you depend on.

Related guides