xamxam/docs/system-setup.md

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:

# 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

# 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):

# 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

"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.