ObjectQuel ORM

ObjectQuel ORM provides an intuitive object-relational mapping layer with a purpose-built query language, automatic relationship management, and Data Mapper pattern architecture.

Installation

Install ObjectQuel in your Canvas project via Composer:

composer require quellabs/canvas-objectquel

Configure your database connection in config/database.php:

return [
    'default' => 'mysql',
    'connections' => [
        'mysql' => [
            'driver' => 'mysql',
            'host' => 'localhost',
            'database' => 'canvas',
            'username' => 'root',
            'password' => 'your_password',
            'charset' => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
        ],
    ],
];

Once installed and configured, ObjectQuel is automatically discovered by Canvas. The EntityManager becomes available via $this->em() in controllers that extend BaseController.

CLI Tools (Sculpt)

ObjectQuel includes Sculpt, a CLI tool for development tasks:

# Create new entity interactively
php vendor/bin/sculpt make:entity

# Generate entity from existing table
php vendor/bin/sculpt make:entity-from-table

# Generate and run migrations
php vendor/bin/sculpt make:migrations
php vendor/bin/sculpt quel:migrate

# Rollback migrations
php vendor/bin/sculpt quel:migrate --rollback

Entity Definition

Define entities using PHP annotations:

/**
 * @Orm\Table(name="users")
 */
class UserEntity {
    /**
     * @Orm\Column(name="id", type="integer", length=11, primary_key=true)
     * @Orm\PrimaryKeyStrategy(strategy="identity")
     */
    private ?int $id = null;

    /**
     * @Orm\Column(name="name", type="string", length=255)
     */
    private string $name;

    /**
     * @Orm\Column(name="email", type="string", length=255)
     */
    private string $email;

    /**
     * @Orm\Column(name="created_at", type="datetime", nullable=true)
     */
    private ?\DateTime $createdAt = null;

    // Standard getters and setters
    public function getId(): ?int { return $this->id; }
    public function getName(): string { return $this->name; }
    public function setName(string $name): void { $this->name = $name; }
    // ...
}

Basic CRUD Operations

Standard find, persist, and remove operations:

// Find by ID
$user = $this->em()->find(UserEntity::class, $id);

// Find by criteria
$admins = $this->em()->findBy(UserEntity::class, [
    'active' => true,
    'role' => 'admin'
]);

// Create
$user = new UserEntity();
$user->setName('John Doe');
$user->setEmail('john@example.com');
$this->em()->persist($user);
$this->em()->flush();

// Update
$user->setEmail('newemail@example.com');
$this->em()->persist($user);
$this->em()->flush();

// Delete
$this->em()->remove($user);
$this->em()->flush();

ObjectQuel Query Language

Execute queries using ObjectQuel's declarative syntax:

// Basic query
$results = $this->em()->executeQuery("
    range of p is App\\Entity\\PostEntity
    retrieve (p) where p.published = :published
    sort by p.createdAt desc
", [
    'published' => true
]);

$posts = array_column($results, 'p');

// Query with relationships
$results = $this->em()->executeQuery("
    range of u is App\\Entity\\UserEntity
    range of p is App\\Entity\\PostEntity via u.posts
    retrieve (u, p) where u.id = :userId
    sort by p.createdAt desc
", [
    'userId' => $authorId
]);

Learn More

For comprehensive documentation on ObjectQuel including advanced query syntax, caching strategies, transaction management, and performance optimization, visit the ObjectQuel documentation site.