Orm Laravel Package

Getting Started

Minimal Setup in Laravel

1. Installation

   composer require cakephp/orm
   

   Add to composer.json under autoload-dev (if using for testing) or autoload:

   "autoload": {
       "psr-4": {
           "App\\": "app/",
           "Cake\\": "vendor/cakephp/orm/src/"
       }
   }
   

   Run composer dump-autoload.

2. First Use Case: Querying a Database Table Define a Table class (e.g., app/Database/UsersTable.php):

   namespace App\Database;
   
   use Cake\ORM\Table;
   use Cake\ORM\RulesChecker;
   
   class UsersTable extends Table
   {
       protected function _initializeSchema()
       {
           return [
               'users' => [
                   'id' => ['type' => 'integer'],
                   'name' => ['type' => 'string', 'null' => false],
                   'email' => ['type' => 'string', 'null' => false]
               ]
           ];
       }
   }
   

   Query users in a Laravel controller:

   use App\Database\UsersTable;
   
   $usersTable = new UsersTable();
   $users = $usersTable->find()->all();
   

Implementation Patterns

1. DataMapper Integration

• Entities: Use CakePHP’s Entity class for model objects (e.g., Cake\ORM\Entity).

  $user = $usersTable->newEntity(['name' => 'John', 'email' => 'john@example.com']);
  $usersTable->save($user);
  

• Associations: Define relationships in initialize():

  protected function _initialize(Connection $connection)
  {
      $this->hasMany('Posts', ['foreignKey' => 'user_id']);
  }
  

2. Query Builder Patterns

• Basic Queries:

  // Find by ID
  $user = $usersTable->get(1);
  
  // Where clause
  $activeUsers = $usersTable->find()->where(['active' => true]);
  
  // Ordering/Limiting
  $users = $usersTable->find()->order(['name' => 'ASC'])->limit(10);
  

• Joins:

  $usersWithPosts = $usersTable->find()
      ->contain(['Posts'])
      ->where(['Posts.title LIKE' => '%test%']);
  

3. Validation

• Define rules in initialize():

  protected function _initialize(Connection $connection)
  {
      $this->addBehavior('Timestamp');
      $this->validationDefault = [
          'email' => ['rule' => 'email']
      ];
  }
  

• Validate manually:

  if (!$user->errors()) {
      $usersTable->save($user);
  }
  

4. Transactions

$connection = $usersTable->getConnection();
$connection->begin();
try {
    $usersTable->save($user);
    $postsTable->save($post);
    $connection->commit();
} catch (\Exception $e) {
    $connection->rollBack();
}

5. Laravel Service Provider Bridge

Create a Laravel service provider to bind CakePHP tables:

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Database\UsersTable;

class CakePHPServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton('usersTable', function ($app) {
            return new UsersTable();
        });
    }
}

Register in config/app.php:

'providers' => [
    App\Providers\CakePHPServiceProvider::class,
],

Gotchas and Tips

1. Configuration Quirks

• Database Connection: CakePHP ORM expects a PDO connection. Configure in config/database.php:

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

• Schema Migrations: CakePHP ORM does not handle migrations. Use Laravel’s migrations for schema changes.

2. Debugging Tips

• Enable Logging:

  $queryLogger = new \Cake\Log\Engine\FileEngine([
      'path' => storage_path('logs/cake_queries.log'),
      'levels' => ['query'],
  ]);
  \Cake\Log\Log::config('query', $queryLogger);
  

• SQL Dump: Use debug() to inspect queries:

  $query = $usersTable->find()->where(['active' => true]);
  \Cake\Log\Log::debug($query->sql());
  

3. Common Pitfalls

• Case Sensitivity: Table/column names are case-sensitive in some databases (e.g., PostgreSQL). Use consistent naming.
• Lazy Loading: Avoid N+1 queries by using contain():

  // Bad (N+1)
  foreach ($users as $user) {
      $user->posts; // Triggers a query per user
  }
  // Good
  $users = $usersTable->find()->contain(['Posts'])->all();
  

• Entity Hydration: Entities are not automatically hydrated from arrays. Use newEntity() or patchEntity():

  $user = $usersTable->patchEntity($existingUser, ['name' => 'Updated']);
  

4. Extension Points

• Custom Query Types: Extend Cake\ORM\Query for reusable logic:

  namespace App\ORM;
  
  use Cake\ORM\Query;
  
  class CustomQuery extends Query
  {
      public function active()
      {
          return $this->where(['active' => true]);
      }
  }
  

  Use in a table:

  $activeUsers = $usersTable->find('custom', ['type' => 'active']);
  

• Behaviors: Reuse logic via behaviors (e.g., Cake\ORM\Behavior\Timestamp):

  $this->addBehavior('Timestamp');
  

• Events: Listen to ORM events (e.g., Model.beforeSave):

  $this->addEventListener('Model.beforeSave', function ($event, $entity, $options) {
      $entity->slug = Str::slug($entity->name);
  });
  

5. Performance Considerations

• Batch Operations: Use saveMany() for bulk inserts/updates:

  $usersTable->saveMany([
      $user1, $user2, $user3
  ]);
  

• Indexing: Ensure frequently queried columns are indexed in your database schema.
• Caching: Cache query results with Laravel’s cache:

  $cacheKey = 'users_active';
  $users = \Cache::remember($cacheKey, 60, function () use ($usersTable) {
      return $usersTable->find()->where(['active' => true])->all();
  });