# cPanel Deployment Guide - PHP 8 Compatibility Fix

**Issue**: PHP 8 deprecation notices and session errors on cPanel hosting

**Date**: 2025-11-20

---

## ✅ FIXES ALREADY APPLIED (Local Changes)

The following fixes have been applied to your local code and need to be uploaded to cPanel:

### 1. Session Driver PHP 8 Compatibility
**File**: `system/libraries/Session/drivers/Session_database_driver.php`

**Changes**: Added `#[\ReturnTypeWillChange]` attribute to 6 methods:
- Line 129: `open()` method
- Line 152: `read()` method
- Line 210: `write()` method
- Line 283: `close()` method
- Line 301: `destroy()` method
- Line 340: `gc()` method

**Result**: Suppresses PHP 8.0+ SessionHandlerInterface deprecation notices

---

## 🚀 DEPLOYMENT STEPS

### Step 1: Upload Fixed Files

**Upload this file to cPanel:**
```
system/libraries/Session/drivers/Session_database_driver.php
```

**Using cPanel File Manager:**
1. Login to cPanel
2. Open File Manager
3. Navigate to `public_html/system/libraries/Session/drivers/`
4. Upload `Session_database_driver.php` (overwrite existing)

**Using FTP:**
1. Connect to your server via FTP
2. Navigate to `/public_html/system/libraries/Session/drivers/`
3. Upload `Session_database_driver.php` (overwrite existing)

---

### Step 2: Set Environment to Production

**Option A: Using .env file (Recommended)**

1. Create/edit file: `/.env` in root directory
2. Add this line:
```
CI_ENV=production
```

**Option B: Edit index.php directly**

Change line 19 in `index.php`:

**FROM:**
```php
define('ENVIRONMENT', isset($_SERVER['CI_ENV']) ? $_SERVER['CI_ENV'] : 'development');
```

**TO:**
```php
define('ENVIRONMENT', isset($_SERVER['CI_ENV']) ? $_SERVER['CI_ENV'] : 'production');
```

---

### Step 3: Verify PHP Version

**Check cPanel PHP Version:**
1. Login to cPanel
2. Go to "Select PHP Version" or "MultiPHP Manager"
3. Verify you're using PHP 8.0 or higher
4. Recommended: PHP 8.1 or 8.2 (not 8.3 yet for CodeIgniter 3)

**Compatible PHP Versions for CodeIgniter 3:**
- ✅ PHP 7.4 (no deprecation notices)
- ✅ PHP 8.0 (with our fixes)
- ✅ PHP 8.1 (with our fixes)
- ⚠️ PHP 8.2 (with our fixes, may have other warnings)
- ❌ PHP 8.3 (not fully tested with CodeIgniter 3)

---

### Step 4: Configure Production Error Handling

**File**: `application/config/config.php`

**Line 231**: Ensure error logging is enabled:
```php
$config['log_threshold'] = 4; // Already set
```

**Result**:
- Errors logged to `application/logs/log-YYYY-MM-DD.php`
- Errors NOT displayed to users (security best practice)
- You can check logs via cPanel File Manager

---

### Step 5: Database Configuration for Production

**File**: `application/config/database.php`

**Verify for production environment:**
```php
$db['default']['hostname'] = 'localhost'; // or your DB host
$db['default']['username'] = 'YOUR_CPANEL_DB_USERNAME';
$db['default']['password'] = 'YOUR_CPANEL_DB_PASSWORD';
$db['default']['database'] = 'YOUR_CPANEL_DB_NAME';
$db['default']['db_debug'] = FALSE; // IMPORTANT: Set to FALSE for production
```

**IMPORTANT**: Set `db_debug` to FALSE in production to prevent database errors being displayed to users!

---

### Step 6: Verify Multi-Tenant Configuration

**File**: `application/config/tenant_databases.php`

Ensure all database names match your cPanel database names:
```php
'default' => array(
    'database' => 'webpos', // Your actual cPanel database name
    ...
)
```

**Note**: cPanel database names are usually prefixed with your username:
- Example: `username_webpos`
- Check cPanel > MySQL Databases for exact names

---

## 🔍 VERIFICATION AFTER DEPLOYMENT

### Test 1: Check Errors Disappeared

1. Visit your site: `https://yourdomain.com`
2. Verify NO PHP deprecation errors displayed
3. Page should load cleanly

**Expected**: Login page appears without errors

---

### Test 2: Login Functionality

1. Enter username and password
2. Click "Sign In"
3. Verify successful login

**Expected**: Dashboard loads successfully

---

### Test 3: Session Persistence

1. Navigate to different pages (Users, Products, Sales)
2. Verify you stay logged in
3. Try logging out and logging back in

**Expected**: Sessions work normally

---

### Test 4: Check Error Logs

1. cPanel > File Manager
2. Navigate to `application/logs/`
3. Open latest `log-YYYY-MM-DD.php` file
4. Check for any ERROR entries

**Expected**:
- INFO and DEBUG entries present
- No ERROR entries
- No "session" errors

---

## ❌ IF ERRORS PERSIST

### Problem 1: Still seeing deprecation warnings

**Cause**: Environment not set to 'production'

**Fix**:
1. Verify `.env` file exists with `CI_ENV=production`
2. Or verify `index.php` line 19 changed to `'production'`
3. Clear browser cache (Ctrl+Shift+Del)

---

### Problem 2: "Headers already sent" errors persist

**Cause**: BOM (Byte Order Mark) or whitespace in PHP files

**Fix**:
1. Check `index.php` - no whitespace before `<?php`
2. Check `application/config/config.php` - no whitespace before `<?php`
3. Check `application/core/MY_Controller.php` - no whitespace before `<?php`

**How to fix BOM**:
1. Open file in Notepad++ or VS Code
2. Save as "UTF-8 without BOM"
3. Re-upload to server

---

### Problem 3: Database connection errors

**Cause**: Incorrect database credentials

**Fix**:
1. cPanel > MySQL Databases
2. Verify database name, username, password
3. Update `application/config/database.php`
4. Update `application/config/tenant_databases.php`

---

### Problem 4: Still getting session errors

**Cause**: Session table issues

**Fix**:
1. cPanel > phpMyAdmin
2. Check `ci_sessions` table exists
3. Run this SQL if missing:
```sql
CREATE TABLE IF NOT EXISTS `ci_sessions` (
  `id` varchar(128) NOT NULL,
  `ip_address` varchar(45) NOT NULL,
  `timestamp` int(10) unsigned DEFAULT 0 NOT NULL,
  `data` blob NOT NULL,
  KEY `ci_sessions_timestamp` (`timestamp`)
);
```

---

## 📋 POST-DEPLOYMENT CHECKLIST

- [ ] Uploaded `Session_database_driver.php` to server
- [ ] Set environment to 'production' (.env or index.php)
- [ ] Verified PHP version (8.0 or 8.1 recommended)
- [ ] Configured database credentials for production
- [ ] Set `db_debug` to FALSE in database.php
- [ ] Tested login functionality
- [ ] Tested session persistence across pages
- [ ] Verified no errors displayed to users
- [ ] Checked error logs for issues
- [ ] Tested users create/update operations
- [ ] Tested products create/update operations
- [ ] Tested sales operations
- [ ] Verified invoice prefix shows "INV" not "SL"

---

## 🔐 SECURITY RECOMMENDATIONS FOR PRODUCTION

### 1. Hide Errors from Users
```php
// index.php - Already configured for production mode
ini_set('display_errors', 0); // Errors hidden from users
error_reporting(E_ALL & ~E_NOTICE & ~E_DEPRECATED & ~E_STRICT);
```

### 2. Enable Error Logging Only
```php
// application/config/config.php
$config['log_threshold'] = 2; // Only errors and warnings
// Or keep at 4 for debugging, but review logs regularly
```

### 3. Secure Database Credentials
- Use strong database passwords
- Restrict database user to only necessary privileges
- Use separate database users per tenant if multi-tenant

### 4. File Permissions
**Recommended cPanel Permissions:**
- Directories: 755
- PHP files: 644
- Writable directories: 777 (uploads/, logs/, cache/)

**Set in cPanel File Manager:**
1. Right-click directory/file
2. Change Permissions
3. Set appropriate values

### 5. Disable Directory Listing
Verify `.htaccess` in root contains:
```apache
Options -Indexes
```

### 6. Protect Sensitive Files
Add to `.htaccess`:
```apache
<FilesMatch "(\.htaccess|\.htpasswd|\.env|database\.php|config\.php|tenant_databases\.php)$">
  Order allow,deny
  Deny from all
</FilesMatch>
```

---

## 📞 SUPPORT

If issues persist after following this guide:

1. **Check Error Logs**: `application/logs/log-YYYY-MM-DD.php`
2. **Check PHP Error Log**: cPanel > Errors (if available)
3. **Test Locally First**: Ensure it works on localhost before deploying

---

## 📝 ADDITIONAL NOTES

### Why These Errors Occurred:

1. **Local (XAMPP)**: Uses PHP 7.4 → No deprecation notices
2. **Production (cPanel)**: Uses PHP 8.x → SessionHandlerInterface type hints required
3. **Solution**: Added `#[\ReturnTypeWillChange]` attribute to suppress notices

### Long-term Solution:

Consider upgrading to CodeIgniter 4 which has full PHP 8+ support:
- Native PHP 8 compatibility
- Better performance
- Modern features (namespaces, PSR-4, etc.)
- Active development and security updates

CodeIgniter 3 maintenance ended September 2021. While it still works, CodeIgniter 4 is recommended for new projects and long-term support.

---

**End of Deployment Guide**

**Last Updated**: 2025-11-20
**Applied Fixes**: Session driver PHP 8 compatibility
**Next Steps**: Upload files + set production environment
