upskill-event-manager/wordpress-dev/CERTIFICATE_TROUBLESHOOTING.md

# Certificate System Troubleshooting Guide

This guide provides steps to diagnose and fix issues with the certificate functionality in the HVAC Community Events plugin.

## Common Issues

1. **500 Error on Certificate Reports Page**
   - Database table might not exist or has incorrect structure
   - Certificate directory might not exist or has incorrect permissions
   - Plugin hooks might not be firing correctly
   - PHP error in the template file

2. **Certificate Generation Issues**
   - PDF generation library might not be installed or configured
   - Temporary directory might not be writable
   - File permissions issues

3. **Certificate Email Issues**
   - Email configuration might be incorrect
   - Attendee email might not exist in the database

## Diagnostic Scripts

We've provided several scripts to help diagnose and fix certificate system issues:

### 1. Debug Certificate System

This script checks all components of the certificate system and identifies issues:

```bash
cd wordpress-dev
./bin/debug-certificate-system.sh
```

The script performs the following checks:
- Plugin files existence
- Database table structure
- Certificate storage directory
- Certificate configuration settings

### 2. Check and Fix Database Tables

This script specifically focuses on the database tables needed for certificates:

```bash
cd wordpress-dev
php bin/check-and-fix-certificate-tables.php
```

The script:
- Checks if certificate table exists
- Creates the table if it doesn't exist
- Verifies the table has the correct structure
- Fixes any missing columns

### 3. Debug Certificate Reports

This script tests the certificate reports functionality:

```bash
cd wordpress-dev
php bin/debug-certificate-reports.php
```

It:
- Simulates loading the certificate reports page
- Runs the same database queries that would run on the page
- Shows detailed output for each query
- Helps identify SQL errors

### 4. Deploy Certificate Fixes

This script automates the deployment of fixes for the certificate system:

```bash
cd wordpress-dev
./bin/deploy-certificate-fixes.sh
```

The script:
- Runs the database fix script
- Fixes certificate directory permissions
- Clears WordPress cache
- Checks plugin status
- Flushes rewrite rules

## Manual Fixing Steps

If the automatic scripts don't resolve the issue, follow these manual steps:

### 1. Check Plugin Activation

Deactivate and reactivate the plugin:

```php
// In WordPress wp-admin > Plugins
// Or via WP-CLI:
wp plugin deactivate hvac-community-events
wp plugin activate hvac-community-events
```

### 2. Check Database Table

Connect to the database and check if the certificate table exists and has the right structure:

```sql
DESCRIBE wp_hvac_certificates;
```

The table should have the following columns:
- `certificate_id` (BIGINT)
- `event_id` (BIGINT)
- `attendee_id` (BIGINT)
- `user_id` (BIGINT)
- `certificate_number` (VARCHAR)
- `file_path` (VARCHAR)
- `date_generated` (DATETIME)
- `generated_by` (BIGINT)
- `revoked` (TINYINT)
- `revoked_date` (DATETIME)
- `revoked_by` (BIGINT)
- `revoked_reason` (TEXT)
- `email_sent` (TINYINT)
- `email_sent_date` (DATETIME)

If the table is missing or has incorrect structure, run:

```php
// Get certificate installer
require_once WP_PLUGIN_DIR . '/hvac-community-events/includes/certificates/class-certificate-installer.php';
$installer = HVAC_Certificate_Installer::instance();
$installer->create_tables();
```

### 3. Check Certificate Directory

Make sure the certificate directory exists and is writable:

```php
$upload_dir = wp_upload_dir();
$cert_dir = $upload_dir['basedir'] . '/hvac-certificates';

// Check if directory exists
if (!file_exists($cert_dir)) {
    wp_mkdir_p($cert_dir);
}

// Set permissions
chmod($cert_dir, 0755);
```

### 4. Debug Template Errors

If you're still getting a 500 error, check the PHP error log for detailed errors.

You can also add debug output to the template file:

```php
// At the top of template-certificate-reports.php
ini_set('display_errors', 1);
error_reporting(E_ALL);

// Add debug output throughout the template
echo "Debug: Got to line X";
var_dump($variable); // Inspect variables
```

### 5. Check for JavaScript Errors

Open your browser's developer console (F12) and check for JavaScript errors when loading the certificate pages.

## Testing Certificate Functionality

After applying fixes, test the certificate functionality with these steps:

1. **Login** as a trainer user
2. **Navigate** to the Generate Certificates page
3. **Select** an event from the dropdown
4. **Generate** certificates for some attendees
5. **Navigate** to the Certificate Reports page
6. **View** the generated certificates
7. **Test** the email functionality
8. **Test** the revoke functionality

## Still Having Issues?

If you continue to experience issues after following this guide:

1. Check the PHP error logs
2. Enable WordPress debugging in wp-config.php:
   ```php
   define('WP_DEBUG', true);
   define('WP_DEBUG_LOG', true);
   define('WP_DEBUG_DISPLAY', true);
   ```
3. Test with a basic WordPress theme to rule out theme conflicts
4. Try deactivating other plugins to check for conflicts