docs: update documentation with comprehensive project details

- Enhanced Copilot instructions with detailed build process, PHP configuration, and extensions
- Added complete documentation for dual image types (distroless + base images)
- Updated README with multi-version support details (PHP 8.1-8.4)
- Documented Composer and Xdebug availability in base images
- Clarified CI/CD pipeline architecture and workflow dependencies
- Added comprehensive extension lists and Swoole version specifications

Author: leocavalcante

.github/copilot-instructions.md

@@ -11,36 +11,53 @@ You are an expert in:
 ## Project Context
 
 This repository provides **distroless PHP container images** that combine:
-- **Static PHP builds** from [static-php-cli](https://github.com/crazywhalecc/static-php-cli)
+- **Static PHP builds** from [static-php-cli](https://github.com/crazywhalecc/static-php-cli) v2.6.1
 - **Google's distroless base images** for minimal attack surface
 - **Multi-architecture support** (AMD64/ARM64)
+- **Dual image types**: Distroless runtime images and Debian-based development images
 
 ### Key Goals
 - Provide the smallest possible PHP runtime environment
 - Eliminate unnecessary OS packages and dependencies
 - Maintain security through minimal attack surface
 - Support production-ready PHP applications
+- Provide development-friendly base images with Composer and Xdebug
 
 ## Technical Architecture
 
 ### Build Process
 - Uses a two-stage GitHub Actions pipeline:
-  1. **PHP Build** (`php.yml`): Compiles static PHP binaries for multiple versions (8.1-8.4) and architectures
-  2. **Image Build** (`image.yml`): Creates Docker images using the compiled binaries
-- Final stage uses `gcr.io/distroless/cc-debian12:nonroot` base image
+  1. **PHP Build** (`php.yml`): Compiles static PHP binaries for multiple versions (8.1-8.4) and architectures using static-php-cli v2.6.1
+  2. **Image Build** (`image.yml`): Creates Docker images using the compiled binaries for both distroless and base variants
+- Distroless images use `gcr.io/distroless/cc-debian12:nonroot` base image
+- Base images use `debian:12.11` with Composer 2.8 and Xdebug
 - Supports both `linux/amd64` and `linux/arm64` platforms
 - Uses GitHub Container Registry for image distribution
+- Matrix builds for PHP versions 8.1, 8.2, 8.3, and 8.4
+- Architecture-specific runners (ubuntu-24.04 for AMD64, ubuntu-24.04-arm for ARM64)
 
 ### PHP Configuration
 - **Versions**: PHP 8.1, 8.2, 8.3, 8.4 (all supported)
-- **Extensions**: 60+ included extensions (defined in `php.yml` workflow)
+- **Extensions**: 60+ included extensions including:
+  - Core: bcmath, calendar, ctype, curl, dom, exif, ffi, fileinfo, filter, iconv, intl, mbregex, mbstring, opcache, openssl, pcntl, pdo, phar, posix, session, shmop, simplexml, soap, sockets, sodium, sqlite3, tokenizer, xml, xmlreader, xmlwriter, xsl, zip, zlib
+  - Caching: apcu, memcache, memcached, redis
+  - Database: mysqli, mysqlnd, pdo_mysql, pgsql, mongodb
+  - Performance: swoole (v5.1.7 for PHP 8.1-8.3, v6.0.2 for PHP 8.4), parallel, zstd
+  - Graphics: gd, imagick
+  - Development: ast, xdebug (base images only)
+  - Other: amqp, rdkafka, brotli, ds, gettext, igbinary, inotify, ldap, libxml, msgpack, opentelemetry, password-argon2, readline, xlswriter, yaml
 - **Binary location**: `/bin/php` in final image
 - **User**: Runs as non-root user for security
+- **ZTS**: Thread-safe builds enabled
+- **Special configurations**: 
+  - Swoole hooks for MySQL, PostgreSQL, and SQLite
+  - MongoDB driver limited to 1.x versions for compatibility
 
 ### Project Structure
-- `Dockerfile`: Minimal multi-arch configuration with build arguments
-- `.github/workflows/php.yml`: PHP binary compilation pipeline
-- `.github/workflows/image.yml`: Docker image build and push pipeline
+- `distroless.Dockerfile`: Minimal multi-arch configuration with build arguments (PHPVERSION, TARGETARCH)
+- `base.Dockerfile`: Debian-based image with PHP, Composer 2.8, and Xdebug
+- `.github/workflows/php.yml`: PHP binary compilation pipeline using static-php-cli v2.6.1
+- `.github/workflows/image.yml`: Docker image build and push pipeline for both image types
 - `.github/copilot-instructions.md`: Development guidelines
 - Pre-compiled PHP binaries are built via GitHub Actions using static-php-cli
 
@@ -51,13 +68,15 @@ This repository provides **distroless PHP container images** that combine:
 - Minimize layers and build context
 - Use appropriate ARG variables (PHPVERSION, TARGETARCH) for target architecture
 - Follow security best practices (non-root user, minimal permissions)
+- Two separate Dockerfiles: `distroless.Dockerfile` for runtime and `base.Dockerfile` for development
 
 ### When working with workflows:
 - **PHP Build Workflow**: Triggered manually via workflow_dispatch
 - **Image Build Workflow**: Requires a PHP workflow run ID as input
 - Test on both AMD64 and ARM64 architectures using matrix strategy
 - Extensions are defined in the `EXTENSIONS` environment variable in `php.yml`
-- Current image builds focus on PHP 8.3 but can be expanded via matrix strategy
+- Both workflows support all PHP versions (8.1, 8.2, 8.3, 8.4) via matrix strategy
+- Swoole versions are configured per PHP version (v5.1.7 for 8.1-8.3, v6.0.2 for 8.4)
 
 ### When modifying build processes:
 - Test on both AMD64 and ARM64 architectures using matrix strategy

README.md

@@ -32,39 +32,55 @@ FROM ghcr.io/opencodeco/distroless-php:8.3-base
 - `8.4` - PHP 8.4 (multi-arch: AMD64, ARM64)
 
 **Base Images (Debian + Composer):**
-- `8.3-base` - PHP 8.3 with Composer on Debian (multi-arch: AMD64, ARM64)
+- `8.1-base` - PHP 8.1 with Composer and Xdebug on Debian (multi-arch: AMD64, ARM64)
+- `8.2-base` - PHP 8.2 with Composer and Xdebug on Debian (multi-arch: AMD64, ARM64)
+- `8.3-base` - PHP 8.3 with Composer and Xdebug on Debian (multi-arch: AMD64, ARM64)
+- `8.4-base` - PHP 8.4 with Composer and Xdebug on Debian (multi-arch: AMD64, ARM64)
+
+### Example
+
+**Using the base image for build stage:**
+
+```dockerfile
+FROM ghcr.io/opencodeco/distroless-php:8.3-base AS base
+WORKDIR /workspace
+COPY composer.* ./
+RUN composer install --prefer-dist --no-dev --no-interaction --optimize-autoloader
+COPY . .
+
+FROM ghcr.io/opencodeco/distroless-php:8.3
+COPY --from=base --chown=nonroot:nonroot /workspace /opt
+CMD [ "/opt/bin/hyperf.php", "start" ]
+EXPOSE 9501
+```
+
+*Note: Base images are available for all PHP versions (8.1-base, 8.2-base, 8.3-base, 8.4-base) and include Composer and Xdebug for development workflows.*
 
 ## Building
 
 Images are automatically built and published via GitHub Actions using pre-compiled PHP binaries from [static-php-cli](https://github.com/crazywhalecc/static-php-cli). The build process uses multi-architecture Docker builds to support both AMD64 and ARM64 platforms.
 
 ### CI/CD Pipeline
 
-The project uses a multi-stage GitHub Actions pipeline:
+The project uses a two-stage GitHub Actions pipeline:
 
 1. **PHP Build** (`php.yml`): Builds static PHP binaries for both architectures
    - **Triggers**: Manual workflow dispatch
    - **PHP Versions**: 8.1, 8.2, 8.3, 8.4
    - **Platforms**: `linux/amd64` and `linux/arm64`
    - **Extensions**: 60+ extensions including amqp, apcu, ast, bcmath, brotli, calendar, ctype, curl, dom, ds, exif, ffi, fileinfo, filter, gd, gettext, iconv, igbinary, imagick, inotify, intl, ldap, libxml, mbregex, mbstring, memcache, memcached, mongodb, msgpack, mysqli, mysqlnd, opcache, openssl, opentelemetry, parallel, password-argon2, pcntl, pdo, pdo_mysql, pgsql, phar, posix, rdkafka, readline, redis, session, shmop, simplexml, soap, sockets, sodium, sqlite3, swoole, swoole-hook-mysql, swoole-hook-pgsql, swoole-hook-sqlite, tokenizer, xlswriter, xml, xmlreader, xmlwriter, xsl, yaml, zip, zlib, zstd
+   - **Additional**: Includes Xdebug extension for base images
    - **Artifacts**: Uploads compiled PHP binaries as GitHub artifacts
 
 2. **Image Build** (`image.yml`): Creates Docker images using the PHP binaries
    - **Triggers**: Manual workflow dispatch (requires PHP workflow run ID)
    - **Registry**: GitHub Container Registry (`ghcr.io`)
    - **Platforms**: Multi-architecture builds for `linux/amd64` and `linux/arm64`
-   - **PHP Version**: Currently builds PHP 8.3 (configurable via matrix)
+   - **PHP Versions**: Builds all supported PHP versions (8.1, 8.2, 8.3, 8.4)
+   - **Image Types**: Both distroless runtime images and Debian-based images with Composer
    - **Caching**: Uses GitHub Actions cache for faster builds
    - **Authentication**: Uses `GITHUB_TOKEN` for registry access
 
-3. **Base Image Build** (`base.yml`): Creates Debian-based images with PHP and Composer
-   - **Triggers**: Manual workflow dispatch
-   - **Registry**: GitHub Container Registry (`ghcr.io`)
-   - **Platforms**: Multi-architecture builds for `linux/amd64` and `linux/arm64`
-   - **PHP Version**: Currently builds PHP 8.3 base image
-   - **Features**: Includes statically built PHP binary and Composer on Debian base
-   - **Use Case**: Ideal for development and build stages where you need package managers and build tools
-
 ### Architecture Support
 
 - **AMD64** (x86_64): Built using pre-compiled PHP binaries
@@ -75,30 +91,34 @@ The project uses a multi-stage GitHub Actions pipeline:
 The complete build process consists of two stages:
 
 1. **PHP Binary Compilation** (`php.yml`):
-   - Checks out the [static-php-cli](https://github.com/crazywhalecc/static-php-cli) repository
-   - Sets up PHP 8.4 build environment with required tools and extensions
+   - Checks out the [static-php-cli](https://github.com/crazywhalecc/static-php-cli) repository (version 2.6.1)
+   - Sets up PHP build environment with required tools and extensions
    - Downloads dependencies and compiles PHP with all extensions for multiple PHP versions (8.1, 8.2, 8.3, 8.4)
    - Creates static PHP binaries for both AMD64 and ARM64 architectures
-   - Uses matrix builds with architecture-specific runners (ubuntu-latest for AMD64, ubuntu-latest-arm for ARM64)
+   - Uses matrix builds with architecture-specific runners (ubuntu-24.04 for AMD64, ubuntu-24.04-arm for ARM64)
+   - Includes Xdebug extension as a shared module for base images
+   - Updates Swoole to specific versions per PHP version (v5.1.7 for PHP 8.1-8.3, v6.0.2 for PHP 8.4)
    - Uploads binaries as GitHub artifacts with version and architecture naming
 
 2. **Docker Image Creation** (`image.yml`):
    - Downloads the PHP binary artifacts from the previous workflow (requires run ID input)
-   - Uses multi-stage Docker build with distroless base image
+   - Uses multi-stage Docker build with both distroless and Debian base images
    - Copies the appropriate PHP binary based on target architecture using build arguments
-   - Creates minimal container image with only PHP binary and distroless base
+   - Creates minimal distroless container images with only PHP binary and distroless base
+   - Creates Debian-based images with PHP, Composer, and Xdebug for development use
    - Supports multi-architecture builds (linux/amd64, linux/arm64)
-   - Currently builds PHP 8.3 images (configurable via matrix strategy)
+   - Builds all PHP versions (8.1, 8.2, 8.3, 8.4) for both image types
    - Pushes to GitHub Container Registry with appropriate tags
 
 ## How it Works
 
 This project combines static PHP binaries with Google's Distroless base images to create minimal, secure PHP runtime containers:
 
-1. **Static PHP Binaries**: Pre-compiled PHP binaries from [static-php-cli](https://github.com/crazywhalecc/static-php-cli) are built with 60+ extensions for multiple PHP versions (8.1, 8.2, 8.3, 8.4)
+1. **Static PHP Binaries**: Pre-compiled PHP binaries from [static-php-cli](https://github.com/crazywhalecc/static-php-cli) v2.6.1 are built with 60+ extensions for multiple PHP versions (8.1, 8.2, 8.3, 8.4)
 2. **Multi-arch Build**: Docker build process uses architecture-specific binaries (AMD64 or ARM64) via build arguments (PHPVERSION and TARGETARCH)
 3. **Distroless Base**: Uses `gcr.io/distroless/cc-debian12:nonroot` for minimal attack surface and runs as non-root user
-4. **No OS**: Final images contain only the PHP binary and distroless base - no package managers, shells, or unnecessary tools
+4. **Base Images**: Debian 12.11-based images with Composer 2.8 and Xdebug for development workflows
+5. **No OS**: Final distroless images contain only the PHP binary and distroless base - no package managers, shells, or unnecessary tools
 
 ### Included PHP Extensions
 
@@ -109,54 +129,17 @@ The PHP binaries include 60+ extensions:
 - **Messaging**: amqp, rdkafka
 - **Performance**: swoole, swoole-hook-mysql, swoole-hook-pgsql, swoole-hook-sqlite, parallel, zstd
 - **Graphics**: gd, imagick
-- **Development**: ast, ffi
+- **Development**: ast, ffi, xdebug (base images only)
 - **Serialization**: igbinary, msgpack, yaml
 - **Monitoring**: opentelemetry
 - **Utilities**: brotli, ds, gettext, inotify, ldap, libxml, password-argon2, readline, xlswriter
 
 ### Project Structure
 
 ```
-├── Dockerfile                                    # Multi-arch Dockerfile with build arguments (PHPVERSION, TARGETARCH)
-├── Dockerfile.base                               # Debian-based image with PHP and Composer
+├── distroless.Dockerfile                        # Multi-arch distroless Dockerfile with build arguments (PHPVERSION, TARGETARCH)
+├── base.Dockerfile                               # Debian-based image with PHP, Composer, and Xdebug
 ├── .github/workflows/php.yml                    # PHP binary build pipeline (supports 8.1, 8.2, 8.3, 8.4)
-├── .github/workflows/image.yml                  # Docker image build pipeline
-├── .github/workflows/base.yml                   # Base image build pipeline
+├── .github/workflows/image.yml                  # Docker image build pipeline (both distroless and base)
 └── .github/copilot-instructions.md              # Copilot development guidelines
 ```
-
-### Example
-
-**Using the base image for build stage:**
-
-```dockerfile
-FROM ghcr.io/opencodeco/distroless-php:8.3-base AS build
-WORKDIR /workspace
-COPY composer.* ./
-RUN composer install --prefer-dist --no-dev --no-interaction --optimize-autoloader
-COPY . .
-
-FROM ghcr.io/opencodeco/distroless-php:8.3
-COPY --from=build --chown=nonroot:nonroot /workspace /app
-CMD [ "/app/bin/hyperf.php", "start" ]
-EXPOSE 9501
-```
-
-**Traditional approach (still supported):**
-
-```dockerfile
-FROM composer:2.2 AS composer
-FROM php:8.3 AS build
-RUN apt-get update && apt-get install -y libzip-dev && docker-php-ext-install zip
-WORKDIR /workspace
-COPY --from=composer /usr/bin/composer /usr/bin/composer
-ENV COMPOSER_ALLOW_SUPERUSER=1
-COPY composer.* ./
-RUN composer install --prefer-dist --no-dev --no-interaction --optimize-autoloader
-COPY . .
-
-FROM ghcr.io/opencodeco/distroless-php:8.3
-COPY --from=build --chown=nonroot:nonroot /workspace /app
-CMD [ "/app/bin/hyperf.php", "start" ]
-EXPOSE 9501
-```