Importbundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require delirehberi/import ">=1" in your Laravel project directory. (Note: This package is Symfony-based, but Laravel can integrate it via symfony/bundle compatibility.)

2. Service Provider Registration Add the bundle to config/app.php under providers:

   Delirehberi\ImportBundle\DelirehberiImportBundle::class,
   

3. Configuration Define database connections in config/database.php (or config/config.yml if using Symfony-style config) under connections:

   'old_database' => [
       'driver' => 'mysql',
       'url' => env('DATABASE_URL'),
       'host' => env('DB_HOST'),
       'port' => env('DB_PORT', '3306'),
       'database' => env('OLD_DB_NAME'),
       'username' => env('OLD_DB_USER'),
       'password' => env('OLD_DB_PASSWORD'),
       'charset' => 'utf8mb4',
       'collation' => 'utf8mb4_unicode_ci',
       'prefix' => '',
       'strict' => true,
       'engine' => null,
   ],
   

4. First Use Case Create a migration to import data from the old database:

   php artisan make:migration import_users_from_old_db --table=users
   

   Then, in the migration file, use the bundle’s importer:

   use Delirehberi\ImportBundle\Import\Importer;
   
   public function up()
   {
       $importer = new Importer('old_database');
       $importer->setSourceTable('users_old')
                ->setDestinationTable('users')
                ->setColumns(['name', 'email', 'created_at'])
                ->import();
   }
   

Implementation Patterns

Workflows

1. Batch Importing Use chunking to avoid memory issues for large datasets:

   $importer = new Importer('old_database');
   $importer->setSourceTable('products')
            ->setDestinationTable('items')
            ->setBatchSize(1000)
            ->import();
   

2. Mapping Fields Handle column name mismatches or transformations:

   $importer->setFieldMappings([
       'old_name' => 'name',
       'price_in_cents' => function ($value) {
           return $value / 100; // Convert cents to dollars
       },
   ]);
   

3. Conditional Imports Filter records before importing (e.g., only active users):

   $importer->setWhereClause('is_active = 1')
            ->import();
   

4. Post-Import Actions Trigger events after import (e.g., send notifications):

   $importer->onImported(function () {
       Log::info('User import completed!');
   });
   

Integration Tips

• Laravel Queues: Offload large imports to a queue job:

  use Delirehberi\ImportBundle\Jobs\ImportJob;
  
  ImportJob::dispatch('old_database', 'users_old', 'users')->onQueue('imports');
  

• Laravel Events: Dispatch custom events for post-import processing:

  event(new UsersImported($importedCount));
  

• Laravel Scout: Index imported data immediately:

  $importer->onImported(function () {
      \App\Models\User::all()->each->searchable();
  });
  

Gotchas and Tips

Pitfalls

1. Connection Key Mismatch Ensure the connection_key in config matches the key defined in config/database.php. Fix: Double-check delirehberi_import.connection_key.database vs. your Laravel connection name.

2. Foreign Key Constraints Disable constraints during import to avoid errors:

   DB::statement('SET FOREIGN_KEY_CHECKS=0;');
   $importer->import();
   DB::statement('SET FOREIGN_KEY_CHECKS=1;');
   

3. Data Type Conflicts Explicitly cast fields to avoid SQL errors:

   $importer->setFieldMappings([
       'price' => 'decimal:8,2',
       'is_active' => 'boolean',
   ]);
   

4. Archived Package Risks

   • No active maintenance; fork or extend locally if critical.
   • Test thoroughly in staging before production.

Debugging

• Log Imports: Enable query logging:

  $importer->setDebug(true);
  

• Dry Runs: Test without writing to the DB:

  $importer->setDryRun(true)->import(); // Logs SQL but doesn’t execute.
  

• Chunk Debugging: Log batch progress:

  $importer->onBatchImported(function ($batch) {
      Log::debug("Imported batch {$batch['offset']}-{$batch['offset'] + $batch['count']}");
  });
  

Extension Points

1. Custom Importers Extend the base Importer class for domain-specific logic:

   class UserImporter extends Importer {
       public function importWithRoles() {
           $this->afterImport(function () {
               // Assign roles based on old DB data.
           });
       }
   }
   

2. Pre/Post-Import Hooks Override beforeImport() and afterImport() in a custom importer.

3. Laravel Service Container Bind the importer for dependency injection:

   $this->app->bind(Importer::class, function ($app) {
       return new Importer($app['config']['database.connections.old_database']);
   });