Model Manager Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require pomm-project/model-manager
   

   Register the service provider in config/app.php under providers:

   PommProject\ModelManager\ModelManagerServiceProvider::class,
   

2. Basic Configuration Publish the config file (if needed) and set up your Pomm database connection in config/pomm.php:

   'connections' => [
       'default' => [
           'driver' => 'pomm',
           'host' => 'localhost',
           'port' => 5432,
           'database' => 'your_db',
           'user' => 'your_user',
           'password' => 'your_password',
       ],
   ],
   

3. First Use Case: Define a Model Create a model class extending PommProject\ModelManager\Model:

   use PommProject\ModelManager\Model;
   
   class User extends Model
   {
       protected $table = 'users';
       protected $primaryKey = 'id';
       protected $fillable = ['name', 'email'];
   }
   

   Use it in a controller or service:

   $user = User::find(1);
   $user->name = 'John Doe';
   $user->save();
   

Implementation Patterns

Common Workflows

1. CRUD Operations Leverage Eloquent-like methods:

   // Create
   $user = new User(['name' => 'Alice', 'email' => 'alice@example.com']);
   $user->save();
   
   // Read
   $user = User::find(1);
   $users = User::all();
   
   // Update
   $user->email = 'new@example.com';
   $user->save();
   
   // Delete
   $user->delete();
   

2. Query Building Use Pomm’s query builder via the model:

   $activeUsers = User::where('active', true)->get();
   $users = User::orderBy('name')->limit(10)->get();
   

3. Relationships Define relationships in model classes:

   class Post extends Model
   {
       public function user()
       {
           return $this->belongsTo(User::class, 'user_id');
       }
   }
   

   Fetch relationships:

   $post = Post::find(1);
   $user = $post->user; // Lazy-loaded
   

4. Transactions Wrap operations in transactions:

   DB::transaction(function () {
       $user = new User(['name' => 'Bob']);
       $user->save();
       // Other operations...
   });
   

Integration Tips

• Custom Pomm Schema: Extend PommProject\ModelManager\Schema to add custom table definitions or behaviors.
• Events: Bind to model events (e.g., creating, saved) for hooks:

  User::creating(function ($model) {
      $model->active = true;
  });
  

• Validation: Use Laravel’s validator with model data:

  $validator = Validator::make($user->toArray(), [
      'email' => 'required|email',
  ]);
  

Gotchas and Tips

Pitfalls

1. Primary Key Assumptions The package assumes $primaryKey is set. If omitted, it defaults to id, but this may fail for non-standard schemas. Always explicitly define $primaryKey.

2. Pomm-Specific Quirks

   • Schema Migrations: Unlike Eloquent, Pomm doesn’t auto-migrate tables. Use Pomm’s Schema class or raw SQL for schema changes.
   • Connection Handling: Ensure your Pomm connection is properly configured in config/pomm.php. Test it with:

     $pomm = app('pomm');
     $pomm->getConnection()->getDatabase()->getSchemaManager()->getTables();
     

3. Lazy Loading Overhead Relationships are lazy-loaded by default. Eager-load them to avoid N+1 queries:

   $posts = Post::with('user')->get();
   

4. Mass Assignment Risks Always define $fillable or $guarded to prevent mass assignment vulnerabilities.

Debugging Tips

• Enable Pomm Logging Add to config/pomm.php:

  'log' => [
      'enabled' => true,
      'channel' => 'single',
  ],
  

  Check logs in storage/logs/laravel.log.

• Query Inspection Use toSql() to debug queries:

  $query = User::where('active', true);
  dd($query->toSql());
  

• Model Events Override boot() to add custom logic:

  protected static function boot()
  {
      static::saved(function ($model) {
          Log::info("User saved: {$model->id}");
      });
  }
  

Extension Points

1. Custom Model Behavior Override methods like save(), delete(), or toArray() for custom logic.

2. Query Scopes Add global scopes:

   class User extends Model
   {
       protected static function booted()
       {
           static::addGlobalScope(new ActiveScope);
       }
   }
   

3. Pomm-Specific Extensions Access the underlying Pomm instance:

   $pomm = $this->getPommConnection();
   $result = $pomm->getConnection()->getDatabase()->execute('SELECT * FROM users');