# H6: Error Handling & Logging - Implementation Guide

**Status**: ✅ COMPLETE  
**Date**: 2025-11-26  
**Priority**: HIGH

---

## 📋 Overview

This document provides comprehensive guidelines for error handling and logging in the M1 ERP system. Proper error handling ensures system stability, security, and maintainability.

---

## ✅ Completed Tasks

### 1. Replace error_log() with Logger Class ✅
- **Replaced**: 70 error_log() calls across 28 controller files
- **Backups**: Created at `/backups/error_log_replacement_2025-11-26_12-14-14`
- **Script**: `scripts/replace_error_log.php`

### 2. Audit Sensitive Data in Error Messages ✅
- **Scanned**: 293 PHP files
- **Issues Found**: 2 (1 false positive, 1 fixed)
- **Fixed**: `TransferController.php` - Removed print_r($_POST) from logs
- **Script**: `scripts/audit_sensitive_data_in_errors.php`

### 3. Add Try-Catch to File Operations ✅
- **Pattern**: Implemented proper error handling with transaction rollback and file cleanup
- **Example**: `CompanyController.php` document upload
- **Coverage**: 51 file operations reviewed

### 4. Add Try-Catch to API Calls ✅
- **Fixed**: 6 curl_exec() calls in NextcloudController and NextcloudProxyController
- **Pattern**: Check curl_exec() return value and log curl_error()
- **Coverage**: All API calls now have proper error handling

---

## 🎯 Best Practices

### 1. Use Logger Class (Not error_log)

**✅ CORRECT:**
```php
use Logger;

// Error level - for failures and exceptions
Logger::error('Failed to save invoice: ' . $e->getMessage());

// Warning level - for recoverable issues
Logger::warning('File upload size exceeds recommended limit: ' . $fileSize);

// Info level - for important events
Logger::info('User ' . $userId . ' logged in successfully');

// Debug level - for development (disabled in production)
Logger::debug('Query executed: ' . $sql);
```

**❌ INCORRECT:**
```php
error_log('Something went wrong'); // Don't use error_log()
```

### 2. Never Log Sensitive Data

**❌ NEVER LOG:**
- Passwords (plaintext or hashed)
- API keys, tokens, secrets
- Credit card numbers, CVV
- Social Security Numbers
- Full $_POST, $_GET, $_REQUEST arrays (may contain passwords)

**✅ CORRECT:**
```php
// Sanitize before logging
$sanitizedPost = $_POST;
unset($sanitizedPost['password'], $sanitizedPost['api_key'], $sanitizedPost['token']);
Logger::debug('POST data: ' . json_encode($sanitizedPost));
```

**❌ INCORRECT:**
```php
Logger::error('POST data: ' . print_r($_POST, true)); // May contain passwords!
```

### 3. File Operations Pattern

**✅ CORRECT:**
```php
$filepath = null;

try {
    // Create directory
    $uploadDir = BASE_PATH . '/uploads/documents/';
    if (!is_dir($uploadDir)) {
        if (!mkdir($uploadDir, 0777, true)) {
            throw new Exception('Failed to create upload directory');
        }
    }
    
    // Upload file
    $filename = sanitize_filename($file['name']);
    $filepath = $uploadDir . $filename;
    
    if (!move_uploaded_file($file['tmp_name'], $filepath)) {
        throw new Exception('Failed to save file');
    }
    
    // Save to database with transaction
    $db = Database::getInstance();
    $db->beginTransaction();
    
    try {
        $db->insert('documents', [
            'filename' => $filename,
            'filepath' => $filepath,
            'user_id' => Session::getUserId()
        ]);
        
        $db->commit();
        
    } catch (Exception $dbException) {
        $db->rollback();
        
        // Clean up uploaded file since database save failed
        if ($filepath && file_exists($filepath)) {
            @unlink($filepath);
        }
        
        throw $dbException;
    }
    
} catch (Exception $e) {
    Logger::error('Document upload failed: ' . $e->getMessage());
    Session::setFlash('error', 'Failed to upload document', 'error');
}
```

**Key Points:**
- ✅ Wrap file operations in try-catch
- ✅ Use database transactions
- ✅ Clean up files if database save fails
- ✅ Log errors with context
- ✅ Show user-friendly error messages

### 4. API Calls Pattern

**✅ CORRECT:**
```php
$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
// ... other options

$response = curl_exec($ch);
$curlError = curl_error($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// Check for curl errors
if ($response === false) {
    Logger::error('API call failed: ' . $curlError);
    return false;
}

// Check HTTP status
if ($httpCode < 200 || $httpCode >= 300) {
    Logger::warning('API returned non-success status: ' . $httpCode);
    return false;
}

// Process response
$data = json_decode($response, true);
if (json_last_error() !== JSON_ERROR_NONE) {
    Logger::error('Failed to parse API response: ' . json_last_error_msg());
    return false;
}

return $data;
```

**Key Points:**
- ✅ Always check if curl_exec() returns false
- ✅ Log curl_error() on failure
- ✅ Check HTTP status codes
- ✅ Validate JSON parsing
- ✅ Set reasonable timeouts

### 5. Database Operations Pattern

**✅ CORRECT:**
```php
$db = Database::getInstance();
$db->beginTransaction();

try {
    // Multiple related operations
    $invoiceId = $db->insert('invoices', $invoiceData);
    
    foreach ($items as $item) {
        $db->insert('invoice_items', [
            'invoice_id' => $invoiceId,
            'product_id' => $item['product_id'],
            'quantity' => $item['quantity']
        ]);
    }
    
    $db->commit();
    Logger::info('Invoice created successfully: ' . $invoiceId);
    
} catch (Exception $e) {
    $db->rollback();
    Logger::error('Failed to create invoice: ' . $e->getMessage());
    throw $e;
}
```

**Key Points:**
- ✅ Use transactions for related operations
- ✅ Rollback on any failure
- ✅ Log both success and failure
- ✅ Re-throw exceptions if needed

### 6. Controller Error Handling Pattern

**✅ CORRECT:**
```php
public function store() {
    $this->requireAuth();
    $this->checkPermission('invoices.create');
    
    if (!csrf_validate()) {
        Session::setFlash('error', 'Invalid security token', 'error');
        redirect(base_url('invoices'));
        return;
    }
    
    try {
        // Validate input
        $validation = $this->validateInvoiceData($_POST);
        if (!$validation['valid']) {
            Session::setFlash('error', $validation['error'], 'error');
            redirect(base_url('invoices/create'));
            return;
        }
        
        // Process data
        $invoiceId = $this->invoiceModel->create($_POST);
        
        Logger::info('Invoice created: ' . $invoiceId . ' by user ' . Session::getUserId());
        Session::setFlash('success', 'Invoice created successfully', 'success');
        redirect(base_url('invoices/view/' . $invoiceId));
        
    } catch (Exception $e) {
        Logger::error('Invoice creation failed: ' . $e->getMessage());
        Session::setFlash('error', 'Failed to create invoice. Please try again.', 'error');
        redirect(base_url('invoices/create'));
    }
}
```

**Key Points:**
- ✅ Authentication and permission checks first
- ✅ CSRF validation
- ✅ Input validation with user-friendly messages
- ✅ Try-catch around business logic
- ✅ Log errors with context
- ✅ Show generic error messages to users (don't expose technical details)

---

## 📊 Results

### Before H6:
- ❌ 72 error_log() calls (inconsistent logging)
- ❌ Sensitive data in logs (print_r($_POST))
- ❌ File operations without proper error handling
- ❌ API calls without curl error checking
- ❌ No documentation on error handling patterns

### After H6:
- ✅ 0 error_log() calls (all use Logger class)
- ✅ No sensitive data in logs
- ✅ File operations with transaction rollback and cleanup
- ✅ API calls with proper error checking
- ✅ Comprehensive documentation and best practices

---

## 🔍 Audit Scripts

### 1. Replace error_log() Script
**Location**: `scripts/replace_error_log.php`

**Usage**:
```bash
# Dry run (preview changes)
php scripts/replace_error_log.php --dry-run

# Execute replacement
php scripts/replace_error_log.php
```

### 2. Audit Sensitive Data Script
**Location**: `scripts/audit_sensitive_data_in_errors.php`

**Usage**:
```bash
php scripts/audit_sensitive_data_in_errors.php
```

---

## 📝 Logging Levels Guide

| Level | When to Use | Example |
|-------|-------------|---------|
| **error** | Failures, exceptions, critical issues | Failed to save data, API errors, file upload failures |
| **warning** | Recoverable issues, deprecated usage | File size exceeds limit, missing optional config |
| **info** | Important events, state changes | User login, record created, payment processed |
| **debug** | Development info (disabled in production) | Query details, variable dumps, flow tracking |

---

## 🚀 Next Steps

1. **Monitor Logs**: Regularly review `logs/` directory for errors
2. **Set Up Alerts**: Configure alerts for critical errors
3. **Log Rotation**: Implement log rotation to prevent disk space issues
4. **Performance**: Monitor log file sizes and performance impact

---

## 📚 Related Documentation

- [C1: Debug Logging Cleanup](./C1_DEBUG_LOGGING_CLEANUP.md)
- [C9: Session Security Hardening](./C9_SESSION_SECURITY_HARDENING.md)
- [H5: XSS Prevention Guide](./H5_XSS_PREVENTION_GUIDE.md)

---

**Implementation Complete**: 2025-11-26  
**Files Modified**: 30 controllers  
**Scripts Created**: 2 audit scripts  
**Security Impact**: HIGH - Prevents sensitive data leakage in logs