ObjectQuel ORM

Last updated: 2026-11-07

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

explanation

Installation

Install ObjectQuel in your Canvas project via Composer:

composer require quellabs/objectquel

Configure your database connection in config/database.php:

return [
    'driver'           => 'mysql',
    'host'             => 'localhost',
    'database'         => 'database',
    'username'         => 'root',
    'password'         => '',
    'port'             => 3306,
    'encoding'         => 'utf8mb4',
    'collation'        => 'utf8mb4_unicode_ci',

    // Development mode
    'development_mode' => true,

    // Entity namespace
    'entity_namespace' => 'App\\Entities',

    // Path to the entities folder
    'entity_path'      => dirname(__FILE__) . '/../src/Entities/',

    // Path to the proxy folder
    'proxy_path'       => dirname(__FILE__) . '/../storage/objectquel/proxies/',

    // Path to the migrations folder
    'migrations_path'  => dirname(__FILE__) . '/../migrations',

    // Table quel:migrate tracks applied migrations in
    'migrations_table' => 'quel_migrations',
];

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

Sculpt CLI Commands

ObjectQuel includes Sculpt, a CLI tool for development tasks:

CommandDescription
sculpt quel:initPublish config/database.php to the project root (skips if it already exists)
sculpt make:entity*Create or update an entity class with properties and relationships, interactively
sculpt make:entity-from-table*Generate an entity class from an existing database table
sculpt make:repository [entity]*Create a repository class for an existing entity
sculpt make:pac-entity [EntityName]*Generate a WakaPAC JavaScript abstraction from an existing entity
sculpt make:migrations*Generate a migration from the difference between your entities and the current schema
sculpt make:blank-migration [Name]*Create a blank migration file for hand-written changes; Name defaults to Migration<timestamp> when omitted
sculpt quel:migrateRun pending migrations, tracked in the configured migrations_table
sculpt quel:migrate --rollback [--steps=n]Roll back the last migration batch, or the last n migrations
sculpt quel:migrate --statusShow which migrations have been applied and which are pending
sculpt quel:migrate --target=<version>Migrate up or down to a specific version
* Installing canvas-doctrine or canvas-eloquent alongside objectquel adds the quel: prefix to make:entity, make:entity-from-table, make:repository, make:pac-entity, make:migrations, and make:blank-migration, to avoid colliding with the other package's command of the same name. quel:init and quel:migrate always keep their prefix.

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
]);

Entity Autowiring

Canvas automatically resolves entity parameters in controller methods. Type-hint an entity class and Canvas fetches it from the database — no manual lookup required. By convention, Canvas uses the route parameter with the same name as the controller parameter as the entity's primary key.

/**
 * @Route("/posts/{id:int}")
 * @param PostEntity|null $id
 * @return Response
 */
public function show(?PostEntity $id): Response {
    if (!$id) {
        return $this->notFound('Post does not exist.');
    }

    return $this->render('blog/show.tpl', ['post' => $id]);
}

The parameter is nullable — if no record is found, null is passed and you handle it in the controller.

Naming the parameter differently

If you'd rather not name the parameter after the route placeholder — calling it $post instead of $id, for example — add a @ResolveEntity annotation naming the controller parameter and the route parameter it should be filled from:

/**
 * @Route("/posts/{id:int}")
 * @ResolveEntity(parameter="post", routeParam="id")
 * @param PostEntity|null $post
 * @return Response
 */
public function show(?PostEntity $post): Response {
    if (!$post) {
        return $this->notFound('Post does not exist.');
    }

    return $this->render('blog/show.tpl', ['post' => $post]);
}

Multiple entity parameters

When a method has more than one entity parameter, add a @ResolveEntity for each parameter whose name doesn't already match its route placeholder. The parameter argument identifies which controller parameter each annotation applies to:

/**
 * @Route("/users/{userId:int}/posts/{postId:int}")
 * @ResolveEntity(parameter="user", routeParam="userId")
 * @ResolveEntity(parameter="post", routeParam="postId")
 * @param UserEntity|null $user
 * @param PostEntity|null $post
 * @return Response
 */
public function show(?UserEntity $user, ?PostEntity $post): Response {
    if (!$user || !$post) {
        return $this->notFound();
    }

    return $this->render('blog/show.tpl', ['user' => $user, 'post' => $post]);
}

@ResolveEntity reference

ParameterRequiredDescription
parameterYesThe name of the controller parameter this annotation applies to.
routeParamYesThe name of the route placeholder that contains the primary key value.

Repository Autowiring

Repositories can be injected directly into any constructor or controller method that Canvas resolves. When Canvas encounters a repository as a parameter type, it resolves it through the DefaultServiceProvider, which instantiates it once and reuses that instance for the lifetime of the application.

class OrderController {
    public function __construct(
        private readonly OrderRepository $orders,
    ) {}
}

No manual instantiation or container configuration is needed — declaring the type is sufficient.

Learn More

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

Frequently Asked Questions

Is basic CRUD simple in ObjectQuel, or do I need to learn the query language first?

Basic CRUD doesn't need the query language at all. find(), findBy(), persist(), flush(), and remove() cover straightforward create, read, update, and delete directly. ObjectQuel's query language is there for when you need it — querying by relationship, sorting, or more complex conditions — not a prerequisite for everyday operations.

What can ObjectQuel's query language express that basic method calls can't?

Genuinely hard queries: window functions, recursive relationship traversal, relational division, and multi-entity joins expressed through relationships rather than hand-written joins. The QUEL-inspired syntax keeps these in the same entity-and-property language as the rest of your domain model, so you don't need to drop into raw SQL as queries grow more complex.

How do I query across relationships in ObjectQuel?

With the via keyword in a range declaration — for example, range of p is PostEntity via u.posts traverses from a user to their posts. You retrieve and filter related entities using the same entity-and-property language as any other query, without writing joins by hand.

Can I skip manual entity lookups in my controller methods?

Yes — entity autowiring. Type-hint an entity class on a route parameter and Canvas fetches it from the database automatically, using the route placeholder as the primary key by convention (or an explicit @ResolveEntity mapping when the names don't match). The parameter comes through as null if no matching record exists.

Is ObjectQuel tied to Canvas, or can I use it separately?

ObjectQuel is a separate project (quellabs/objectquel) that Canvas integrates with via auto-discovery — installing it makes the EntityManager available through $this->em() without extra wiring, but it isn't Canvas-exclusive. Full ObjectQuel documentation, including advanced query syntax and performance tuning, lives at the ObjectQuel documentation site linked above.