Cycle ORM

https://github.com/cycle/orm
Admin
Cycle ORM is a PHP DataMapper and ORM engine designed for classic and daemonized applications,...
Tokens:6,958
Snippets:36
Trust Score:9.2
License:MIT
Update:9 months ago
Show doc for...
Tokens:
Raw
### Load Active Users with Pre-loaded Paid Orders (PHP)

Source: https://github.com/cycle/orm/blob/2.x/README.md

This example demonstrates how to load all active users and pre-load their paid orders, sorted from newest to oldest, using a LEFT JOIN. It utilizes the Cycle ORM's repository and select methods for data retrieval and manipulation. The EntityManager is then used to persist and run the changes.

```php
// load all active users and pre-load their paid orders sorted from newest to olders
// the pre-load will be complete using LEFT JOIN
$users = $orm->getRepository(User::class)
    ->select()
    ->where('active', true)
    ->load('orders', [
        'method' => Select::SINGLE_QUERY,
        'load'   => function($q) {
            $q->where('paid', true)->orderBy('timeCreated', 'DESC');
        }
    ])
    ->fetchAll();

$em = new EntityManager($orm);

foreach($users as $user) {
    $em->persist($user);
}

$em->run();
```

--------------------------------

### Apply Global Query Constraints with Scopes (PHP)

Source: https://context7.com/cycle/orm/llms.txt

Demonstrates how to implement and apply scopes in Cycle ORM to enforce global query constraints. It shows how to create scope classes (e.g., ActiveScope, TenantScope) that implement the ScopeInterface and how to register them in the schema or apply them at runtime. The examples cover applying a tenant scope and removing scopes for specific queries.

```php
<?php

use Cycle\ORM\Select\ScopeInterface;
use Cycle\ORM\Select\QueryBuilder;

class ActiveScope implements ScopeInterface
{
    public function apply(QueryBuilder $query): void
    {
        $query->where('deleted_at', null);
    }
}

class TenantScope implements ScopeInterface
{
    public function __construct(
        private int $tenantId
    ) {}

    public function apply(QueryBuilder $query): void
    {
        $query->where('tenant_id', $this->tenantId);
    }
}

// Register scope in schema
$schema = new Schema([
    'user' => [
        SchemaInterface::ENTITY => User::class,
        SchemaInterface::SCOPE => ActiveScope::class,
        // ... other options
    ],
]);

// Or apply scope at runtime
$users = (new Select($orm, User::class))
    ->scope(new TenantScope(tenantId: 42))
    ->fetchAll();

// Remove scope for query
$allUsers = (new Select($orm, User::class))
    ->scope(null)
    ->fetchAll();

```

--------------------------------

### Run Docker Compose for Cycle ORM Testing

Source: https://github.com/cycle/orm/blob/2.x/CONTRIBUTING.md

This command starts the Docker containers required to test the Cycle ORM engine locally. Ensure you have Docker installed and are in the 'tests' directory of the cloned repository.

```bash
cd tests/
docker-compose up
```

--------------------------------

### Implement Custom Repositories for Domain Queries (PHP)

Source: https://context7.com/cycle/orm/llms.txt

Details the creation and usage of custom repositories in Cycle ORM to encapsulate domain-specific query logic. It provides examples of methods for finding active users, users by email, users with recent orders, and counting users by status. The code shows how to register the custom repository in the schema and then use it to perform queries.

```php
<?php

use CycleORMSelect;
use CycleORMSelect\Repository;

class UserRepository extends Repository
{
    public function findActiveUsers(): iterable
    {
        return $this->select()
            ->where('status', 'active')
            ->orderBy('name', 'ASC')
            ->fetchAll();
    }

    public function findByEmail(string $email): ?User
    {
        return $this->select()
            ->where('email', $email)
            ->fetchOne();
    }

    public function findWithRecentOrders(int $days = 30): iterable
    {
        return $this->select()
            ->distinct()
            ->with('orders')
            ->where('orders.created_at', '>', new \DateTime("-{$days} days"))
            ->load('orders', [
                'where' => ['{@}.created_at' => ['>' => new \DateTime("-{$days} days")]]
            ])
            ->fetchAll();
    }

    public function countByStatus(string $status): int
    {
        return $this->select()
            ->where('status', $status)
            ->count();
    }
}

// Register in schema
$schema = new Schema([
    'user' => [
        SchemaInterface::ENTITY => User::class,
        SchemaInterface::REPOSITORY => UserRepository::class,
        // ... other options
    ],
]);

// Use custom repository
/** @var UserRepository $userRepo */
$userRepo = $orm->getRepository(User::class);
$activeUsers = $userRepo->findActiveUsers();
$user = $userRepo->findByEmail('john@example.com');

```

--------------------------------

### Execute Full Test Suite with PHPUnit

Source: https://github.com/cycle/orm/blob/2.x/CONTRIBUTING.md

This command runs the complete test suite for the Cycle ORM using PHPUnit. It requires PHPUnit to be installed as a dev-dependency.

```bash
./vendor/bin/phpunit
```

--------------------------------

### Create ORM Instance with Database Configuration

Source: https://context7.com/cycle/orm/llms.txt

Demonstrates how to initialize the Cycle ORM instance. This involves configuring database connections using DatabaseManager and defining the entity schema. The ORM requires a Factory and Schema for initialization.

```php
<?php

use Cycle\ORM\ORM;
use Cycle\ORM\Factory;
use Cycle\ORM\Schema;
use Cycle\ORM\SchemaInterface;
use Cycle\ORM\Mapper\Mapper;
use Cycle\Database\DatabaseManager;
use Cycle\Database\Config\DatabaseConfig;

// Configure database connection
$dbal = new DatabaseManager(new DatabaseConfig([
    'default' => 'default',
    'databases' => [
        'default' => ['connection' => 'sqlite']
    ],
    'connections' => [
        'sqlite' => [
            'driver' => \Cycle\Database\Driver\SQLite\SQLiteDriver::class,
            'connection' => 'sqlite:database.db',
        ]
    ]
]));

// Define entity schema
$schema = new Schema([
    'user' => [
        SchemaInterface::ENTITY => User::class,
        SchemaInterface::MAPPER => Mapper::class,
        SchemaInterface::DATABASE => 'default',
        SchemaInterface::TABLE => 'users',
        SchemaInterface::PRIMARY_KEY => 'id',
        SchemaInterface::COLUMNS => ['id', 'email', 'name', 'balance'],
        SchemaInterface::RELATIONS => [],
    ],
]);

// Create ORM instance
$orm = new ORM(
    factory: new Factory($dbal),
    schema: $schema,
);

// Access services
$heap = $orm->getHeap();
$factory = $orm->getFactory();
$schema = $orm->getSchema();

```

--------------------------------

### Build Select Queries with Cycle ORM

Source: https://context7.com/cycle/orm/llms.txt

Demonstrates how to construct basic and complex SELECT queries using the fluent interface of Cycle ORM's Select class. Supports basic WHERE clauses, primary key lookups, ordering, limiting, aggregation, and raw SQL generation. It also shows how to fetch raw data instead of ORM entities.

```php
<?php

use Cycle\ORM\Select;

// Create select query
$select = new Select($orm, User::class);

// Basic where conditions
$users = $select
    ->where('status', 'active')
    ->where('balance', '>', 100)
    ->orderBy('name', 'ASC')
    ->limit(10)
    ->offset(0)
    ->fetchAll();

// Find by primary key
$user = (new Select($orm, User::class))
    ->wherePK(1)
    ->fetchOne();

// Multiple primary keys
$users = (new Select($orm, User::class))
    ->wherePK(1, 2, 3)
    ->fetchAll();

// Complex conditions with callbacks
$users = (new Select($orm, User::class))
    ->where(function ($q) {
        $q->where('status', 'active')
          ->orWhere('role', 'admin');
    })
    ->fetchAll();

// Aggregations
$count = (new Select($orm, User::class))->count();
$avgBalance = (new Select($orm, User::class))->avg('balance');
$maxBalance = (new Select($orm, User::class))->max('balance');
$minBalance = (new Select($orm, User::class))->min('balance');
$totalBalance = (new Select($orm, User::class))->sum('balance');

// Get raw SQL
$sql = (new Select($orm, User::class))
    ->where('status', 'active')
    ->sqlStatement();

// Fetch as array data (not entities)
$data = (new Select($orm, User::class))
    ->fetchData(typecast: true);

```

--------------------------------

### Query Entities using Repository and ORM

Source: https://context7.com/cycle/orm/llms.txt

Shows how to retrieve entities using repositories and the ORM instance. This includes finding entities by primary key, by conditions, and directly from the ORM, with options to bypass the heap cache.

```php
<?php

use Cycle\ORM\Select;

// Get repository for an entity
$userRepository = $orm->getRepository(User::class);

// Find by primary key
$user = $userRepository->findByPK(1);

// Find one by conditions
$user = $userRepository->findOne(['email' => 'john@example.com']);

// Find all matching conditions
$users = $userRepository->findAll(['status' => 'active']);

// Get entity directly from ORM (uses heap cache)
$user = $orm->get(User::class, ['id' => 1]);

// Force load from database (bypass heap)
$user = $orm->get(User::class, ['id' => 1], load: true);

// Check if entity exists in heap without loading
$user = $orm->get(User::class, ['id' => 1], load: false);

```

--------------------------------

### Execute Quick Test Suite with PHPUnit (SQLite)

Source: https://github.com/cycle/orm/blob/2.x/CONTRIBUTING.md

This command runs a quick subset of the Cycle ORM tests, specifically focusing on the SQLite driver functional tests. It's useful for faster feedback during development.

```bash
./vendor/bin/phpunit tests/ORM/Functional/Driver/SQLite
```

--------------------------------

### Create Entities with ORM Factory (PHP)

Source: https://context7.com/cycle/orm/llms.txt

Demonstrates creating entity instances using the ORM factory method. Entities can be created as new, untracked objects, or as managed entities tracked within the ORM's heap. Supports initial data hydration and optional typecasting for raw database values.

```php
<?php

use Cycle\ORM\Heap\Node;

// Create new entity (not tracked)
$user = $orm->make(User::class);
$user->name = 'Jane Doe';
$user->email = 'jane@example.com';

// Create with initial data
$user = $orm->make(User::class, [
    'name' => 'Jane Doe',
    'email' => 'jane@example.com',
    'balance' => 500.00,
]);

// Create as managed entity (tracked in heap)
$user = $orm->make(User::class, [
    'id' => 1,
    'name' => 'Jane Doe',
    'email' => 'jane@example.com',
], Node::MANAGED);

// Create with typecast (for raw database data)
$user = $orm->make(User::class, [
    'id' => '1',           // Will be cast to int
    'balance' => '500.00', // Will be cast to float
    'created_at' => '2024-01-01 00:00:00', // Will be cast to DateTime
], Node::MANAGED, typecast: true);
```

--------------------------------

### Persist and Delete Entities with EntityManager

Source: https://context7.com/cycle/orm/llms.txt

Illustrates how to use the EntityManager for persisting and deleting entities using the Unit of Work pattern. It covers both deferred and immediate state synchronization, running operations, and cleaning the entity manager.

```php
<?php

use Cycle\ORM\EntityManager;

// Create entity manager
$em = new EntityManager($orm);

// Create new entity
$user = new User();
$user->name = 'John Doe';
$user->email = 'john@example.com';
$user->balance = 100.00;

// Persist with deferred state sync (changes after persist() are included)
$em->persist($user);
$user->balance = 150.00; // This change WILL be saved

// Or persist with immediate state capture (changes after persistState() are ignored)
$em->persistState($user);
$user->balance = 200.00; // This change will NOT be saved

// Execute all pending operations
$state = $em->run();

if ($state->isSuccess()) {
    echo "Entity saved with ID: " . $user->id;
} else {
    echo "Error: " . $state->getLastError()->getMessage();
}

// Delete an entity
$em->delete($user);
$em->run();

// Run without throwing exceptions
$state = $em->run(throwException: false);
if (!$state->isSuccess()) {
    // Handle error gracefully
    $error = $state->getLastError();
}

// Clean the entity manager (reset pending operations)
$em->clean();

// Clean with heap reset
$em->clean(cleanHeap: true);

```

--------------------------------

### Utilize Heap and Identity Map for Entity Tracking (PHP)

Source: https://context7.com/cycle/orm/llms.txt

Explains how to use the Cycle ORM Heap to maintain an identity map, preventing duplicate entity instances. It covers checking if an entity is tracked, accessing its node for state and metadata, finding entities by primary key, cleaning the heap, and creating an ORM with a fresh heap. The primary input is the ORM instance.

```php
<?php

// Access the heap
$heap = $orm->getHeap();

// Check if entity is tracked
$isTracked = $heap->has($user);

// Get node for entity (contains state and metadata)
$node = $heap->get($user);
if ($node !== null) {
    $role = $node->getRole();
    $status = $node->getStatus();  // Node::NEW, Node::MANAGED, Node::DELETED
    $data = $node->getData();
}

// Find entity in heap by primary key
$user = $heap->find('user', ['id' => 1]);

// Clean heap (detach all entities)
$heap->clean();

// Create ORM with fresh heap
$freshOrm = $orm->with(heap: new CycleORMHeapHeap());

// Detach specific entity
$heap->detach($user);

```

--------------------------------

### Manage Entity Relations with Property Assignment (PHP)

Source: https://context7.com/cycle/orm/llms.txt

Demonstrates how to manage one-to-one, one-to-many, and many-to-many relationships in Cycle ORM by assigning related entities to properties. It covers creating, persisting, and removing entities within these relations. Dependencies include the EntityManager and ORM instance.

```php
<?php

use CycleORMEntityManager;

$em = new EntityManager($orm);

// Create user with profile (has-one)
$user = new User();
$user->name = 'John Doe';
$user->email = 'john@example.com';

$profile = new Profile();
$profile->bio = 'Developer';
$profile->avatar = 'avatar.jpg';

$user->profile = $profile;

$em->persist($user);
$em->run(); // Both user and profile are saved

// Create user with posts (has-many)
$user = new User();
$user->name = 'Jane Doe';
$user->posts = [];

$post1 = new Post();
$post1->title = 'First Post';
$post1->content = 'Content here';

$post2 = new Post();
$post2->title = 'Second Post';
$post2->content = 'More content';

$user->posts[] = $post1;
$user->posts[] = $post2;

$em->persist($user);
$em->run(); // User and all posts are saved

// Many-to-many relations
$post = new Post();
$post->title = 'Tagged Post';
$post->tags = [];

$tag1 = $orm->getRepository(Tag::class)->findOne(['name' => 'PHP']);
$tag2 = new Tag();
$tag2->name = 'ORM';

$post->tags[] = $tag1;
$post->tags[] = $tag2;

$em->persist($post);
$em->run(); // Post, new tag, and pivot records are saved

// Remove from relation
$user = $orm->getRepository(User::class)
    ->select()
    ->load('posts')
    ->wherePK(1)
    ->fetchOne();

// Remove specific post
$postToRemove = $user->posts[0];
unset($user->posts[array_search($postToRemove, $user->posts)]);

$em->persist($user);
$em->delete($postToRemove); // Optional: also delete the post
$em->run();

```

--------------------------------

### Eagerly Load Relations with Cycle ORM

Source: https://context7.com/cycle/orm/llms.txt

Explains how to use the `load()` method in Cycle ORM's Select class to efficiently load related entities, preventing the N+1 query problem. Supports loading single, multiple, and nested relations, with options for custom conditions, ordering, and controlling the loading method (e.g., LEFT JOIN, separate query).

```php
<?php

use Cycle\ORM\Select;

// Load single relation
$users = (new Select($orm, User::class))
    ->load('profile')
    ->fetchAll();

// Load multiple relations
$users = (new Select($orm, User::class))
    ->load(['profile', 'comments', 'orders'])
    ->fetchAll();

// Load nested relations (user -> posts -> comments)
$users = (new Select($orm, User::class))
    ->load('posts.comments')
    ->fetchAll();

// Load with conditions using placeholder {@} for table alias
$users = (new Select($orm, User::class))
    ->load('comments', [
        'where' => ['{@}.approved' => true],
        'orderBy' => ['{@}.created_at' => 'DESC'],
    ])
    ->fetchAll();

// Control loading method
$users = (new Select($orm, User::class))
    ->load('orders', [
        'method' => Select::SINGLE_QUERY,  // Use LEFT JOIN
        'load' => function ($q) {
            $q->where('paid', true)
              ->orderBy('created_at', 'DESC');
        }
    ])
    ->fetchAll();

// Load with OUTER_QUERY (separate query, default for has-many)
$users = (new Select($orm, User::class))
    ->load('orders', ['method' => Select::OUTER_QUERY])
    ->fetchAll();

// Many-to-many with pivot conditions
$users = (new Select($orm, User::class))
    ->load('tags', [
        'wherePivot' => ['{@}.approved' => true]
    ])
    ->fetchAll();

```

--------------------------------

### Configure Doctrine and Illuminate Collections in Cycle ORM Factory

Source: https://context7.com/cycle/orm/llms.txt

This snippet demonstrates how to configure custom collection factories for Doctrine Collections and Illuminate Collections within the Cycle ORM Factory. It shows the instantiation of the Factory and the use of `withCollectionFactory` to register a specific collection type and its corresponding class.

```php
<?php

use Cycle\ORM\Factory;
use Cycle\ORM\Collection\DoctrineCollectionFactory;
use Cycle\ORM\Collection\IlluminateCollectionFactory;
use Doctrine\Common\Collections\ArrayCollection;
use Illuminate\Support\Collection;

// Assuming $dbal is an initialized database connection instance

// Use Doctrine Collections
$factory = (new Factory($dbal))
    ->withCollectionFactory(
        'doctrine',
        new DoctrineCollectionFactory(),
        ArrayCollection::class
    );

// Use Laravel/Illuminate Collections
$factory = (new Factory($dbal))
    ->withCollectionFactory(
        'illuminate',
        new IlluminateCollectionFactory(),
        Collection::class
    );

// Specify collection type in schema
$schema = new Schema([
    'user' => [
        // ... other options
        SchemaInterface::RELATIONS => [
            'posts' => [
                Relation::TYPE => Relation::HAS_MANY,
                Relation::TARGET => 'post',
                Relation::COLLECTION_TYPE => 'doctrine', // or 'illuminate'
                Relation::SCHEMA => [
                    // ...
                ],
            ],
        ],
    ],
]);

```

--------------------------------

### Join Relations for Filtering with Cycle ORM

Source: https://context7.com/cycle/orm/llms.txt

Demonstrates using the `with()` method in Cycle ORM's Select class to join relations for filtering purposes without necessarily loading the relation data. This is useful for optimizing queries where you only need to filter based on related entity fields. Supports filtering on direct and nested relations, as well as pivot tables.

```php
<?php

use Cycle\ORM\Select;

// Filter users who have comments
$users = (new Select($orm, User::class))
    ->distinct()
    ->with('comments')
    ->fetchAll();

// Filter by related entity field
$users = (new Select($orm, User::class))
    ->with('comments')
    ->where('comments.approved', true)
    ->fetchAll();

// Nested relation filtering
$users = (new Select($orm, User::class))
    ->with('posts.comments')
    ->where('posts_comments.approved', true)
    ->fetchAll();

// Custom join alias
$users = (new Select($orm, User::class))
    ->with('posts.comments', ['as' => 'comments'])
    ->where('comments.approved', true)
    ->fetchAll();

// Many-to-many pivot table filtering
$users = (new Select($orm, User::class))
    ->with('tags')
    ->where('tags_pivot.approved', true)
    ->fetchAll();

// Combine with() and load() - filter and load
$users = (new Select($orm, User::class))
    ->with('comments')
    ->where('comments.approved', true)
    ->load('comments', [
        'using' => 'comments'  // Reuse the joined table
    ])
    ->fetchAll();

```

--------------------------------

### Define Entity Schemas with Relations and Typecasting (PHP)

Source: https://context7.com/cycle/orm/llms.txt

Defines entity schemas programmatically using Cycle ORM's Schema class. Supports defining relations (HAS_ONE, HAS_MANY, BELONGS_TO, MANY_TO_MANY), database table mappings, primary keys, column definitions, and typecasting for entity properties. This allows for a structured and code-driven approach to ORM configuration.

```php
<?php

use Cycle\ORM\Schema;
use Cycle\ORM\SchemaInterface;
use Cycle\ORM\Relation;
use Cycle\ORM\Mapper\Mapper;

$schema = new Schema([
    // User entity
    'user' => [
        SchemaInterface::ENTITY => User::class,
        SchemaInterface::MAPPER => Mapper::class,
        SchemaInterface::DATABASE => 'default',
        SchemaInterface::TABLE => 'users',
        SchemaInterface::PRIMARY_KEY => 'id',
        SchemaInterface::COLUMNS => [
            'id' => 'id',           // property => column
            'email' => 'email',
            'name' => 'name',
            'createdAt' => 'created_at',
        ],
        SchemaInterface::TYPECAST => [
            'id' => 'int',
            'createdAt' => 'datetime',
        ],
        SchemaInterface::RELATIONS => [
            'profile' => [
                Relation::TYPE => Relation::HAS_ONE,
                Relation::TARGET => 'profile',
                Relation::SCHEMA => [
                    Relation::CASCADE => true,
                    Relation::INNER_KEY => 'id',
                    Relation::OUTER_KEY => 'user_id',
                ],
            ],
            'posts' => [
                Relation::TYPE => Relation::HAS_MANY,
                Relation::TARGET => 'post',
                Relation::SCHEMA => [
                    Relation::CASCADE => true,
                    Relation::INNER_KEY => 'id',
                    Relation::OUTER_KEY => 'user_id',
                ],
            ],
        ],
    ],

    // Profile entity with belongs-to relation
    'profile' => [
        SchemaInterface::ENTITY => Profile::class,
        SchemaInterface::MAPPER => Mapper::class,
        SchemaInterface::DATABASE => 'default',
        SchemaInterface::TABLE => 'profiles',
        SchemaInterface::PRIMARY_KEY => 'id',
        SchemaInterface::COLUMNS => ['id', 'user_id', 'bio', 'avatar'],
        SchemaInterface::RELATIONS => [
            'user' => [
                Relation::TYPE => Relation::BELONGS_TO,
                Relation::TARGET => 'user',
                Relation::SCHEMA => [
                    Relation::CASCADE => true,
                    Relation::INNER_KEY => 'user_id',
                    Relation::OUTER_KEY => 'id',
                ],
            ],
        ],
    ],

    // Many-to-many relation example
    'post' => [
        SchemaInterface::ENTITY => Post::class,
        SchemaInterface::MAPPER => Mapper::class,
        SchemaInterface::DATABASE => 'default',
        SchemaInterface::TABLE => 'posts',
        SchemaInterface::PRIMARY_KEY => 'id',
        SchemaInterface::COLUMNS => ['id', 'user_id', 'title', 'content'],
        SchemaInterface::RELATIONS => [
            'tags' => [
                Relation::TYPE => Relation::MANY_TO_MANY,
                Relation::TARGET => 'tag',
                Relation::SCHEMA => [
                    Relation::CASCADE => true,
                    Relation::INNER_KEY => 'id',
                    Relation::OUTER_KEY => 'id',
                    Relation::THROUGH_ENTITY => 'post_tag',
                    Relation::THROUGH_INNER_KEY => 'post_id',
                    Relation::THROUGH_OUTER_KEY => 'tag_id',
                ],
            ],
        ],
    ],
]);

// Access schema information
$roles = $schema->getRoles();                    // ['user', 'profile', 'post', ...]
$relations = $schema->getRelations('user');      // ['profile', 'posts']
$table = $schema->define('user', SchemaInterface::TABLE);  // 'users'
```
Tokens:
Raw