# Production Deployment Checklist

**Last Updated:** 2026-02-28

## Overview

This checklist ensures all PHP extension dependencies are verified before deployment to prevent production failures. Use this checklist before every deployment.

## Pre-Deployment Checklist

### 0. Quick Pre-Deploy (Recommended)

Run a single command that minifies assets, validates PHP extensions, and checks schema:

```bash
make pre-deploy
# or
npm run pre-deploy
```

This runs: `npm run minify` + `composer validate:php` + `composer schema`. See `docs/development/DEV_TOOLING.md` for details.

### 1. PHP Extension Validation

**Run extension validator:**

```bash
php v2/scripts/dev-helpers/check-php-extensions.php
```

**Expected output:**

- ✅ All required extensions loaded
- ✅ Optional extensions status reported
- ✅ Exit code 0 if all checks pass

**If extensions missing:**

- Install missing extensions (see installation instructions)
- Verify installation: `php -m | grep <extension-name>`
- Re-run validator

### 2. Pre-Deployment Comprehensive Check

**Run comprehensive validator:**

```bash
php v2/scripts/dev-helpers/pre-deployment-check.php
```

**Checks performed:**

- PHP version compatibility
- Required PHP extensions
- Optional PHP extensions
- File permissions
- Required directories
- Configuration files

**Expected output:**

- ✅ All checks passed
- Exit code 0 if successful

### 3. Composer Validation

**Verify Composer extension requirements:**

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

**Expected behavior:**

- Composer validates extension requirements
- Fails if required extensions missing
- Installs dependencies successfully

**If Composer fails:**

- Check `composer.json` for `ext-*` requirements
- Install missing extensions
- Re-run `composer install`

### 4. Local Testing with Extensions Disabled

**Test fallback logic (if possible):**

```bash
# Temporarily disable extension in php.ini
# Comment out: extension=mbstring

# Run test script
php v2/scripts/dev-helpers/test-extension-fallbacks.php

# Re-enable extension
```

**Expected behavior:**

- Code executes without fatal errors
- Fallback logic activates
- Error logs show fallback usage
- Functionality degrades gracefully

### 5. Code Review

**Verify code follows patterns:**

- [ ] All `mb_*` function calls have `function_exists()` checks
- [ ] All `iconv_*` function calls have `function_exists()` checks
- [ ] All `curl_*` function calls have `function_exists()` checks
- [ ] All `gd_*` function calls have `extension_loaded()` checks
- [ ] Fallback logic implemented for optional extensions
- [ ] Error logging when fallbacks are used
- [ ] No direct extension function calls without checks

**Search for problematic patterns:**

```bash
# Find mb_* calls without checks
grep -r "mb_[a-z_]*(" v2/ --include="*.php" | grep -v "function_exists\|extension_loaded\|_has_mbstring"

# Find curl_* calls without checks
grep -r "curl_[a-z_]*(" v2/ --include="*.php" | grep -v "function_exists\|extension_loaded"
```

### 6. Production Environment Verification

**Check production environment:**

```bash
# On production server (or via SSH)
php -m | grep -E "mbstring|iconv|curl|gd|zip|xml|json"

# Check PHP version
php -v

# Check extension configuration
php -i | grep -E "extension_dir|mbstring|iconv"
```

**Expected:**

- All required extensions listed
- PHP version matches requirements
- Extension directory configured correctly

### 7. Diagnostic Endpoint Check

**Access diagnostic endpoint:**

```
https://www.ordio.com/v2/api/php-extensions-diagnostics.php
```

**Verify:**

- All required extensions show as loaded
- PHP version matches requirements
- Extension versions reported correctly

**Security:**

- Endpoint should be IP-whitelisted or token-protected
- Remove or secure after verification

## Deployment Steps

### Step 1: Backup Current State

```bash
# Backup configuration files
cp php.ini php.ini.backup

# Backup code (if using version control)
git tag pre-deployment-$(date +%Y%m%d-%H%M%S)
```

### Step 2: Deploy Code

```bash
# Deploy via your standard process
# Git, rsync, FTP, etc.
```

### Step 3: Verify Deployment

**Run post-deployment checks:**

```bash
# Check extension availability
php -r "echo extension_loaded('mbstring') ? 'OK' : 'MISSING';"

# Run comprehensive check
php v2/scripts/dev-helpers/pre-deployment-check.php
```

### Step 4: Test Critical Functionality

**Test features that use extensions:**

- Blog FAQ schema generation (mbstring)
- Image processing (gd)
- API requests (curl)
- Excel generation (zip, xml)

**Expected:**

- All features work correctly
- No fatal errors in error logs
- Fallback logic activates if needed

### Step 5: Monitor Error Logs

**Check error logs after deployment:**

```bash
# Check PHP error log
tail -f /var/log/php/error.log

# Check application error log
tail -f v2/logs/*.log
```

**Look for:**

- Extension-related errors
- Fallback usage messages
- Fatal errors

## Post-Deployment Verification

### 1. Functional Testing

**Test critical paths:**

- [ ] Blog posts load correctly
- [ ] FAQ schema generates correctly
- [ ] API endpoints respond
- [ ] Image processing works (if applicable)
- [ ] Excel generation works (if applicable)

### 2. Error Log Review

**Review logs for:**

- Extension-related errors
- Fallback usage (should be logged)
- Fatal errors
- Warnings

**If errors found:**

- Identify root cause
- Fix or implement fallback
- Re-deploy if necessary

### 3. Performance Monitoring

**Monitor:**

- Page load times
- Error rates
- Fallback usage frequency

**If performance degraded:**

- Check if fallbacks are being used excessively
- Consider installing missing extensions
- Optimize fallback logic

## Troubleshooting

### Extension Missing After Deployment

**Symptoms:**

- Code works locally
- Fails in production
- Extension shows as not loaded

**Solutions:**

1. **Verify extension installed:**

   ```bash
   php -m | grep <extension-name>
   ```

2. **Check php.ini:**

   ```bash
   php --ini
   # Edit php.ini and uncomment extension line
   ```

3. **Restart web server:**

   ```bash
   sudo service php-fpm restart
   # OR
   sudo service apache2 restart
   ```

4. **Check extension directory:**
   ```bash
   php -i | grep extension_dir
   # Verify extension files exist
   ```

### Fallback Not Working

**Symptoms:**

- Extension missing
- Fallback should activate but doesn't
- Code still fails

**Solutions:**

1. **Check fallback logic:**

   ```php
   // Add logging
   if (!extension_loaded('mbstring')) {
       error_log('mbstring not available, using fallback');
       // Fallback code
   }
   ```

2. **Verify function checks:**

   ```php
   // Ensure checks are correct
   if (function_exists('mb_strlen')) {
       // Use mbstring
   } else {
       // Use fallback
   }
   ```

3. **Test locally:**
   - Disable extension temporarily
   - Test fallback logic
   - Re-enable extension

### Composer Fails During Deployment

**Symptoms:**

- `composer install` fails
- Extension requirement errors

**Solutions:**

1. **Check composer.json:**

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

2. **Install missing extensions:**

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

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

## Quick Reference

### Required Extensions

- `json` - JSON encoding/decoding
- `mbstring` - UTF-8 text processing
- `iconv` - Character encoding (fallback)
- `curl` - HTTP requests

### Optional Extensions

- `gd` - Image processing
- `zip` - ZIP archives
- `xml` - XML parsing

### Validation Commands

```bash
# Quick pre-deploy (recommended)
make pre-deploy
# or: npm run pre-deploy

# Composer scripts (run steps 1-2)
composer validate:php
composer schema

# Individual checks
php v2/scripts/dev-helpers/check-php-extensions.php
php v2/scripts/dev-helpers/pre-deployment-check.php
php v2/scripts/dev-helpers/test-extension-fallbacks.php
composer install --no-dev
```

### Diagnostic Endpoints

- `/v2/api/php-extensions-diagnostics.php` - Extension diagnostics

## Related Documentation

- `docs/development/DEV_TOOLING.md` - Linting, validation, Makefile, Composer scripts
- `docs/development/PHP_EXTENSION_DEPENDENCIES.md` - Extension dependencies guide
- `docs/development/PHP_EXTENSION_FALLBACK_PATTERNS.md` - Fallback patterns
- `.cursor/rules/php-extensions.mdc` - Cursor rules
- `docs/content/blog/MBSTRING_FIX_SUMMARY.md` - mbstring fix documentation

## Summary

**Before every deployment:**

1. ✅ Run extension validator
2. ✅ Run pre-deployment check
3. ✅ Verify Composer requirements
4. ✅ Test fallback logic locally
5. ✅ Review code for extension checks
6. ✅ Verify production environment
7. ✅ Check diagnostic endpoint

**After deployment:**

1. ✅ Verify functionality
2. ✅ Review error logs
3. ✅ Monitor performance
4. ✅ Check fallback usage

**Remember**: Prevention is better than fixing production issues. Always validate extensions before deployment.