Database Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require luracast/database
   

   Requires PHP 7.4+ and a database connection configured in config/database.php (manually or via .env).

2. First Database Connection Define a connection in config/database.php:

   'connections' => [
       'mysql' => [
           'driver' => 'mysql',
           'host' => env('DB_HOST', '127.0.0.1'),
           'database' => env('DB_DATABASE', 'forge'),
           'username' => env('DB_USERNAME', 'root'),
           'password' => env('DB_PASSWORD', ''),
       ],
   ],
   

3. Run Migrations

   vendor/bin/artisan migrate
   

   (Ensure migrations table exists; run migrate:install if missing.)

4. First Migration

   vendor/bin/artisan make:migration create_users_table
   

   Edit the generated file in database/migrations/ and run:

   vendor/bin/artisan migrate
   

First Use Case: CLI-Driven Development

Use db commands to interact with the database directly:

# Start a Tinker-like session
vendor/bin/artisan db

# Seed the database
vendor/bin/artisan db:seed

# Wipe and reset (careful!)
vendor/bin/artisan db:wipe
vendor/bin/artisan migrate:fresh

Implementation Patterns

Workflow: Migration-Heavy Projects

1. Structured Migration Naming Use timestamps + descriptive names (e.g., 2023_01_01_000000_create_products_table). Group related migrations (e.g., users_, roles_) for logical rollbacks.

2. Seeding Data Create seeders with make:seeder:

   vendor/bin/artisan make:seeder UsersTableSeeder
   

   Chain seeders in database/seeders/DatabaseSeeder.php:

   public function run()
   {
       $this->call([
           UsersTableSeeder::class,
           RolesTableSeeder::class,
       ]);
   }
   

   Run with:

   vendor/bin/artisan db:seed --class=UsersTableSeeder
   

3. Artisan Command Integration Extend Laravel’s Artisan for custom tasks. Example:

   vendor/bin/artisan make:command GenerateReports
   

   Register in app/Console/Kernel.php:

   protected $commands = [
       \App\Console\Commands\GenerateReports::class,
   ];
   

Integration Tips

1. Non-Laravel Projects

   • Use Luracast\Database\Bootstrap\BootstrapApplication to bootstrap the database layer:

     $app = BootstrapApplication::create();
     $app->make(\Illuminate\Database\Capsule\Manager::class)->bootEloquent();
     

   • Access the DB via Eloquent:

     $users = \App\Models\User::all();
     

2. Testing Use migrate:fresh in PHPUnit tests:

   public function setUp(): void
   {
       Artisan::call('migrate:fresh');
       Artisan::call('db:seed');
   }
   

3. Custom Commands Override default commands (e.g., db:wipe) by publishing and modifying:

   vendor/bin/artisan vendor:publish --tag=laravel-database-commands
   

Gotchas and Tips

Pitfalls

1. Missing migrations Table

   • Error: Table 'migrations' doesn't exist.
   • Fix: Run migrate:install before migrations.
   • Tip: Add a check in AppServiceProvider:

     public function boot()
     {
         if (!Schema::hasTable('migrations')) {
             Artisan::call('migrate:install');
         }
     }
     

2. Environment Configuration

   • Gotcha: .env is not auto-loaded. Manually set up config/database.php or use:

     $dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
     $dotenv->load();
     

   • Tip: Use env() helper or config('database.connections.mysql.host').

3. Seeding Order Dependencies

   • Gotcha: Seeders may fail if tables aren’t created first.
   • Fix: Use Artisan::call('migrate') in seeders or chain them logically.

4. Artisan in Non-Laravel Contexts

   • Gotcha: Commands like serve or tinker require a full Laravel setup.
   • Tip: Use only migrate, db:seed, and make:* commands for non-Laravel projects.

Debugging

1. Migration Failures

   • Check migrate:status for stuck migrations.
   • Rollback with migrate:rollback --step=1 or migrate:reset.
   • Tip: Use --pretend to dry-run migrations:

     vendor/bin/artisan migrate --pretend
     

2. Seeder Errors

   • Run seeders in isolation:

     vendor/bin/artisan db:seed --class=UsersTableSeeder --force
     

   • Tip: Use transactions in seeders to avoid partial failures:

     DB::transaction(function () {
         // Seeding logic
     });
     

3. Eloquent Issues

   • Gotcha: Models must be in app/Models/ (or configured in Model::setConnectionResolvers()).
   • Fix: Ensure bootEloquent() is called:

     $capsule = new \Illuminate\Database\Capsule\Manager();
     $capsule->addConnection(config('database.default'));
     $capsule->bootEloquent();
     

Extension Points

1. Custom Migration Paths Override the migrations path in config/database.php:

   'migrations' => [
       'path' => database_path('custom_migrations'),
   ],
   

2. Event Listeners Listen to migration events (e.g., Migrating, Migrated) in EventServiceProvider:

   protected $listen = [
       'Illuminate\Database\Events\Migrating' => [
          \App\Listeners\LogMigration::class,
       ],
   ];
   

3. Database Observers Attach observers to models for automatic logging/auditing:

   class UserObserver
   {
       public function saved(User $user)
       {
           // Log changes
       }
   }
   

   Register in AppServiceProvider:

   User::observe(UserObserver::class);
   

4. Query Logging Enable query logging in config/database.php:

   'log' => env('DB_LOG_QUERIES', false),
   'log_query_params' => env('DB_LOG_QUERY_PARAMS', true),
   

   View logs in storage/logs/laravel.log.