Model Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require baikal/model-bundle
   

   Enable the bundle in config/bundles.php (Symfony) or config/app.php (Laravel via Symfony bridge):

   return [
       // ...
       Baikal\ModelBundle\BaikalModelBundle::class => ['all' => true],
   ];
   

2. First Use Case Define a model extending Baikal\ModelBundle\Model\AbstractModel:

   namespace App\Models;
   
   use Baikal\ModelBundle\Model\AbstractModel;
   
   class User extends AbstractModel
   {
       protected $table = 'users';
       protected $primaryKey = 'id';
   }
   

   Use the model in a controller:

   use App\Models\User;
   
   public function index()
   {
       $users = User::all(); // Uses Baikal's query builder
       return response()->json($users);
   }
   

3. Key Entry Points

   • Model Definition: Extend AbstractModel for basic CRUD.
   • Query Builder: Use Baikal\ModelBundle\Query\QueryBuilder for complex queries.
   • Events: Listen to baikal.model.created, baikal.model.updated, etc.

Implementation Patterns

Core Workflows

1. CRUD Operations Leverage built-in methods:

   // Create
   $user = new User(['name' => 'John']);
   $user->save();
   
   // Read
   $user = User::find(1);
   $users = User::where('active', true)->get();
   
   // Update
   $user->name = 'Jane';
   $user->save();
   
   // Delete
   $user->delete();
   

2. Query Building Use the query builder for dynamic queries:

   $query = User::query()
       ->where('role', 'admin')
       ->orderBy('created_at', 'desc')
       ->limit(10);
   
   $results = $query->get();
   

3. Relationships Define relationships via hasOne, hasMany, etc.:

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

4. Events and Observers Attach observers to models:

   // config/baikal.php
   'observers' => [
       User::class => [
           \App\Observers\UserObserver::class,
       ],
   ];
   

Integration Tips

• Laravel Eloquent Hybrid: Mix Baikal’s query builder with Eloquent:

  $users = User::query()->where('active', true)->get(); // Baikal
  $users = User::whereHas('posts')->get(); // Eloquent
  

• API Resources: Pair with Laravel’s ApiResource for JSON serialization:

  class UserResource extends \Illuminate\Http\Resources\Json\JsonResource
  {
      public function toArray($request)
      {
          return [
              'id' => $this->id,
              'name' => $this->name,
          ];
      }
  }
  

Gotchas and Tips

Common Pitfalls

1. Namespace Conflicts Ensure Baikal\ModelBundle is not shadowed by other packages. Prefix classes if needed:

   use Baikal\ModelBundle\Model\AbstractModel as BaikalAbstractModel;
   

2. Query Builder Overrides Baikal’s query builder may override Laravel’s. Explicitly use Baikal\ModelBundle\Query\QueryBuilder if issues arise:

   $query = new \Baikal\ModelBundle\Query\QueryBuilder(User::class);
   

3. Event System Quirks Events like baikal.model.saving may not fire if validation fails. Use baikal.model.saved for post-save logic.

4. Primary Key Assumptions Baikal assumes $primaryKey = 'id' by default. Override in your model if using a custom key:

   protected $primaryKey = 'uuid';
   

Debugging Tips

• Enable Logging Add to config/baikal.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs queries and events to storage/logs/baikal.log.

• Query Dumping Use the dump() method to inspect queries:

  $query = User::where('active', true);
  $query->dump(); // Outputs SQL to logs
  

Extension Points

1. Custom Query Types Extend Baikal\ModelBundle\Query\QueryBuilder for custom clauses:

   namespace App\Extensions;
   
   use Baikal\ModelBundle\Query\QueryBuilder;
   
   class CustomQueryBuilder extends QueryBuilder
   {
       public function customWhere($field, $operator, $value)
       {
           // Custom logic
       }
   }
   

2. Model Events Override event methods in your model:

   class User extends AbstractModel
   {
       public function saving(array $options = [])
       {
           $this->name = strtolower($this->name);
           parent::saving($options);
       }
   }
   

3. Database Drivers Baikal supports multiple drivers (MySQL, PostgreSQL, SQLite). Configure in config/baikal.php:

   'connection' => 'pgsql',