Quick Reference Guide
Quick commands and configurations for common tasks.
Table of contents
- Installation Quick Start
- Configuration Snippets
- Common Commands
- Migration Steps Order
- Troubleshooting Quick Fixes
- API Endpoints
- Validation Commands
- File Locations
- Docker Quick Start
- Useful SQL Queries
- Performance Optimization
- Security Checklist
- Backup Strategy
- Common Patterns
- Getting Help
- Version Information
Installation Quick Start
# Clone repository
git clone https://github.com/kunwar-shah/opencart-migration-tool.git
cd opencart-migration-tool
# Configure
cp config/config.example.php config/config.php
nano config/config.php
# Install via web
# Navigate to: http://your-domain.com/install.php
Configuration Snippets
Database Connection
'database' => [
'source' => [
'host' => 'localhost',
'database' => 'opencart3_db',
'username' => 'db_user',
'password' => 'db_password',
'table_prefix' => 'oc_'
],
'target' => [
'host' => 'localhost',
'database' => 'opencart4_db',
'username' => 'db_user',
'password' => 'db_password',
'table_prefix' => 'oc_'
]
],
Image Paths
// Linux
'images' => [
'source_path' => '/var/www/opencart3/image',
'target_path' => '/var/www/opencart4/image',
],
// Windows
'images' => [
'source_path' => 'C:/xampp/htdocs/opencart3/image',
'target_path' => 'C:/xampp/htdocs/opencart4/image',
],
Performance Tuning
// Small stores (< 5K products)
'migration' => [
'default_batch_size' => 1000,
'memory_limit' => '256M',
],
// Large stores (> 50K products)
'migration' => [
'default_batch_size' => 500,
'memory_limit' => '1G',
],
Common Commands
Database Backup
# Backup OpenCart 3
mysqldump -u root -p opencart3_db > oc3_backup.sql
# Backup OpenCart 4
mysqldump -u root -p opencart4_db > oc4_backup.sql
# Backup with compression
mysqldump -u root -p opencart3_db | gzip > oc3_backup.sql.gz
Database Restore
# Restore from backup
mysql -u root -p opencart4_db < oc4_backup.sql
# Restore from compressed backup
gunzip < oc4_backup.sql.gz | mysql -u root -p opencart4_db
Permissions
# Linux/Unix
sudo chown -R www-data:www-data /path/to/migration-tool
sudo chmod -R 755 storage/ logs/
sudo chmod 400 config/config.php
# Check permissions
ls -la config/config.php
ls -la storage/
Migration Steps Order
- Default Data - Required first step
- Categories - Product categories
- Manufacturers - Product manufacturers
- Attributes - Product attributes
- Filters - Product filters
- Infrastructure - Banners, reviews, etc.
- Admin Users - Admin accounts
- Products - Main product data
- Customers - Customer accounts
- Orders - Order history
- Other Data - Downloads, vouchers
Troubleshooting Quick Fixes
Connection Failed
# Test MySQL connection
mysql -u username -p -h localhost database_name
# Check MySQL status
sudo systemctl status mysql
sudo systemctl start mysql
Permission Denied
# Fix ownership
sudo chown -R www-data:www-data /path/to/tool
# Fix permissions
sudo chmod 755 storage/ logs/
sudo chmod 666 config/config.php
Out of Memory
// Increase in config
'memory_limit' => '1G',
'default_batch_size' => 500,
; In php.ini
memory_limit = 1G
Timeout Errors
// In config
'time_limit' => 7200,
# Apache
Timeout 7200
# Nginx
proxy_read_timeout 7200s;
fastcgi_read_timeout 7200s;
API Endpoints
Authentication
POST /login
Content-Type: application/json
{
"username": "admin",
"password": "password"
}
Start Migration
POST /api/migrate/products
Content-Type: application/json
{
"batch_size": 1000,
"skip_validation": false
}
Check Progress
GET /api/migrate/products/progress
Get All Steps
GET /api/steps
Validation Commands
Check Record Counts
-- Source (OC3)
SELECT COUNT(*) FROM oc_product;
SELECT COUNT(*) FROM oc_order;
SELECT COUNT(*) FROM oc_customer;
-- Target (OC4)
SELECT COUNT(*) FROM oc_product;
SELECT COUNT(*) FROM oc_order;
SELECT COUNT(*) FROM oc_customer;
Verify ID Mappings
-- Check mapping table
SELECT * FROM id_mappings WHERE old_table = 'product' LIMIT 10;
-- Count mappings
SELECT old_table, COUNT(*) as count
FROM id_mappings
GROUP BY old_table;
File Locations
Important Files
config/config.php # Main configuration
logs/migration.log # Migration logs
storage/migration_tracking.sqlite # Progress database
database/init.php # Database schema
src/Controllers/ # Controllers
src/Migration/Steps/ # Migration steps
src/Services/ # Services
src/Utils/ # Table definitions
Log Files
# View logs in real-time
tail -f logs/migration.log
# Search for errors
grep "ERROR" logs/migration.log
# View last 100 lines
tail -n 100 logs/migration.log
Docker Quick Start
# docker-compose.yml
version: '3.8'
services:
migration-tool:
build: .
ports:
- "8080:80"
volumes:
- ./:/var/www/html
environment:
- PHP_MEMORY_LIMIT=512M
mysql:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: root
MYSQL_DATABASE: migration_tracking
ports:
- "3306:3306"
# Start
docker-compose up -d
# View logs
docker-compose logs -f migration-tool
# Stop
docker-compose down
Useful SQL Queries
Find Missing Records
-- Products in OC3 but not in OC4
SELECT p3.product_id, p3.model
FROM opencart3_db.oc_product p3
LEFT JOIN opencart4_db.oc_product p4 ON p3.product_id = p4.product_id
WHERE p4.product_id IS NULL;
Check for Duplicates
-- Find duplicate customers
SELECT email, COUNT(*) as count
FROM oc_customer
GROUP BY email
HAVING count > 1;
Verify Foreign Keys
-- Products with invalid category
SELECT p.product_id, p.model
FROM oc_product p
LEFT JOIN oc_category c ON p.category_id = c.category_id
WHERE p.category_id > 0 AND c.category_id IS NULL;
Performance Optimization
MySQL Optimization
-- Optimize tables
OPTIMIZE TABLE oc_product;
OPTIMIZE TABLE oc_order;
-- Analyze tables
ANALYZE TABLE oc_product;
ANALYZE TABLE oc_order;
-- Check indexes
SHOW INDEX FROM oc_product;
PHP Optimization
; php.ini settings
memory_limit = 1G
max_execution_time = 3600
max_input_time = 3600
post_max_size = 100M
upload_max_filesize = 100M
; Enable OPcache
opcache.enable=1
opcache.memory_consumption=256
opcache.max_accelerated_files=20000
Security Checklist
# After installation
rm install.php
# Secure config
chmod 400 config/config.php
# Protect logs
cat > logs/.htaccess << EOF
Order deny,allow
Deny from all
EOF
# Use strong passwords
# Enable HTTPS
# Limit IP access (optional)
Backup Strategy
# Before migration
mysqldump -u root -p opencart3_db > oc3_before.sql
mysqldump -u root -p opencart4_db > oc4_before.sql
# During migration (snapshots)
mysqldump -u root -p opencart4_db > oc4_snapshot_$(date +%Y%m%d_%H%M%S).sql
# After migration
mysqldump -u root -p opencart4_db > oc4_final.sql
# Backup images
tar -czf images_backup.tar.gz /path/to/opencart4/image/
Common Patterns
Custom Transformation
// In YourTables.php
'transformations' => [
'custom_field' => function($value, $record) {
// Your logic here
return $transformedValue;
},
'category_id' => 'ID_MAPPING:category',
'store_id' => 'SMART_STORE_ID',
]
Adding Validation
// In YourValidationStep.php
protected function getCustomValidationRules(): array
{
return [
'rule_name' => function($sourceDb, $targetDb) {
// Your validation logic
return $result;
}
];
}
Getting Help
Documentation
Community
Version Information
// Check version
cat config/config.example.php | grep version
// Git information
git log --oneline -5
git describe --tags
Need more details? Check the full Documentation.