Orm Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require atlas/orm
   

   Add the service provider to config/app.php:

   'providers' => [
       Atlas\Orm\AtlasServiceProvider::class,
   ],
   

2. Define a Record Create a record class extending Atlas\Orm\Record:

   namespace App\Records;
   
   use Atlas\Orm\Record;
   
   class UserRecord extends Record
   {
       protected $table = 'users';
       protected $primaryKey = 'id';
   }
   

3. First Query

   use App\Records\UserRecord;
   
   $user = UserRecord::find(1); // Hydrates a record from DB
   $users = UserRecord::all();  // Returns a collection of records
   

4. Key Files to Review

   • Atlas Documentation (official docs)
   • src/Atlas/Orm/Record.php (core class)
   • src/Atlas/Orm/QueryBuilder.php (query logic)

Implementation Patterns

Core Workflows

1. CRUD Operations

   // Create
   $user = new UserRecord(['name' => 'John', 'email' => 'john@example.com']);
   $user->save();
   
   // Read
   $user = UserRecord::find(1);
   $users = UserRecord::where('active', true)->get();
   
   // Update
   $user->name = 'Jane';
   $user->save();
   
   // Delete
   $user->delete();
   

2. Relationships (via hasOne, hasMany)

   class PostRecord extends Record
   {
       protected $table = 'posts';
       public function user()
       {
           return $this->hasOne(UserRecord::class, 'user_id');
       }
   }
   
   $post = PostRecord::find(1);
   $user = $post->user; // Eager-loaded if needed
   

3. Transactions

   Atlas\Orm\Atlas::transaction(function () {
       $user = new UserRecord(['name' => 'Alice']);
       $user->save();
   
       $post = new PostRecord(['title' => 'Hello', 'user_id' => $user->id]);
       $post->save();
   });
   

4. Query Scoping

   class ActiveUserScope extends Atlas\Orm\Scope
   {
       public function apply(Atlas\Orm\QueryBuilder $query)
       {
           return $query->where('active', true);
       }
   }
   
   class UserRecord extends Record
   {
       protected $scopes = [ActiveUserScope::class];
   }
   

5. Integration with Laravel Eloquent Use Atlas records to hydrate Eloquent models:

   $userRecord = UserRecord::find(1);
   $userModel = new User($userRecord->toArray());
   

Gotchas and Tips

Common Pitfalls

1. Passive Records

   • Atlas records are disconnected from the DB after hydration. Avoid assuming they auto-sync with the DB.
   • Always call save() or delete() explicitly.

2. Primary Key Assumptions

   • Defaults to id, but override $primaryKey if your table uses a different column (e.g., uuid).

3. Mass Assignment

   • Atlas does not protect against mass assignment by default. Whitelist attributes explicitly:

     protected $fillable = ['name', 'email'];
     

4. Relationship Caching

   • Relationships are lazy-loaded. Use with() to eager-load:

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

5. Query Builder Confusion

   • Atlas uses a custom QueryBuilder (not Laravel’s). Methods like where() work similarly, but some Eloquent-specific methods (e.g., orWhere) may behave differently.

Debugging Tips

• Enable Logging Configure Atlas to log queries in config/atlas.php:

  'logging' => true,
  

  Logs appear in Laravel’s default log channel.

• SQL Dump Use Atlas\Orm\Atlas::enableQueryLogging() to dump raw SQL to the console:

  Atlas\Orm\Atlas::enableQueryLogging();
  $users = UserRecord::all(); // SQL will be logged
  

• Check for Stale Records Atlas does not auto-refresh records. Manually reload with:

  $user->fresh();
  

Extension Points

1. Custom Query Builders Extend Atlas\Orm\QueryBuilder for domain-specific queries:

   class CustomQueryBuilder extends Atlas\Orm\QueryBuilder
   {
       public function customMethod()
       {
           return $this->whereRaw('...');
       }
   }
   

2. Event Hooks Override lifecycle methods:

   class UserRecord extends Record
   {
       protected static function boot()
       {
           static::creating(function ($record) {
               $record->created_at = now();
           });
       }
   }
   

3. Custom Hydration Override hydrate() to transform data before assignment:

   protected function hydrate(array $data)
   {
       $data['email'] = strtolower($data['email']);
       return parent::hydrate($data);
   }
   

4. Database-Agnostic Logic Atlas abstracts DB-specific quirks. Use it for:

   • Cross-database migrations.
   • Complex joins or subqueries.
   • Stored procedure interactions.

Configuration Quirks

• Default Connection Atlas uses Laravel’s default DB connection. Specify a custom one via:

  Atlas\Orm\Atlas::setConnection('mysql_secondary');
  

• Timestamp Handling Atlas does not auto-manage created_at/updated_at. Add logic in boot() or override save():

  protected function save(array $options = [])
  {
      if (!$this->{$this->getCreatedAtColumn()}) {
          $this->{$this->getCreatedAtColumn()} = now();
      }
      return parent::save($options);
  }
  

• Soft Deletes Implement manually or use a trait:

  use Atlas\Orm\Traits\SoftDeletes;
  
  class UserRecord extends Record
  {
      use SoftDeletes;
      protected $deletedAtColumn = 'deleted_at';
  }