Quick Start

Get up and running with ObjectQuel in under 5 minutes. This guide walks you through creating an entity, querying data, and saving changes.

Step 1: Create Your First Entity

Use the Sculpt CLI tool to generate an entity:

php ./vendor/bin/sculpt make:entity

Sculpt will prompt you for the entity name and column definitions. For example, creating a ProductEntity with columns for name, price, and active status generates src/Entity/ProductEntity.php with the appropriate annotations, properties, and getters/setters:

<?php
namespace App\Entity;

use Quellabs\ObjectQuel\Annotations\Orm;

/**
 * @Orm\Table(name="products")
 */
class ProductEntity {

    /**
     * @Orm\Column(name="product_id", type="integer", primary_key=true)
     * @Orm\PrimaryKeyStrategy(strategy="identity")
     */
    private ?int $productId = null;

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

    /**
     * @Orm\Column(name="active", type="boolean", default=true)
     */
    private bool $active = true;

    // Getters and setters omitted for brevity
}

Once your entity is ready, generate and run a migration to create the database table:

php ./vendor/bin/sculpt make:migrations
php ./vendor/bin/sculpt quel:migrate

Step 2: Query Your Data

The EntityManager provides simple lookup methods and a full query language for more complex needs:

<?php
// Find a single entity by primary key
$product = $entityManager->find(ProductEntity::class, 1);

// Find entities matching criteria
$activeProducts = $entityManager->findBy(ProductEntity::class, [
    'active' => true
]);

// Use ObjectQuel's query language for advanced filtering
$results = $entityManager->executeQuery("
    range of p is App\\Entity\\ProductEntity
    retrieve (p) where p.price < :maxPrice and p.active = true
    sort by p.name asc
", [
    'maxPrice' => 50.00
]);

Step 3: Create and Save Entities

Use persist() to tell the EntityManager to track an entity, then flush() to save all pending changes to the database:

<?php
$product = new ProductEntity();
$product->setName("New Widget");
$product->setActive(true);

$entityManager->persist($product);
$entityManager->flush();

That's it! You now know the fundamentals: creating entities with Sculpt, querying data, and persisting changes.