Configuration Guide

Complete guide to configuring the OpenCart Migration Tool.

Configuration File
Application Settings
1. Basic Configuration
  1. Debug Mode
Database Configuration
Migration Settings
1. Performance Configuration
  1. Batch Size Recommendations
  2. Memory Limits
Image Configuration
Store Configuration
1. OpenCart 4 Settings
Extension Configuration
1. Extension Management
2. Marketplace Integration
Logging Configuration
Environment-Specific Configuration
Security Configuration
1. Database Security
2. Environment Variables
Advanced Configuration
1. Custom Table Prefix
2. Multi-Database Setup
Configuration Best Practices
Validation
1. Test Configuration
2. Common Validation Errors
Troubleshooting
1. Configuration Issues
2. Getting Help
Next Steps

Configuration File

The main configuration file is located at: config/config.php

Copy from example template:

cp config/config.example.php config/config.php

Application Settings

Basic Configuration

'app' => [
    'name' => 'OpenCart Migration Tool',
    'url' => 'http://your-domain.com/',  // Your tool URL
    'version' => '1.0.0',
    'debug' => false,  // Enable only in development
    'timezone' => 'UTC',  // PHP timezone
    'locale' => 'en',  // Application locale
],

Debug Mode

Never enable debug mode in production! It exposes sensitive information.

Development:

'debug' => true,  // Shows detailed errors

Production:

'debug' => false,  // Logs errors, shows generic messages

Database Configuration

SQLite (Tracking Database)

Used for migration progress tracking:

'sqlite' => [
    'driver' => 'sqlite',
    'database' => storage_path('migration_tracking.sqlite'),
],

Default location: storage/migration_tracking.sqlite

Source Database (OpenCart 3)

'source' => [
    'driver' => 'mysql',
    'host' => 'localhost',  // Database host
    'port' => '3306',  // MySQL port
    'database' => 'opencart3_db',  // OC3 database name
    'username' => 'db_user',  // Database username
    'password' => 'db_password',  // Database password
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'table_prefix' => 'oc_'  // Usually 'oc_'
],

Remote Database

If OC3 is on a different server:

'source' => [
    'host' => '192.168.1.100',  // Remote IP
    'port' => '3306',
    'database' => 'opencart3_db',
    'username' => 'remote_user',
    'password' => 'remote_password',
],

Remote connections are slower. Use local databases when possible.

Target Database (OpenCart 4)

'target' => [
    'driver' => 'mysql',
    'host' => 'localhost',
    'port' => '3306',
    'database' => 'opencart4_db',  // OC4 database name
    'username' => 'db_user',
    'password' => 'db_password',
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'table_prefix' => 'oc_'
],

OpenCart 4 must have default data installed. Complete the OC4 installation wizard first.

Migration Settings

Performance Configuration

'migration' => [
    'default_batch_size' => 1000,  // Records per batch
    'memory_limit' => '512M',  // PHP memory limit
    'time_limit' => 3600,  // Max execution time (seconds)
],

Batch Size Recommendations

Dataset Size	Recommended Batch Size
< 10K records	1000 - 2000
10K - 50K	500 - 1000
50K - 100K	100 - 500
> 100K	50 - 100

Lower batch size = Less memory but slower Higher batch size = More memory but faster

Memory Limits

Store Size	Recommended Memory
Small (< 5K products)	256M
Medium (5K - 25K)	512M
Large (25K - 100K)	1G
Very Large (> 100K)	2G

Image Configuration

Basic Setup

'images' => [
    'enabled' => true,  // Enable image transfer
    'source_path' => '/absolute/path/to/opencart3/image',
    'target_path' => '/absolute/path/to/opencart4/image',
    'validation' => true,  // Validate after transfer
],

Paths must be absolute, not relative!

Path Examples

Linux:

'source_path' => '/var/www/opencart3/image',
'target_path' => '/var/www/opencart4/image',

Windows:

'source_path' => 'C:/xampp/htdocs/opencart3/image',
'target_path' => 'C:/xampp/htdocs/opencart4/image',

Docker:

'source_path' => '/app/opencart3/image',
'target_path' => '/app/opencart4/image',

Advanced Image Settings

'images' => [
    'enabled' => true,
    'source_path' => '/path/to/oc3/image',
    'target_path' => '/path/to/oc4/image',
    'validation' => true,

    // Optional: Advanced settings
    'skip_existing' => false,  // Skip if file exists in target
    'verify_size' => true,  // Verify file size matches
    'preserve_timestamps' => true,  // Keep original file dates
    'create_thumbnails' => false,  // Generate thumbnails (future)
],

Store Configuration

OpenCart 4 Settings

'store' => [
    'target_url' => 'http://your-oc4-store.com/',
],

'opencart4' => [
    'base_url' => 'http://your-oc4-store.com/',
    'admin_url' => 'http://your-oc4-store.com/admin',
    'path' => '/absolute/path/to/opencart4',
],

Extension Configuration

Extension Management

'extensions' => [
    'auto_install' => false,  // Enable automated installation
    'backup_settings' => true,  // Backup before migration
    'validate_after_migration' => true,  // Validate after

    'marketplace' => [
        'api_key' => '',  // OpenCart API key (optional)
        'auto_search' => true,  // Search marketplace automatically
    ]
],

Marketplace Integration

'marketplace' => [
    'opencart_base_url' => 'https://www.opencart.com/index.php?route=marketplace/extension',
    'search_params' => [
        'filter_search' => '',  // Populated dynamically
        'filter_version' => '4.x',
    ]
],

Logging Configuration

Basic Logging

'logging' => [
    'default' => 'file',  // Default channel
    'enabled' => true,  // Enable logging
    'level' => 'INFO',  // DEBUG, INFO, WARNING, ERROR
    'path' => 'logs/',  // Log directory
    'date_format' => 'Y-m-d H:i:s',
    'max_file_size' => '10MB',  // For future rotation
],

Log Levels

Level	When to Use	What Gets Logged
DEBUG	Development only	Everything including debug info
INFO	Development/Staging	General information, progress
WARNING	Production	Warnings and above
ERROR	Production (minimal)	Only errors

Log Channels

'channels' => [
    'file' => [
        'driver' => 'file',
        'path' => 'logs/migration.log',
        'level' => 'debug',
    ],
    'database' => [
        'driver' => 'sqlite',
        'table' => 'migration_logs'
    ]
],

Environment-Specific Configuration

Development Environment

return [
    'app' => [
        'debug' => true,
        'url' => 'http://localhost:8000/',
    ],
    'logging' => [
        'level' => 'DEBUG',
    ],
    'migration' => [
        'default_batch_size' => 100,  // Small batches for testing
    ],
];

Staging Environment

return [
    'app' => [
        'debug' => false,
        'url' => 'https://staging.example.com/',
    ],
    'logging' => [
        'level' => 'INFO',
    ],
    'migration' => [
        'default_batch_size' => 500,
    ],
];

Production Environment

return [
    'app' => [
        'debug' => false,  // NEVER true in production
        'url' => 'https://migration.example.com/',
    ],
    'logging' => [
        'level' => 'WARNING',  // Only warnings and errors
    ],
    'migration' => [
        'default_batch_size' => 1000,
        'memory_limit' => '1G',
    ],
];

Security Configuration

Database Security

// Use dedicated users with minimal privileges
'source' => [
    'username' => 'migration_readonly',  // Read-only for source
    'password' => env('SOURCE_DB_PASSWORD'),  // From environment
],
'target' => [
    'username' => 'migration_writer',  // Write access for target
    'password' => env('TARGET_DB_PASSWORD'),
],

Environment Variables

Create .env file (not committed to git):

# .env
SOURCE_DB_PASSWORD=secure_password_here
TARGET_DB_PASSWORD=another_secure_password
APP_URL=https://your-domain.com

Load in config:

'password' => getenv('SOURCE_DB_PASSWORD'),

Advanced Configuration

Custom Table Prefix

If your OpenCart uses custom prefixes:

'database' => [
    'source' => [
        'table_prefix' => 'custom_prefix_',  // e.g., 'shop_'
    ],
    'target' => [
        'table_prefix' => 'oc_',  // Standard prefix
    ]
],

Multi-Database Setup

If source/target on different MySQL servers:

'source' => [
    'host' => 'mysql-oc3.example.com',
    'port' => '3306',
    // ... other settings
],
'target' => [
    'host' => 'mysql-oc4.example.com',
    'port' => '3307',  // Different port
    // ... other settings
],

Configuration Best Practices

Security

✅ Never commit config.php to git
✅ Use environment variables for credentials
✅ Set restrictive file permissions (400)
✅ Disable debug in production
✅ Use strong database passwords

Performance

✅ Use local databases when possible
✅ Adjust batch size based on available memory
✅ Increase time limits for large datasets
✅ Enable PHP OPcache in production
✅ Use SSD storage for databases

Reliability

✅ Test configuration in staging first
✅ Backup databases before migration
✅ Enable detailed logging for first migration
✅ Monitor system resources during migration
✅ Keep source database read-only during migration

Validation

Test Configuration

# Verify configuration syntax
php -l config/config.php

# Test database connections
php migrate.php test-connections

# Validate paths
php migrate.php validate-paths

Common Validation Errors

“Database connection failed”

Check credentials
Verify MySQL is running
Test connection with mysql command

“Image path not found”

Use absolute paths
Check directory exists
Verify read/write permissions

“Permission denied”

Check file permissions
Verify web server user has access
Use chmod and chown to fix

Troubleshooting

Configuration Issues

Issue	Solution
Syntax error	Check for missing commas, quotes
Connection failed	Verify database credentials
Permission denied	Fix file/directory permissions
Path not found	Use absolute paths
Memory exhausted	Increase memory_limit

Getting Help

Next Steps

✅ Configuration complete
Review Features Documentation
Start migration with Installation Guide
Monitor progress in dashboard
Validate results after migration