# ⚙️ MOLAK v2.0 - Configuration Files Guide

## 📋 Overview

Complete configuration setup for MOLAK v2.0. This guide explains what you need to change in each configuration file.

---

## 📁 Configuration Files

```
config/
├── database.php    # Database connection settings
├── app.php         # Application settings
├── mail.php        # Email configuration
├── stripe.php      # Stripe payment gateway
├── twilio.php      # Twilio SMS service
└── .env.example    # Environment variables template
```

Plus:
```
.gitignore          # Git ignore file (protects sensitive data)
```

---

## 🚀 Quick Start

### Step 1: Copy Environment File

```bash
# Copy .env.example to .env
cp config/.env.example config/.env

# OR rename it
mv config/.env.example config/.env
```

### Step 2: Edit Configuration Files

Open each file and change the marked values (see below).

### Step 3: Test Configuration

```bash
# Open test file in browser
php -S localhost:8000
# Then visit: http://localhost:8000/test_config.php
```

---

## 🔧 What You MUST Change

### 1️⃣ `config/database.php` - Database Configuration

#### ⚠️ MUST CHANGE:

```php
// Line ~45: Database Host
'host' => getenv('DB_HOST') ?: 'localhost',  // ✏️ CHANGE to your database host
// Examples:
// Local: 'localhost' or '127.0.0.1'
// Remote: 'db.example.com' or '192.168.1.100'
// Docker: 'mysql' or container name

// Line ~61: Database Name
'database' => getenv('DB_DATABASE') ?: 'molak_v2',  // ✏️ CHANGE to your database name
// Example: 'molak_production'

// Line ~75: Database Username
'username' => getenv('DB_USERNAME') ?: 'root',  // ✏️ CHANGE in production
// Example: 'molak_user'
// ⚠️ DON'T use 'root' in production!

// Line ~89: Database Password
'password' => getenv('DB_PASSWORD') ?: '',  // ✏️ CHANGE to your password
// Example: 'strong_password_123'
// ⚠️ DON'T leave empty in production!
```

#### ✅ Keep As-Is (Don't Change):

```php
'charset' => 'utf8mb4',        // ✅ Keep for Arabic support
'collation' => 'utf8mb4_unicode_ci',  // ✅ Keep for Arabic sorting
'port' => 3306,                // ✅ Keep unless using custom port
```

---

### 2️⃣ `config/app.php` - Application Configuration

#### ⚠️ MUST CHANGE:

```php
// Line ~24: Application URL
'url' => getenv('APP_URL') ?: 'http://localhost',  // ✏️ CHANGE to your domain
// Development: http://localhost or http://localhost/molak
// Production: https://molak.ae or https://www.molak.ae

// Line ~44: Environment
'env' => getenv('APP_ENV') ?: 'development',  // ✏️ CHANGE to 'production' when live
// Options: 'development', 'staging', 'production'

// Line ~57: Debug Mode
'debug' => getenv('APP_DEBUG') === 'true' ? true : false,  // ✏️ Set to FALSE in production
// Development: true (shows errors)
// Production: false (hides errors for security)

// Line ~256: Contact Email
'email' => getenv('CONTACT_EMAIL') ?: 'support@molak.ae',  // ✏️ CHANGE to your email

// Line ~257: Contact Phone
'phone' => getenv('CONTACT_PHONE') ?: '+971-4-123-4567',  // ✏️ CHANGE to your phone

// Line ~258: Contact Address
'address' => getenv('CONTACT_ADDRESS') ?: 'Dubai, UAE',  // ✏️ CHANGE to your address

// Line ~278: Company Name
'name' => getenv('COMPANY_NAME') ?: 'MOLAK',  // ✏️ CHANGE to your company name

// Line ~279: Company Legal Name
'legal_name' => getenv('COMPANY_LEGAL_NAME') ?: 'MOLAK Property Management LLC',  // ✏️ CHANGE

// Line ~280: Trade License
'trade_license' => getenv('COMPANY_LICENSE') ?: '',  // ✏️ ADD your license number

// Line ~281: Tax Number
'tax_number' => getenv('COMPANY_TAX') ?: '',  // ✏️ ADD your tax/VAT number
```

#### 🔴 CRITICAL - DO NOT CHANGE:

```php
// Line ~84-85: Platform Fee Rates
'maintenance_fee_rate' => 30.0,        // 🔴 DON'T CHANGE - 30% from provider
'online_payment_fee_rate' => 3.1,     // 🔴 DON'T CHANGE - 3.1% from owner
// ⚠️ These are core business logic - only change with management authorization
```

#### ✅ Optional Changes:

```php
'timezone' => 'Asia/Dubai',         // ✏️ Change if not in UAE
'default_language' => 'ar',         // ✏️ Change to 'en' if needed
'currency' => 'AED',                // ✏️ Change if not using AED
```

---

### 3️⃣ `config/mail.php` - Email Configuration

#### ⚠️ MUST CHANGE:

```php
// Line ~48: SMTP Host
'host' => getenv('MAIL_HOST') ?: 'smtp.gmail.com',  // ✏️ CHANGE to your SMTP server
// Common options:
// Gmail: smtp.gmail.com
// Outlook: smtp.office365.com
// Yahoo: smtp.mail.yahoo.com
// SendGrid: smtp.sendgrid.net
// Custom: mail.yourdomain.com

// Line ~63: SMTP Port
'port' => getenv('MAIL_PORT') ?: 587,  // ✏️ CHANGE if needed
// 587 = TLS (recommended)
// 465 = SSL
// 2525 = Alternative (SendGrid, Mailgun)

// Line ~80: SMTP Username
'username' => getenv('MAIL_USERNAME') ?: 'your-email@gmail.com',  // ✏️ CHANGE to your email
// Example: support@molak.ae

// Line ~95: SMTP Password
'password' => getenv('MAIL_PASSWORD') ?: 'your-app-password',  // ✏️ CHANGE to your password
// For Gmail:
// 1. Enable 2FA: https://myaccount.google.com/security
// 2. Generate App Password: https://myaccount.google.com/apppasswords
// 3. Use the 16-character app password here

// Line ~116: From Email Address
'address' => getenv('MAIL_FROM_ADDRESS') ?: 'noreply@molak.ae',  // ✏️ CHANGE to your domain
// Example: noreply@yourdomain.com

// Line ~117: From Name
'name' => getenv('MAIL_FROM_NAME') ?: 'MOLAK',  // ✏️ CHANGE to your name

// Line ~128: Reply-To Address
'address' => getenv('MAIL_REPLY_TO_ADDRESS') ?: 'support@molak.ae',  // ✏️ CHANGE
```

#### 📧 Gmail Setup Instructions:

1. **Enable 2-Factor Authentication:**
   - Go to: https://myaccount.google.com/security
   - Enable 2-Step Verification

2. **Generate App Password:**
   - Go to: https://myaccount.google.com/apppasswords
   - Select "Mail" and your device
   - Copy the 16-character password

3. **Use in config:**
   ```php
   'username' => 'your-email@gmail.com',
   'password' => 'abcd efgh ijkl mnop',  // The 16-char app password
   ```

---

### 4️⃣ `config/stripe.php` - Stripe Payment Gateway

#### ⚠️ MUST CHANGE:

```php
// Line ~26: Stripe Mode
'mode' => getenv('STRIPE_MODE') ?: 'test',  // ✏️ CHANGE to 'live' in production
// test = Testing (no real charges)
// live = Production (real money)

// Line ~42: Stripe Public Key
'public_key' => getenv('STRIPE_PUBLIC_KEY') ?: 'pk_test_YOUR_KEY',  // ✏️ CHANGE
// Get from: https://dashboard.stripe.com/apikeys
// Test: pk_test_...
// Live: pk_live_...

// Line ~55: Stripe Secret Key
'secret_key' => getenv('STRIPE_SECRET_KEY') ?: 'sk_test_YOUR_KEY',  // ✏️ CHANGE
// ⚠️ CRITICAL: Keep this secret!
// Test: sk_test_...
// Live: sk_live_...

// Line ~68: Webhook Secret
'webhook_secret' => getenv('STRIPE_WEBHOOK_SECRET') ?: 'whsec_YOUR_SECRET',  // ✏️ CHANGE
// Get from: https://dashboard.stripe.com/webhooks
// Format: whsec_...

// Line ~125: Statement Descriptor
'statement_descriptor' => 'MOLAK PROPERTY',  // ✏️ CHANGE (max 22 chars)
// This appears on customer's bank statement
```

#### 🔴 CRITICAL - DO NOT CHANGE:

```php
// Line ~102: Platform Fee Rate
'platform_fee_rate' => 3.1,  // 🔴 DON'T CHANGE - 3.1% online payment fee
// This is the fee charged from owners when online payment is enabled
```

#### 📝 Stripe Setup Instructions:

1. **Create Stripe Account:**
   - Go to: https://dashboard.stripe.com/register
   - Verify your email and business

2. **Get API Keys:**
   - Development: https://dashboard.stripe.com/test/apikeys
   - Production: https://dashboard.stripe.com/apikeys
   - Copy: Publishable key (pk_...) and Secret key (sk_...)

3. **Setup Webhooks:**
   - Go to: https://dashboard.stripe.com/webhooks
   - Add endpoint: https://yourdomain.com/webhooks/stripe/payment-intent
   - Copy webhook secret (whsec_...)

---

### 5️⃣ `config/twilio.php` - Twilio SMS Service

#### ⚠️ MUST CHANGE (when ready to use SMS):

```php
// Line ~24: Enable Twilio
'enabled' => getenv('TWILIO_ENABLED') === 'true' ? true : false,  // ✏️ Set to true
// false = Disabled (default)
// true = Enabled (when ready)

// Line ~38: Account SID
'account_sid' => 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',  // ✏️ CHANGE
// Get from: https://console.twilio.com/
// Format: ACxxxx...

// Line ~50: Auth Token
'auth_token' => 'your_auth_token_here',  // ✏️ CHANGE
// ⚠️ CRITICAL: Keep this secret!
// Get from: https://console.twilio.com/

// Line ~64: From Phone Number
'from_number' => '+15551234567',  // ✏️ CHANGE to your Twilio number
// Format: E.164 (+[country code][number])
// Example: +971501234567 (UAE)
```

#### 📱 Twilio Setup Instructions:

1. **Create Twilio Account:**
   - Go to: https://www.twilio.com/try-twilio
   - Sign up and verify your email

2. **Get Credentials:**
   - Dashboard: https://console.twilio.com/
   - Copy: Account SID and Auth Token

3. **Get Phone Number:**
   - Go to: https://console.twilio.com/phone-numbers
   - Buy a phone number (or use trial number)

4. **Enable (when ready):**
   ```php
   'enabled' => true,
   ```

---

## 🔒 Security Checklist

### ✅ Before Going Live:

- [ ] Change `APP_ENV` to `'production'`
- [ ] Set `APP_DEBUG` to `false`
- [ ] Use strong database password
- [ ] Don't use database username `'root'`
- [ ] Use HTTPS (secure connection)
- [ ] Set up real Stripe live keys
- [ ] Set up real email credentials
- [ ] Change all default contact information
- [ ] Enable Twilio (if using SMS)
- [ ] Test all configurations
- [ ] Verify `.gitignore` is working

### ⚠️ Never Commit to Git:

```
❌ config/database.php
❌ config/app.php (with real data)
❌ config/mail.php (with real credentials)
❌ config/stripe.php (with real keys)
❌ config/twilio.php (with real credentials)
❌ config/.env
❌ .env

✅ config/.env.example (OK to commit)
✅ .gitignore (OK to commit)
```

The `.gitignore` file is configured to protect these files automatically.

---

## 📊 Fee Rates Reference

### 🔴 CRITICAL - Platform Revenue

#### 1. Maintenance Fee = **30%**
```
Source: Service Provider
When: ALWAYS (every maintenance work order)
Example:
  Work Order Total: 1,000 AED
  Platform Fee (30%): 300 AED → MOLAK
  Provider Receives: 700 AED
```

#### 2. Online Payment Fee = **3.1%**
```
Source: Property Owner
When: OPTIONAL (only if owner enables online payment)
Example (Enabled):
  Tenant Pays: 5,000 AED
  Platform Fee (3.1%): 155 AED → MOLAK
  Owner Receives: 4,845 AED

Example (Disabled):
  Tenant Pays: 5,000 AED (bank transfer/cash)
  Platform Fee: 0 AED
  Owner Receives: 5,000 AED (full amount)
```

**⚠️ DO NOT CHANGE these rates without management authorization!**

---

## 🧪 Testing Configuration

### Run Test File:

```bash
# Start PHP server
php -S localhost:8000

# Open in browser
http://localhost:8000/test_config.php
```

The test file will show:
- ✅ Which files exist
- ⚠️ Which values need to be changed
- ❌ Which configurations are incorrect
- 📋 Summary of all settings

---

## 🌍 Environment Variables

Instead of editing config files directly, you can use environment variables:

### Create `.env` file:

```bash
cp config/.env.example config/.env
```

### Edit `.env`:

```env
# Database
DB_HOST=localhost
DB_DATABASE=molak_v2
DB_USERNAME=root
DB_PASSWORD=

# Application
APP_URL=http://localhost
APP_ENV=development
APP_DEBUG=true

# Email
MAIL_HOST=smtp.gmail.com
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password

# Stripe
STRIPE_MODE=test
STRIPE_PUBLIC_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...

# Twilio
TWILIO_ENABLED=false
TWILIO_ACCOUNT_SID=ACxxxx...
TWILIO_AUTH_TOKEN=...
```

Environment variables take precedence over hardcoded values.

---

## 📝 Common Issues & Solutions

### Issue 1: Database Connection Failed

**Solution:**
```php
// Check in database.php:
'host' => 'localhost',     // ✅ Correct host?
'database' => 'molak_v2',  // ✅ Database exists?
'username' => 'root',      // ✅ Correct username?
'password' => '',          // ✅ Correct password?
```

### Issue 2: Emails Not Sending

**Solution:**
```php
// For Gmail, use App Password:
1. Enable 2FA
2. Generate App Password: https://myaccount.google.com/apppasswords
3. Use 16-character password in config

// Check:
'host' => 'smtp.gmail.com',  // ✅ Correct host?
'port' => 587,               // ✅ Correct port?
'encryption' => 'tls',       // ✅ TLS for port 587
```

### Issue 3: Stripe Payments Not Working

**Solution:**
```php
// Check mode:
'mode' => 'test',  // ✅ Use 'test' in development

// Check keys match mode:
Test mode: pk_test_... and sk_test_...
Live mode: pk_live_... and sk_live_...

// In browser console, check for errors
```

### Issue 4: SMS Not Sending

**Solution:**
```php
// Check if enabled:
'enabled' => true,  // ✅ Must be true

// Check credentials:
'account_sid' => 'ACxxxx...',  // ✅ Starts with AC?
'from_number' => '+971...',    // ✅ E.164 format?

// Check phone number format:
+971501234567 ✅ Correct
971501234567  ❌ Missing +
501234567     ❌ Missing country code
```

---

## 📚 Additional Resources

### Official Documentation:

- **Stripe:** https://stripe.com/docs
- **Twilio:** https://www.twilio.com/docs
- **Gmail SMTP:** https://support.google.com/mail/answer/7126229
- **PHP Environment:** https://www.php.net/manual/en/function.getenv.php

### MOLAK Documentation:

- Database Schema: See `DATABASE_README.md`
- Includes/Functions: See `INCLUDES_README.md`
- API Documentation: (Coming in Phase 2)

---

## ✅ Configuration Checklist

```
☐ 1. Copy .env.example to .env
☐ 2. Edit config/database.php
   ☐ Database host
   ☐ Database name
   ☐ Database username
   ☐ Database password
☐ 3. Edit config/app.php
   ☐ Application URL
   ☐ Environment (production)
   ☐ Debug mode (false in production)
   ☐ Contact information
   ☐ Company information
☐ 4. Edit config/mail.php
   ☐ SMTP host
   ☐ SMTP username
   ☐ SMTP password (app password)
   ☐ From address
   ☐ Reply-to address
☐ 5. Edit config/stripe.php
   ☐ Stripe mode (live in production)
   ☐ Public key
   ☐ Secret key
   ☐ Webhook secret
☐ 6. Edit config/twilio.php (if using SMS)
   ☐ Enable Twilio
   ☐ Account SID
   ☐ Auth token
   ☐ From phone number
☐ 7. Test all configurations
☐ 8. Verify .gitignore is working
☐ 9. Deploy to production
☐ 10. Monitor logs for errors
```

---

## 🆘 Need Help?

If you encounter issues:

1. Run `test_config.php` to diagnose problems
2. Check error logs in `/logs/` directory
3. Verify all values are correct
4. Make sure database exists and is accessible
5. Test email/SMS services independently first

---

**✅ Section 1.3 Complete!**

Once you've configured everything, proceed to **Section 1.4: Database Setup**

---

**Last Updated:** 2024-11-07  
**Version:** 2.0  
**Status:** ✅ Complete