# Deployment Process Guide

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

## Overview

This guide provides a comprehensive deployment process that includes PHP extension validation, pre-deployment checks, and post-deployment verification to prevent production failures.

## Pre-Deployment Checklist

### 1. Run Pre-Deployment Validation

**Run comprehensive validation script:**

```bash
./scripts/deployment/pre-deployment-validate.sh
```

**With verbose output:**

```bash
./scripts/deployment/pre-deployment-validate.sh --verbose
```

**Expected result:**
- ✅ All checks passed
- Exit code 0

**If checks fail:**
- Review error messages
- Fix issues
- Re-run validation

### 2. PHP Extension Validation

**Check extensions:**

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

**Verify:**
- All required extensions loaded
- Optional extensions status noted
- No missing critical extensions

### 3. Pre-Deployment Comprehensive Check

**Run comprehensive check:**

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

**Verify:**
- PHP version compatible
- All required extensions available
- File permissions correct
- Required directories exist

### 4. Extension Fallback Tests

**Test fallback logic:**

```bash
php v2/scripts/dev-helpers/test-extension-fallbacks.php
```

**Verify:**
- All fallback tests pass
- Fallback logic works correctly
- No fatal errors

### 5. Unit Tests

**Run unit tests:**

```bash
php tests/php-extensions/ExtensionFallbackTest.php
```

**Verify:**
- All unit tests pass
- Helper functions work correctly

### 6. Code Review

**Review code for:**

- [ ] Extension function calls have checks
- [ ] Fallback logic implemented
- [ ] Error logging in place
- [ ] No direct extension 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\|safe_mb_"

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

## Deployment Steps

### Step 1: Backup Current State

**Backup code:**

```bash
# Git tag
git tag pre-deployment-$(date +%Y%m%d-%H%M%S)

# Or create backup
tar -czf backup-$(date +%Y%m%d-%H%M%S).tar.gz v2/
```

**Backup configuration:**

```bash
# Backup php.ini if modified
cp /etc/php/8.0/fpm/php.ini /etc/php/8.0/fpm/php.ini.backup
```

### Step 2: Deploy Code

**Deploy via your standard process:**

- Git pull
- rsync
- FTP
- CI/CD pipeline

### Step 3: Verify Deployment

**Run post-deployment checks:**

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

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

# Check diagnostic endpoint (if accessible)
curl https://www.ordio.com/v2/api/php-extensions-diagnostics.php
```

### Step 4: Test Critical Functionality

**Test features that use extensions:**

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

**Expected:**
- All features work correctly
- No fatal errors
- Fallback logic activates if needed

### Step 5: Monitor Error Logs

**Check error logs:**

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

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

**Look for:**
- Extension-related errors
- Fallback usage messages
- Fatal errors
- Warnings

## 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 being used excessively
- Consider installing missing extensions
- Optimize fallback logic

## Rollback Procedure

### If Deployment Fails

1. **Identify issue:**
   - Check error logs
   - Review diagnostic endpoint
   - Test critical functionality

2. **Rollback code:**
   ```bash
   # Git rollback
   git reset --hard <previous-commit>
   git push --force
   
   # Or restore backup
   tar -xzf backup-YYYYMMDD-HHMMSS.tar.gz
   ```

3. **Verify rollback:**
   - Test critical functionality
   - Check error logs
   - Verify extensions still work

## 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
   ```

### Fallback Not Working

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

**Solutions:**

1. **Check fallback logic:**
   ```php
   if (!extension_loaded('mbstring')) {
       error_log('mbstring not available, using fallback');
       // Fallback code
   }
   ```

2. **Verify function checks:**
   ```php
   if (function_exists('mb_strlen')) {
       // Use mbstring
   } else {
       // Use fallback
   }
   ```

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

## Quick Reference

### Required Extensions

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

### Validation Commands

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

# Comprehensive check
php v2/scripts/dev-helpers/pre-deployment-check.php

# Fallback tests
php v2/scripts/dev-helpers/test-extension-fallbacks.php

# Unit tests
php tests/php-extensions/ExtensionFallbackTest.php

# Pre-deployment validation
./scripts/deployment/pre-deployment-validate.sh
```

### Diagnostic Endpoints

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

## Related Documentation

- `docs/development/PRODUCTION_DEPLOYMENT_CHECKLIST.md` - Detailed checklist
- `docs/development/PHP_EXTENSION_DEPENDENCIES.md` - Extension dependencies
- `docs/development/PHP_EXTENSION_TESTING.md` - Testing procedures
- `.cursor/rules/php-extensions.mdc` - Cursor rules

## Summary

**Before every deployment:**

1. ✅ Run pre-deployment validation
2. ✅ Check PHP extensions
3. ✅ Test fallback logic
4. ✅ Review code for extension checks
5. ✅ Verify production environment

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