migrate/README.md

# Magento 1 to Magento 2 Migration Tool

A comprehensive web-based migration tool built with Laravel to migrate data from Magento 1 to Magento 2, including categories, products, customers, and product options.

## Features

### 🗂️ Category Migration
- Multi-store category migration with store mapping
- Preserves category hierarchy and structure
- Migrates category attributes (name, URL key, is_active) for each store view
- Category preview before migration
- Real-time migration progress

### 📦 Product Migration
- Migrates products with all attributes
- Handles products with and without SKUs (auto-generates SKUs when needed)
- Updates existing products or creates new ones
- Migrates product attributes across all backend types (varchar, int, text, decimal, datetime)
- Product-to-category assignments
- Product options migration (catalog_product_option tables)
- Missing attribute detection and reporting
- Dry run mode for testing

### 👥 Customer Migration
- Migrates customer data with all attributes
- Creates new customers or updates existing ones based on email
- Preserves customer website and group assignments

### 📊 Additional Features
- Web-based user interface
- Real-time migration progress tracking
- Detailed error logging (errors-only view)
- Database connection testing
- Comparison tools for products and categories
- Statistics and reporting

## Requirements

- PHP 8.1 or higher
- Laravel 11.x
- MySQL/MariaDB (for both Magento 1 and Magento 2 databases)
- Node.js and NPM (for frontend assets)

## Installation

1. **Clone the repository:**
   ```bash
   git clone <repository-url>
   cd migrate
   ```

2. **Install PHP dependencies:**
   ```bash
   composer install
   ```

3. **Install Node dependencies:**
   ```bash
   npm install
   ```

4. **Set up environment:**
   ```bash
   cp .env.example .env
   php artisan key:generate
   ```

5. **Configure database connections:**
   
   Edit your `.env` file and add the Magento database configurations:
   
   ```env
   # Magento 1 Database
   MAGENTO1_DB_HOST=127.0.0.1
   MAGENTO1_DB_PORT=3306
   MAGENTO1_DB_DATABASE=magento1
   MAGENTO1_DB_USERNAME=root
   MAGENTO1_DB_PASSWORD=your_password
   MAGENTO1_DB_PREFIX=
   
   # Magento 2 Database
   MAGENTO2_DB_HOST=127.0.0.1
   MAGENTO2_DB_PORT=3306
   MAGENTO2_DB_DATABASE=magento2
   MAGENTO2_DB_USERNAME=root
   MAGENTO2_DB_PASSWORD=your_password
   MAGENTO2_DB_PREFIX=
   ```

   For DDEV setups, see [DATABASE_SETUP.md](DATABASE_SETUP.md) for detailed instructions.

6. **Build frontend assets:**
   ```bash
   npm run build
   ```

7. **Run migrations:**
   ```bash
   php artisan migrate
   ```

## Usage

### Accessing the Migration Interface

Once your Laravel application is running, navigate to:

- **Main migration page:** `/migration`
- **Products page:** `/products`
- **Categories page:** `/categories`
- **Customers page:** `/customers`
- **Attributes page:** `/attributes`
- **Connections page:** `/connections`

### Migration Workflow

1. **Test Database Connections**
   - Go to the Connections page or use the "Test Connections" button
   - Verify both Magento 1 and Magento 2 databases are accessible

2. **Category Migration**
   - Map Magento 1 stores to Magento 2 stores
   - Preview categories (optional)
   - Start the migration

3. **Product Migration**
   - Review missing attributes (if any)
   - Run a dry run first to check for errors
   - Start the actual migration
   - Review error logs (only errors are shown)

4. **Customer Migration**
   - Run dry run to preview changes
   - Start customer migration

5. **Product Options Migration**
   - Migrate catalog_product_option tables
   - Includes options, prices, titles, and type values

## Important Notes

⚠️ **Backup First**: Always backup your Magento 2 database before running any migration.

⚠️ **Test Environment**: It's highly recommended to test the migration on a development/staging environment first.

⚠️ **No Data Deletion**: The migration tool only performs INSERT and UPDATE operations. No data is deleted from Magento 2.

⚠️ **Products Without SKUs**: Products without SKUs will automatically receive a generated SKU in the format `MIGRATED-{entity_id}` to satisfy Magento 2's non-null SKU requirement.

⚠️ **Error Logs**: The Product Migration Logs section now shows only errors for easier troubleshooting.

## Project Structure

```
app/
├── Http/Controllers/
│   ├── ProductsController.php      # Product migration controller
│   ├── CategoriesController.php    # Category migration controller
│   ├── CustomersController.php     # Customer migration controller
│   └── ...
├── Services/
│   ├── MagentoProductMigrationService.php    # Product migration logic
│   └── MagentoCategoryMigrationService.php   # Category migration logic
resources/
├── views/
│   ├── products/        # Product migration interface
│   ├── categories/      # Category migration interface
│   ├── customers/       # Customer migration interface
│   └── ...
└── js/
    ├── products.js      # Product migration frontend logic
    ├── categories.js    # Category migration frontend logic
    └── ...
```

## Documentation

- [MAGENTO_MIGRATION_README.md](MAGENTO_MIGRATION_README.md) - Detailed category migration documentation
- [DATABASE_SETUP.md](DATABASE_SETUP.md) - Database connection setup for DDEV
- [ENV_SETUP_INSTRUCTIONS.md](ENV_SETUP_INSTRUCTIONS.md) - Environment configuration guide

## Troubleshooting

### Connection Errors

If you see connection errors:

1. Verify database credentials in `.env`
2. Ensure both databases are accessible from your Laravel application
3. Check database table prefixes if your Magento installations use them
4. For DDEV setups, see [DATABASE_SETUP.md](DATABASE_SETUP.md)

### Migration Errors

1. Check the migration logs in the web interface (errors-only view)
2. Review Laravel logs: `storage/logs/laravel.log`
3. Ensure Magento 2 database has proper permissions
4. Verify that required Magento 2 tables exist
5. Check for missing attributes that need to be created first

### Common Issues

- **"Column 'sku' cannot be null"**: This has been fixed - products without SKUs now get auto-generated SKUs
- **Missing attributes**: The tool will report missing attributes that need to be created in Magento 2 first
- **Store mapping errors**: Ensure store mappings are correct before starting migration

## Development

### Running Tests

```bash
php artisan test
```

### Building Assets

For development:
```bash
npm run dev
```

For production:
```bash
npm run build
```

## License

This project is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

## Support

For issues or questions:
- Check Laravel logs: `storage/logs/laravel.log`
- Review migration logs in the web interface
- Check database connection status in the web interface