Quick Start

Get up and running with ObjectQuel in under 10 minutes. This guide will walk you through setting up entities, writing queries, and performing database operations using ObjectQuel's intuitive query language.

Step 1: Create Your First Entity

Use the Sculpt tool to generate an entity, or create one manually. Here's src/Entity/ProductEntity.php:

<?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="price", type="decimal", limit="10,2")
     */
    private float $price;

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

    // Getters and setters
    public function getProductId(): ?int { return $this->productId; }
    public function getName(): string { return $this->name; }
    public function setName(string $name): void { $this->name = $name; }
    public function getPrice(): float { return $this->price; }
    public function setPrice(float $price): void { $this->price = $price; }
    public function isActive(): bool { return $this->active; }
    public function setActive(bool $active): void { $this->active = $active; }
}

Step 2: Query with ObjectQuel Language

ObjectQuel provides an intuitive query language that works with entities:

<?php
// Basic entity retrieval
$product = $entityManager->find(ProductEntity::class, 1);

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

// Advanced ObjectQuel queries
$affordableProducts = $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
]);

// Retrieve specific properties only
$productNames = $entityManager->executeQuery("
    range of p is App\\Entity\\ProductEntity
    retrieve (p.name) where p.active = true
    sort by p.name asc
");

foreach($productNames as $row) {
    echo $row['p.name'] . "\n";
}

Step 3: Work with Entity Relationships

Create related entities and query across relationships:

<?php
namespace App\Entity;

/**
 * @Orm\Table(name="categories")
 */
class CategoryEntity {

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

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

    /**
     * @Orm\OneToMany(targetEntity="ProductEntity", mappedBy="categoryId")
     */
    public $products;

    // Getters and setters...
}

// Query across relationships
$results = $entityManager->executeQuery("
    range of p is App\\Entity\\ProductEntity
    range of c is App\\Entity\\CategoryEntity via p.category
    retrieve (p, c.name) where c.name = :categoryName
    sort by p.price asc
", [
    'categoryName' => 'Electronics'
]);

foreach($results as $row) {
    $product = $row['p'];
    $categoryName = $row['c.name'];
    echo $product->getName() . " in " . $categoryName . "\n";
}

Step 4: Save and Persist Data

Create, update, and delete entities using the EntityManager:

<?php
// Create a new product
$product = new ProductEntity();
$product->setName("New Widget");
$product->setPrice(29.99);
$product->setActive(true);

// Tell EntityManager to track this entity
$entityManager->persist($product);

// Save all changes to database
$entityManager->flush();

// Update existing product
$existingProduct = $entityManager->find(ProductEntity::class, 1);
$existingProduct->setPrice(24.99);
$entityManager->persist($existingProduct);
$entityManager->flush();

// Delete a product
$productToDelete = $entityManager->find(ProductEntity::class, 5);
$entityManager->remove($productToDelete);
$entityManager->flush();

Step 5: Generate Database Schema

Use Sculpt to create migrations and update your database schema:

# Generate migration from entity definitions
php bin/sculpt make:migrations

# Apply migrations to database
php bin/sculpt quel:migrate

Congratulations! You've learned the core concepts of ObjectQuel. You can now work with entities, write intuitive queries, and manage your database schema. Ready to dive deeper? Explore our guides on Advanced Queries, Entity Relationships, and Performance Optimization.