> For the complete documentation index, see [llms.txt](https://senselab.gitbook.io/senselab-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://senselab.gitbook.io/senselab-docs/vendor/pact-foundation/pact-php/docs/alpine-ffi-troubleshooting.md).

# Pact PHP — Alpine (musl) FFI Troubleshooting

This page explains how to fix a common issue when running **Pact PHP v10** on **Alpine Linux (musl)**.

***

## The problem

When running Pact on Alpine, you may see:

```
error while loading shared libraries: libgcc_s.so.1: cannot open shared object file
```

This happens because Alpine images are minimal:

* Required runtime libraries (like `libgcc`) aren’t installed.
* The PHP **FFI** extension (used by Pact v10) is missing or disabled.

***

## The fixes

### 1) Official PHP Alpine images (e.g., `php:8.3-cli-alpine`)

Add this to your Dockerfile:

```dockerfile
FROM php:8.3-cli-alpine

RUN set -eux; \
    apk add --no-cache $PHPIZE_DEPS libgcc; \
    docker-php-ext-install ffi; \
    echo "ffi.enable=true" > /usr/local/etc/php/conf.d/ffi-enable.ini
```

### 2) Alpine’s distro PHP (not Docker Hub’s `php:` image)

```bash
apk add --no-cache php83-ffi
echo "ffi.enable=true" > /etc/php83/conf.d/ffi-enable.ini
```

### 3) Debian/Ubuntu base images (e.g., `php:8.3-cli`)

```dockerfile
FROM php:8.3-cli

RUN set -eux; \
    apt-get update; \
    apt-get install -y --no-install-recommends libgcc-12-dev; \
    docker-php-ext-install ffi; \
    rm -rf /var/lib/apt/lists/*; \
    echo "ffi.enable=true" > /usr/local/etc/php/conf.d/ffi-enable.ini
```

***

## Notes

* Pact PHP v10 requires **PHP 8.1+** and the **FFI** extension **enabled** (`ffi.enable=true`).
* If you use multi-stage Docker builds, make sure the **final** image still has `libgcc` and FFI enabled.
* On Apple Silicon (ARM64), use matching `arm64` images; Pact will load the correct native library automatically.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://senselab.gitbook.io/senselab-docs/vendor/pact-foundation/pact-php/docs/alpine-ffi-troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.