# System Setup — PHP Extensions

## Required extensions (in `composer.json`)

| Extension | Used for | Enabled? |
|-----------|----------|----------|
| `pdo` | Database abstraction | ✅ |
| `pdo_sqlite` | SQLite driver | ✅ |
| `sqlite3` | Direct SQLite (migrations) | ✅ |
| `openssl` | AES-256-GCM encryption, TLS, CSRNG | ✅ |
| `json` | API responses, config, logging | ✅ |
| `ctype` | Character type checks (Composer/vendor) | ✅ (polyfill) |
| `filter` | Input validation (`filter_var`) | ✅ |
| `hash` | Password hashing, checksums | ✅ |
| `mbstring` | Multibyte string handling | ✅ (polyfill) |
| `iconv` | Character encoding conversion (vendor) | ⚠️ (polyfill) |
| `tokenizer` | PHP-CS-Fixer, PHPStan | ✅ |
| `fileinfo` | MIME type detection (FilePond uploads) | ✅ |
| `curl` | HTTP requests (PeerTube, external APIs) | ✅ |
| `zip` | ZIP export (ExportController), vendor packages | ✅ |
| `dom` | HTML/XML parsing (vendor, Parsedown→CommonMark) | ✅ |
| `libxml` | XML parsing | ✅ |
| `session` | Admin auth, CSRF, flash messages | ✅ |
| `zlib` | Compression, vendor packages | ✅ |

## Recommended extensions (not required, but useful)

| Extension | Purpose | Add? |
|-----------|---------|------|
| `gd` | Image resizing/thumbnails (cover images) | ⬜ Future |
| `exif` | Image metadata extraction | ⬜ Future |
| `sodium` | Modern crypto primitives (alternative to openssl) | ⬜ Optional |
| `intl` | Unicode collation, date formatting (locale-aware) | ⬜ Optional |

## Production server (nginx + PHP-FPM)

The production server runs PHP 8.4 FPM. The nginx config references:
```
fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;
```

### Production extension list

Same as above, plus:
- `php8.4-fpm` (the FPM SAPI itself)

### Enabling an extension on Arch Linux

Extensions are compiled as shared objects (`.so` files) and live in
`/usr/lib/php/modules/`.  To enable one:

```bash
# 1. Verify the .so file exists
ls /usr/lib/php/modules/iconv.so

# 2. Add to /etc/php/php.ini
echo "extension=iconv" >> /etc/php/php.ini

# 3. Verify it loaded
php -m | grep iconv

# 4. Restart PHP-FPM (production)
sudo systemctl restart php8.4-fpm
```

### Checking the production server

```bash
# SSH into the server
ssh xamxam

# List loaded extensions
php -m

# List available (compiled but not loaded) extensions
ls /usr/lib/php/modules/

# Check PHP-FPM status
sudo systemctl status php8.4-fpm
```

## Required shared objects on current dev machine

The following `.so` files exist in `/usr/lib/php/modules/` but are **not loaded**:

| Extension | `.so` present? | Currently loaded? | Needed? |
|-----------|---------------|-------------------|---------|
| `iconv` | ✅ `iconv.so` | ❌ (polyfill) | For production — enable native to avoid polyfill overhead |
| `gd` | ❌ | ❌ | Not yet, but useful for cover image thumbnails |
| `exif` | ✅ `exif.so` | ❌ | Not yet |
| `intl` | ✅ `intl.so` | ❌ | Not yet |
| `sodium` | ❌ | ❌ | Not yet |
| `bcmath` | ✅ `bcmath.so` | ❌ | No |
| `bz2` | ✅ `bz2.so` | ❌ | No |
| `gmp` | ✅ `gmp.so` | ❌ | No |
| `ldap` | ✅ `ldap.so` | ❌ | No — future LDAP auth planned |

## Quick enable for production parity

To match what composer expects natively (no polyfills needed on server):

```bash
# On the server
echo "extension=iconv" | sudo tee -a /etc/php/php.ini
echo "extension=mbstring" | sudo tee -a /etc/php/php.ini
sudo systemctl restart php8.4-fpm
```

`iconv` and `mbstring` are currently satisfied by Symfony polyfills on the dev
machine. Enabling them natively on the server is a free performance improvement
and avoids a class of polyfill edge cases.

## composer.json platform requirements

```json
"require": {
    "php": ">=8.4",
    "ext-json": "*",
    "ext-pdo": "*",
    "ext-openssl": "*"
}
```

These three are declared explicitly because the application cannot function
without them. All other extensions (curl, zip, dom, etc.) are required
transitively by vendor packages and will cause a `composer install` failure
if missing.