# Composer Extension Requirements

**Last Updated:** 2026-01-15

## Overview

Composer can validate PHP extension requirements using `ext-*` package names. This ensures that required extensions are available before code is deployed, preventing production failures.

## How It Works

Composer treats PHP extensions as packages with the `ext-*` prefix:

```json
{
  "require": {
    "ext-mbstring": "*",
    "ext-iconv": "*",
    "ext-json": "*",
    "ext-curl": "*"
  }
}
```

When you run `composer install` or `composer update`, Composer checks if these extensions are loaded. If an extension is missing, Composer will fail with a clear error message.

## Current Configuration

**Required Extensions** (in `composer.json`):

```json
{
  "require": {
    "ext-mbstring": "*",
    "ext-iconv": "*",
    "ext-json": "*",
    "ext-curl": "*"
  }
}
```

**Optional Extensions** (in `composer.json`):

```json
{
  "suggest": {
    "ext-gd": "For image processing",
    "ext-zip": "For Excel generation",
    "ext-xml": "For XML processing"
  }
}
```

## Extension Descriptions

### Required Extensions

#### ext-mbstring

- **Purpose**: Multibyte string handling for UTF-8 text processing
- **Used for**: Blog FAQ schema generation, text processing, UTF-8 encoding
- **Fallback**: `iconv` or standard PHP string functions
- **Installation**: `sudo apt-get install php-mbstring` (Ubuntu/Debian)

#### ext-iconv

- **Purpose**: Character encoding conversion
- **Used for**: Fallback for mbstring encoding operations
- **Fallback**: `mb_convert_encoding` if available
- **Installation**: Usually included by default

#### ext-json

- **Purpose**: JSON encoding/decoding
- **Used for**: API responses, data storage, configuration files
- **Fallback**: None (critical - will fail if missing)
- **Installation**: Included by default in PHP 8.0+

#### ext-curl

- **Purpose**: HTTP client for API requests
- **Used for**: External API integrations, webhooks
- **Fallback**: `file_get_contents()` if `allow_url_fopen` enabled
- **Installation**: `sudo apt-get install php-curl` (Ubuntu/Debian)

### Optional Extensions (suggested)

#### ext-gd

- **Purpose**: Image processing and manipulation
- **Used for**: Image optimization, resizing, format conversion
- **Fallback**: Skip image processing, use original images
- **Installation**: `sudo apt-get install php-gd` (Ubuntu/Debian)

#### ext-zip

- **Purpose**: ZIP archive handling
- **Used for**: Excel file generation, archive creation
- **Fallback**: Skip ZIP operations, use alternative methods
- **Installation**: `sudo apt-get install php-zip` (Ubuntu/Debian)

#### ext-xml

- **Purpose**: XML parsing and processing
- **Used for**: XML file parsing, RSS feeds
- **Fallback**: Use alternative XML parsers
- **Installation**: Usually included by default

## Version Constraints

**Current**: Using `"*"` (any version)

**Alternative constraints:**

```json
{
  "require": {
    "ext-mbstring": ">=7.0",
    "ext-iconv": ">=7.0",
    "ext-json": ">=7.0",
    "ext-curl": ">=7.0"
  }
}
```

**Note**: Most extensions don't have version numbers, so `"*"` is typically used.

## Validation

### Check Requirements

**Validate extension requirements:**

```bash
composer install --no-dev
```

**Expected behavior:**

- Composer checks all `ext-*` requirements
- Fails if any required extension is missing
- Shows clear error message with missing extensions

### Example Error

**If extension missing:**

```
Your requirements could not be resolved to an installable set of packages.

Problem 1
- The requested PHP extension ext-mbstring has the wrong version (none) installed, or is missing a dependency.
- ordio/landingpage requires ext-mbstring * -> satisfiable by ext-mbstring[*].
```

**Solution:**

1. Install missing extension: `sudo apt-get install php-mbstring`
2. Restart web server: `sudo service php-fpm restart`
3. Re-run Composer: `composer install`

## Installation Instructions

### Ubuntu/Debian

```bash
# Install required extensions
sudo apt-get install php-mbstring php-iconv php-curl

# Install optional extensions
sudo apt-get install php-gd php-zip php-xml

# Restart PHP-FPM
sudo service php-fpm restart
```

### CentOS/RHEL

```bash
# Install required extensions
sudo yum install php-mbstring php-iconv php-curl

# Install optional extensions
sudo yum install php-gd php-zip php-xml

# Restart PHP-FPM
sudo systemctl restart php-fpm
```

### macOS (Homebrew)

```bash
# Install required extensions
brew install php-mbstring php-curl

# Restart PHP
brew services restart php
```

## Verification

### Check Extensions

**Command line:**

```bash
# List all loaded extensions
php -m

# Check specific extension
php -r "echo extension_loaded('mbstring') ? 'Loaded' : 'Not loaded';"
```

**Via Composer:**

```bash
# Validate requirements
composer validate

# Check platform requirements
composer show --platform
```

## Troubleshooting

### Composer Fails During Install

**Symptoms:**

- `composer install` fails
- Error about missing `ext-*` package

**Solutions:**

1. **Install missing extension:**

   ```bash
   sudo apt-get install php-mbstring
   ```

2. **Verify extension loaded:**

   ```bash
   php -m | grep mbstring
   ```

3. **Restart web server:**

   ```bash
   sudo service php-fpm restart
   ```

4. **Re-run Composer:**
   ```bash
   composer install --no-dev
   ```

### Extension Installed But Composer Still Fails

**Symptoms:**

- Extension shows in `php -m`
- Composer still reports missing

**Solutions:**

1. **Check PHP version:**

   ```bash
   php -v
   # Composer may use different PHP version
   ```

2. **Check Composer PHP:**

   ```bash
   composer show --platform | grep php
   ```

3. **Use same PHP for Composer:**
   ```bash
   /usr/bin/php8.0 /usr/local/bin/composer install
   ```

### Extension Works But Not Detected

**Symptoms:**

- Extension works in code
- Composer doesn't detect it

**Solutions:**

1. **Check php.ini:**

   ```bash
   php --ini
   # Verify extension line is uncommented
   ```

2. **Check extension directory:**

   ```bash
   php -i | grep extension_dir
   # Verify extension files exist
   ```

3. **Restart web server:**
   ```bash
   sudo service php-fpm restart
   ```

## CI/CD Integration

### GitHub Actions

```yaml
name: Validate Extensions

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: "8.0"
          extensions: mbstring, iconv, curl, json
      - name: Install dependencies
        run: composer install --no-dev
```

### GitLab CI

```yaml
validate:
  image: php:8.0
  before_script:
    - apt-get update && apt-get install -y php-mbstring php-iconv php-curl
  script:
    - composer install --no-dev
```

## Best Practices

1. **Declare all required extensions** in `composer.json`
2. **Use `suggest` for optional extensions** that enhance functionality
3. **Test Composer install** in clean environment before deployment
4. **Document extension requirements** in README
5. **Provide installation instructions** for common platforms

## Related Documentation

- `composer.json` - Extension requirements configuration
- `docs/development/PHP_EXTENSION_DEPENDENCIES.md` - Extension dependencies guide
- `docs/development/PRODUCTION_DEPLOYMENT_CHECKLIST.md` - Deployment checklist
- `.cursor/rules/php-extensions.mdc` - Cursor rules

## Summary

1. **Composer validates** extension requirements during `composer install`
2. **Required extensions** must be installed or Composer fails
3. **Optional extensions** are suggested but not required
4. **Always test** `composer install` in clean environment
5. **Document** extension requirements and installation steps

**Remember**: Composer validation catches missing extensions early, preventing production failures.