# Ngauge SQL Backup Plugin - Composer Integration Guide

## Overview

The **portalpeople/ngauge-backup-sql** plugin is fully configured for automatic bootstrap via Composer. Once installed, it automatically registers itself in both Console and Backend/Web applications without requiring manual configuration.

---

## ✅ Automatic Bootstrap Configuration

### How It Works

The plugin uses Yii2's composer plugin integration to automatically bootstrap itself:

1. **composer.json declares bootstrap class**
   ```json
   "extra": {
       "bootstrap": "PortalPeople\\NgaugeBackupSql\\Module"
   }
   ```

2. **Yii2 Composer Plugin discovers and executes bootstrap**
   - Reads `extra.bootstrap` from installed packages
   - Instantiates the Module class
   - Calls `bootstrap()` method on application

3. **Module auto-registers console command**
   - Registers `db-backup` command with console app
   - Registers `db-backup` module with web app
   - No manual module registration needed

---

## 📦 Files Involved

### Main Application Composer
**File:** `composer.json`

Already configured with:
```json
{
    "repositories": [
        {
            "type": "path",
            "url": "vendor/portalpeople/ngauge-backup-sql"
        }
    ],
    "require": {
        "portalpeople/ngauge-backup-sql": "dev-main"
    },
    "extra": {
        "yii-install-all": 1
    },
    "config": {
        "allow-plugins": {
            "yiisoft/yii2-composer": true
        }
    }
}
```

### Plugin Composer
**File:** `vendor/portalpeople/ngauge-backup-sql/composer.json`

```json
{
    "name": "portalpeople/ngauge-backup-sql",
    "type": "yii2-extension",
    "autoload": {
        "psr-4": {
            "PortalPeople\\NgaugeBackupSql\\": "src/"
        },
        "files": ["src/bootstrap.php"]
    },
    "extra": {
        "bootstrap": "PortalPeople\\NgaugeBackupSql\\Module"
    }
}
```

### Plugin Bootstrap File
**File:** `vendor/portalpeople/ngauge-backup-sql/src/bootstrap.php`

Automatically loaded by Composer during app initialization. Handles:
- Detecting application type (Console vs Web)
- Loading appropriate configuration
- Registering module dynamically

### Configuration Files
**Files:**
- `vendor/portalpeople/ngauge-backup-sql/src/config/console.php`
- `vendor/portalpeople/ngauge-backup-sql/src/config/web.php`

Provide default configuration for each application type.

---

## 🔧 Default Configuration

### Console Configuration
**Location:** `vendor/portalpeople/ngauge-backup-sql/src/config/console.php`

```php
return [
    'bootstrap' => ['db-backup'],
    'modules' => [
        'db-backup' => [
            'class' => 'PortalPeople\NgaugeBackupSql\Module',
            'backupPath' => '@backups/sql',
            'retentionDays' => 30,
            'compressBackups' => true,
            'excludeTables' => ['log', 'queue', 'session'],
            'dbComponent' => 'db',
        ],
    ],
];
```

### Web Configuration
**Location:** `vendor/portalpeople/ngauge-backup-sql/src/config/web.php`

```php
return [
    'modules' => [
        'db-backup' => [
            'class' => 'PortalPeople\NgaugeBackupSql\Module',
            'backupPath' => '@backups/sql',
            'retentionDays' => 30,
            'compressBackups' => true,
            'excludeTables' => ['log', 'queue', 'session'],
            'dbComponent' => 'db',
        ],
    ],
];
```

---

## 🚀 Installation Steps

### Step 1: Update Main Application Composer
The plugin is already added to `composer.json` with:

```json
{
    "repositories": [
        {
            "type": "path",
            "url": "vendor/portalpeople/ngauge-backup-sql"
        }
    ],
    "require": {
        "portalpeople/ngauge-backup-sql": "dev-main"
    }
}
```

### Step 2: Install via Composer
```bash
cd /var/www/vhosts/sb.ion-club.net/surf.sb.ion-club.net
composer update portalpeople/ngauge-backup-sql
```

### Step 3: Verify Bootstrap
Check that the module auto-registered:

```bash
# Console app
php yii db-backup

# Should show menu with available commands
```

### Step 4: Run Migration (Optional)
To enable backup history tracking:

```bash
php yii migrate --migrationPath=@PortalPeople/NgaugeBackupSql/migrations
```

---

## ✨ What Gets Automatically Configured

### ✅ Console Application
- ✓ `db-backup` command registered
- ✓ Module instantiated with default config
- ✓ Bootstrap method called automatically
- ✓ No manual config file changes needed

### ✅ Backend/Frontend Web Applications
- ✓ `db-backup` module registered
- ✓ Web UI accessible at `/db-backup`
- ✓ Controllers and views available
- ✓ No manual config file changes needed

### ✅ Shared Features
- ✓ Database connection using app's `db` component
- ✓ Backup directory created automatically
- ✓ All routes and URL rules configured
- ✓ Permissions and access control set

---

## 🔧 Customizing Configuration

### Option A: Override via Application Config (Recommended)

You can still override the plugin's default configuration in your application config files:

**File:** `console/config/main.php`
```php
return [
    'modules' => [
        'db-backup' => [
            'class' => 'PortalPeople\NgaugeBackupSql\Module',
            'backupPath' => '@backups/custom-path',  // Custom backup path
            'retentionDays' => 90,                    // Keep for 90 days
            'compressBackups' => true,
            'excludeTables' => ['log', 'queue'],
        ],
    ],
];
```

**File:** `backend/config/main.php`
```php
return [
    'modules' => [
        'db-backup' => [
            'class' => 'PortalPeople\NgaugeBackupSql\Module',
            'backupPath' => '@app-backups',
            'retentionDays' => 60,
        ],
    ],
];
```

### Option B: Modify Plugin Config Files

Edit the plugin's config files directly:
- `vendor/portalpeople/ngauge-backup-sql/src/config/console.php`
- `vendor/portalpeople/ngauge-backup-sql/src/config/web.php`

⚠️ **Not recommended** - will be overwritten on package update

---

## 🎯 Bootstrap Mechanism Details

### Execution Flow

```
1. Composer Install
   └─> Installs plugin to vendor/portalpeople/ngauge-backup-sql/
   └─> Registers PSR-4 autoloader for PortalPeople\NgaugeBackupSql\
   └─> Marks bootstrap entry from composer.json
   
2. Application Bootstrap
   └─> Yii2 reads extra.bootstrap entries from all packages
   └─> Finds "PortalPeople\NgaugeBackupSql\Module"
   └─> Includes src/bootstrap.php (via autoload.files)
   └─> Instantiates Module class
   
3. Module Initialization
   └─> Module::__construct() called
   └─> Module::init() called
       ├─> Creates backup directory
       └─> Sets up aliases
   
4. Bootstrap Method
   └─> Module::bootstrap($app) called
   ├─> Console App:
   │   └─> Registers db-backup console command
   │   └─> Sets up command controller
   │
   └─> Web App:
       └─> Registers db-backup module
       └─> Sets up routes and controllers

5. Application Ready
   └─> Module fully functional
   └─> All features available
```

---

## 🔒 How Automatic Bootstrap Works

### 1. Composer Plugin Detection
```json
{
    "extra": {
        "bootstrap": "PortalPeople\\NgaugeBackupSql\\Module"
    }
}
```

Yii2's `yiisoft/yii2-composer` plugin reads this entry and registers it for bootstrapping.

### 2. Bootstrap File Auto-Load
```json
{
    "autoload": {
        "files": ["src/bootstrap.php"]
    }
}
```

The bootstrap.php file is automatically included during composer autoload initialization.

### 3. Module Bootstrap Interface
```php
class Module extends \yii\base\Module implements BootstrapInterface
{
    public function bootstrap($app)
    {
        // Auto-register console command or module
        // based on application type
    }
}
```

Implements `BootstrapInterface` so Yii2 calls the bootstrap method.

---

## 📋 Verification Checklist

After installation, verify the plugin is properly bootstrapped:

- [ ] Plugin installed in `vendor/portalpeople/ngauge-backup-sql/`
- [ ] Autoloader includes plugin classes: `php -r "var_dump(class_exists('PortalPeople\NgaugeBackupSql\Module'));"`
- [ ] Console command available: `php yii db-backup`
- [ ] Web module accessible: `curl http://localhost/db-backup`
- [ ] Backup directory exists: `/backups/sql/` with 755 permissions
- [ ] Can create backup: `php yii db-backup/create --table=users`
- [ ] Can list backups: `php yii db-backup/list`
- [ ] History table created (after migration): `php yii migrate`

---

## 🚨 Troubleshooting Bootstrap

### Issue: Command Not Found: `db-backup`

**Solution:**
```bash
# Clear Composer cache
composer clear-cache

# Regenerate autoload
composer dump-autoload -o

# Test again
php yii db-backup
```

### Issue: Module Not Registering

**Check:**
1. Plugin installed: `ls vendor/portalpeople/ngauge-backup-sql/`
2. Composer.json has bootstrap entry
3. Yii2 composer plugin enabled: `grep yii2-composer composer.json`

**Fix:**
```bash
composer update portalpeople/ngauge-backup-sql --no-scripts
```

### Issue: Web UI Not Accessible

**Check:**
1. Backend app loads plugin: `php yii list` (should show db-backup)
2. Database component works: `php yii migrate`
3. Backup directory exists: `ls -la backups/sql/`

**Fix:**
```php
// In backend/config/main.php, ensure module registration:
'modules' => [
    'db-backup' => [
        'class' => 'PortalPeople\NgaugeBackupSql\Module',
    ],
],
```

---

## 📚 Additional Documentation

- **README.md** - Full feature documentation
- **QUICKSTART.md** - Quick start guide
- **NGAUGE-BACKUP-SQL-IMPLEMENTATION.md** - Implementation details

---

## 🎓 Composer Configuration Summary

### Minimum Required (Already Done)

**composer.json**
```json
{
    "repositories": [{
        "type": "path",
        "url": "vendor/portalpeople/ngauge-backup-sql"
    }],
    "require": {
        "portalpeople/ngauge-backup-sql": "dev-main"
    },
    "config": {
        "allow-plugins": {
            "yiisoft/yii2-composer": true
        }
    }
}
```

### Plugin Composer (Built-in)
```json
{
    "type": "yii2-extension",
    "autoload": {
        "psr-4": {"PortalPeople\\NgaugeBackupSql\\": "src/"},
        "files": ["src/bootstrap.php"]
    },
    "extra": {
        "bootstrap": "PortalPeople\\NgaugeBackupSql\\Module"
    }
}
```

### Result
✅ **Automatic bootstrap in both Console and Web applications**
✅ **No manual module registration required**
✅ **Default configuration loaded automatically**
✅ **Full plugin functionality immediately available**

---

**Status:** ✅ Ready for automatic bootstrap  
**Installation Date:** February 10, 2026  
**Configuration:** Complete
