Phpmig Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require davedevelopment/phpmig
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       DavidDevelopment\PhpMig\PhpMigServiceProvider::class,
   ],
   

2. First Migration Create a migration file in database/migrations/ (e.g., 2024_01_01_000000_create_users_table.php):

   <?php
   use DavidDevelopment\PhpMig\Migration;
   
   class CreateUsersTable extends Migration
   {
       public function up()
       {
           // Your schema logic (e.g., using a DBAL or raw SQL)
           DB::statement("CREATE TABLE users (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255))");
       }
   
       public function down()
       {
           DB::statement("DROP TABLE users");
       }
   }
   

3. Run Migrations

   php artisan phpmig:migrate
   

4. Rollback

   php artisan phpmig:rollback
   

First Use Case: Schema Changes

Use phpmig to version-control database schema changes alongside your Laravel app. Ideal for:

• Teams needing lightweight migrations without Laravel’s Eloquent.
• Projects where Laravel’s migrations are overkill (e.g., legacy systems).
• Custom database backends (e.g., SQLite, PostgreSQL, or even non-SQL databases with adapters).

Implementation Patterns

Workflow Integration

1. Migration Naming Follow Laravel’s convention (YYYY_MM_DD_HHMMSS_description.php) for atomic, chronological migrations. Example:

   database/migrations/
   ├── 2024_01_01_000000_create_users_table.php
   └── 2024_01_02_000000_add_email_to_users.php
   

2. Database Abstraction Use DB::statement() or a DBAL-compatible connection (e.g., Doctrine DBAL) for cross-database support:

   use Doctrine\DBAL\Connection;
   
   class AddIndexToUsers extends Migration
   {
       public function up()
       {
           $connection = DB::connection('pgsql'); // Custom connection
           $connection->executeStatement("CREATE INDEX idx_users_email ON users(email)");
       }
   }
   

3. Seeding Data Combine with phpmig:seed (if extended) or use a post-migration hook:

   public function up()
   {
       $this->up(); // Run schema changes
       $this->seedUsers(); // Custom seeding method
   }
   

4. Environment-Specific Migrations Use conditional logic in up()/down() to target environments:

   public function up()
   {
       if (app()->environment('local')) {
           DB::statement("CREATE TABLE users (...)");
       }
   }
   

Advanced Patterns

• Composite Migrations: Group related migrations into a single file with up()/down() handling dependencies.
• Migration Dependencies: Use a dependsOn() method (if supported) to enforce order:

  class AddPostsTable extends Migration
  {
      public function dependsOn()
      {
          return [CreateUsersTable::class];
      }
  }
  

• Transaction Wrapping: Wrap up() in a transaction for atomicity:

  public function up()
  {
      DB::transaction(function () {
          DB::statement("ALTER TABLE users ADD COLUMN created_at TIMESTAMP");
      });
  }
  

Gotchas and Tips

Pitfalls

1. No Built-in Rollback for Schema Changes

   • phpmig:rollback only reverses the last migration. For complex schemas, manually define down() or use a library like Doctrine Migrations for auto-generated rollbacks.

2. Lack of Laravel-Specific Features

   • No Schema builder (use raw SQL or DBAL).
   • No migrations table by default (track state manually or via a custom table).

3. No Native Testing Support

   • Rollbacks may fail in tests. Use phpmig:fresh (if available) or reset the database manually:

     php artisan phpmig:fresh
     

4. No Event System

   • Unlike Laravel, phpmig lacks events for hooks (e.g., Migrating, Migrated). Use a wrapper class or events manually.

Debugging Tips

• Check Migration Status Inspect the phpmig_migrations table (if created) or manually track run migrations:

  SELECT * FROM phpmig_migrations;
  

• Verbose Output Enable debug mode in config or use:

  php artisan phpmig:migrate --verbose
  

• Dry Runs Test migrations without executing:

  php artisan phpmig:migrate --dry-run
  

Extension Points

1. Custom Migration Repository Override the default repository to store migrations in a non-standard location:

   // config/phpmig.php
   'repository' => [
       'class' => 'Custom\MigrationRepository',
       'path'  => database_path('custom_migrations'),
   ],
   

2. Add a phpmig:seed Command Extend the package to support seeding:

   // app/Console/Commands/SeedCommand.php
   use DavidDevelopment\PhpMig\Console\MigrateCommand;
   
   class SeedCommand extends MigrateCommand
   {
       protected function handle()
       {
           // Custom seeding logic
       }
   }
   

3. Integrate with Laravel’s Artisan Alias phpmig commands to Laravel’s namespace for consistency:

   // In a service provider
   Artisan::addCommands([
       new \DavidDevelopment\PhpMig\Console\MigrateCommand('phpmig:migrate', 'migrate'),
   ]);
   

4. Support for Non-SQL Databases Implement a custom connection adapter (e.g., for Redis or Elasticsearch):

   class RedisMigration extends Migration
   {
       public function up()
       {
           Redis::connection('default')->flushdb();
       }
   }