# PHP Extension Monitoring Guide

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

## Overview

This guide explains how to set up monitoring for PHP extensions to detect when critical extensions become unavailable in production.

## Monitoring Script

### Location

`v2/cron/monitor-php-extensions.php`

### Usage

**Manual run:**

```bash
php v2/cron/monitor-php-extensions.php
```

**With verbose output:**

```bash
php v2/cron/monitor-php-extensions.php --verbose
```

**With email alerts:**

```bash
php v2/cron/monitor-php-extensions.php --email
```

### Exit Codes

- `0` - All extensions loaded
- `1` - Critical extensions missing
- `2` - Optional extensions missing (warnings only)

## Cron Setup

### Daily Monitoring

**Add to crontab:**

```bash
crontab -e
```

**Add line:**

```cron
# Daily PHP extension monitoring at 2 AM
0 2 * * * /usr/bin/php /path/to/v2/cron/monitor-php-extensions.php --email >> /var/log/php-extensions-monitor.log 2>&1
```

### Weekly Monitoring

**Add to crontab:**

```cron
# Weekly PHP extension monitoring on Monday at 2 AM
0 2 * * 1 /usr/bin/php /path/to/v2/cron/monitor-php-extensions.php --email --verbose >> /var/log/php-extensions-monitor.log 2>&1
```

### Hourly Monitoring (High Priority)

**For critical systems:**

```cron
# Hourly PHP extension monitoring
0 * * * * /usr/bin/php /path/to/v2/cron/monitor-php-extensions.php --email >> /var/log/php-extensions-monitor.log 2>&1
```

## Alert Configuration

### Email Alerts

**Recipient:** `hady@ordio.com` (configured in script)

**Alert triggers:**
- Critical: Required extensions missing
- Warning: Optional extensions missing

**Email content includes:**
- Missing extensions list
- Installation instructions
- Diagnostic endpoint URL
- PHP version and SAPI information

### Log Monitoring

**Check logs:**

```bash
# View recent monitoring logs
tail -f /var/log/php-extensions-monitor.log

# Search for critical issues
grep "CRITICAL" /var/log/php-extensions-monitor.log

# Search for warnings
grep "WARNING" /var/log/php-extensions-monitor.log
```

### Integration with Monitoring Systems

**Send to monitoring system:**

```bash
# Example: Send to monitoring API
php v2/cron/monitor-php-extensions.php --json | curl -X POST https://monitoring.example.com/api/alerts -d @-
```

## Monitoring Dashboard

### Diagnostic Endpoint

**Access diagnostic information:**

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

**Returns JSON with:**
- PHP version and configuration
- Extension status (required and optional)
- Missing extensions list
- Installation instructions

**Security:** Should be IP-whitelisted or token-protected in production.

### Manual Check

**Check extension status:**

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

# List all loaded extensions
php -m

# Check extension version
php -r "echo phpversion('mbstring');"
```

## Alert Response Procedures

### Critical Alert (Required Extension Missing)

**Immediate actions:**

1. **Verify issue:**
   ```bash
   php v2/scripts/dev-helpers/check-php-extensions.php
   ```

2. **Check diagnostic endpoint:**
   ```
   https://www.ordio.com/v2/api/php-extensions-diagnostics.php
   ```

3. **Install missing extension:**
   ```bash
   sudo apt-get install php-mbstring
   sudo service php-fpm restart
   ```

4. **Verify installation:**
   ```bash
   php -m | grep mbstring
   ```

5. **Test functionality:**
   - Test blog FAQ schema generation
   - Test API endpoints
   - Check error logs

### Warning Alert (Optional Extension Missing)

**Actions:**

1. **Assess impact:**
   - Determine if feature is used
   - Check if fallback is working
   - Review error logs

2. **Install if needed:**
   ```bash
   sudo apt-get install php-gd
   sudo service php-fpm restart
   ```

3. **Monitor fallback usage:**
   - Check error logs for fallback messages
   - Verify functionality still works

## Monitoring Best Practices

### 1. Regular Monitoring

- **Daily checks** for critical systems
- **Weekly checks** for standard systems
- **Hourly checks** for high-priority systems

### 2. Alert Thresholds

- **Critical:** Required extensions missing
- **Warning:** Optional extensions missing
- **Info:** All extensions loaded

### 3. Log Retention

**Retain logs for analysis:**

```bash
# Rotate logs monthly
logrotate -d /etc/logrotate.d/php-extensions-monitor
```

**Log rotation config:**

```
/var/log/php-extensions-monitor.log {
    monthly
    rotate 12
    compress
    delaycompress
    notifempty
    create 0644 www-data www-data
}
```

### 4. Trend Analysis

**Track extension availability over time:**

```bash
# Extract extension status from logs
grep "PHP Extensions Monitor" /var/log/php-extensions-monitor.log | tail -30
```

## Integration Examples

### Nagios Check

**Create Nagios check script:**

```bash
#!/bin/bash
php /path/to/v2/cron/monitor-php-extensions.php
exit $?
```

**Nagios command:**

```
define command {
    command_name    check_php_extensions
    command_line    /usr/lib/nagios/plugins/check_php_extensions.sh
}
```

### Zabbix Monitoring

**Zabbix item:**

```
php.extensions.missing[mbstring]
```

**Zabbix script:**

```bash
#!/bin/bash
php /path/to/v2/cron/monitor-php-extensions.php --json | jq '.summary.missing_required | length'
```

### Prometheus Metrics

**Export metrics:**

```php
<?php
$results = json_decode(shell_exec('php monitor-php-extensions.php --json'), true);
echo "php_extensions_loaded_total " . $results['summary']['loaded_required'] . "\n";
echo "php_extensions_missing_total " . $results['summary']['missing_required'] . "\n";
```

## Troubleshooting

### Monitoring Script Not Running

**Symptoms:**
- No logs generated
- Cron job not executing

**Solutions:**

1. **Check cron service:**
   ```bash
   sudo service cron status
   ```

2. **Check cron logs:**
   ```bash
   grep CRON /var/log/syslog
   ```

3. **Test script manually:**
   ```bash
   php v2/cron/monitor-php-extensions.php --verbose
   ```

4. **Verify file permissions:**
   ```bash
   ls -l v2/cron/monitor-php-extensions.php
   chmod +x v2/cron/monitor-php-extensions.php
   ```

### False Positives

**Symptoms:**
- Alerts for extensions that are actually loaded
- Different results between CLI and web server

**Solutions:**

1. **Check PHP version:**
   ```bash
   php -v
   php -i | grep "PHP Version"
   ```

2. **Check different php.ini:**
   ```bash
   php --ini
   # CLI and web server may use different php.ini files
   ```

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

### Email Not Sending

**Symptoms:**
- Script runs but no email received
- Email function fails

**Solutions:**

1. **Check mail function:**
   ```bash
   php -r "var_dump(function_exists('mail'));"
   ```

2. **Test email manually:**
   ```php
   <?php
   mail('hady@ordio.com', 'Test', 'Test message');
   ```

3. **Check mail logs:**
   ```bash
   tail -f /var/log/mail.log
   ```

## Related Documentation

- `v2/cron/monitor-php-extensions.php` - Monitoring script
- `docs/development/PHP_EXTENSION_DEPENDENCIES.md` - Extension dependencies
- `v2/api/php-extensions-diagnostics.php` - Diagnostic endpoint
- `.cursor/rules/php-extensions.mdc` - Cursor rules

## Summary

1. **Set up cron job** for regular monitoring
2. **Configure email alerts** for critical issues
3. **Monitor logs** for trends and issues
4. **Respond quickly** to critical alerts
5. **Document** monitoring setup and procedures

**Remember**: Proactive monitoring prevents production failures. Set up monitoring before issues occur.