Cycle ORM

Cycle is a PHP DataMapper, ORM, and Data Modelling engine. It is specifically designed to work safely in both classic PHP environments and long-running, daemonized PHP applications (such as those powered by RoadRunner).

Key capabilities include:

• Data Modeling: Supports various relation types (has-one, has-many, many-through-many, polymorphic), embedded entities, and single table inheritance.
• Object Support: Works with Plain Old PHP Objects (POPOs), Active Record, custom objects, or even classless entities.
• Querying: Provides a powerful query builder with multiple fetch strategies, including eager and lazy loading.
• Architecture: Designed for long-running processes using an immutable service core and a disposable Unit of Work (UoW).
• Database Support: Compatible with MySQL, MariaDB, PostgreSQL, SQL Server, and SQLite.
• Extensibility: Supports custom column types, custom mappers, relations, and persist strategies. It is compatible with PHP8 attributes and Doctrine Annotations.

You can use the Repository to select entities with specific criteria and pre-load related collections. Pre-loading can be configured to use a single query (via LEFT JOIN) or separate queries. This example demonstrates fetching active users and pre-loading their paid orders, sorted by creation time.

To persist changes, use the EntityManager to persist() the fetched entities and then call run() to execute the unit of work.

// 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();

When using Cycle\ORM\Select::load(), you can pass an instance of JoinableLoadOptions to control how related data is fetched. This class allows you to specify the loading method (JOIN vs separate query), apply custom scopes, set table aliases, or reuse existing joins to optimize performance.

Key Configuration Properties

• method: Determines the SQL strategy for loading the relation.
  • LoadMethod::SingleQuery: Performs an INLOAD (joins the relation into the parent query).
  • LoadMethod::OuterQuery: Performs a POSTLOAD (executes a separate SELECT query).
  • JoinMethod::InnerJoin: Performs an INNER JOIN (useful for filtering, but does not eager-load the data).
  • JoinMethod::LeftJoin: Performs a LEFT JOIN.
  • null: Uses the default loader configuration for that specific relation.
• scope: Controls the query scope applied to the relation.
  • true: Uses the default scope defined on the relation source.
  • false: Disables all scopes (e.g., to include soft-deleted rows).
  • ScopeInterface: An instance of a custom scope.
• as: A custom table alias for the relation in the generated SQL (e.g., 'rel').
• using: Reuses an alias defined by another relation (typically from a previous with() call) instead of generating a new JOIN or query. This prevents duplicate JOINs.
• table: Overrides the default table name used for loading the related entities.
• minify: A boolean (default true) that, when true, minifies loader column aliases in the SQL output. Use with caution as disabling this may cause column name conflicts.

The where() method allows for complex filtering using several syntaxes:

• Simple equality/comparison: where('column', 'value') or where('column', '>', 10).
• BETWEEN: where('column', 'between', from, to).
• Array syntax: where(['id' => 2]) or where(['id' => ['>' => 0, '<' => 3]]).
• Logical grouping: Use @or or @AND keys in an array, or use closures for nested logic.
• Raw SQL: Use Cycle\Database\Injection\Fragment for fragments with parameters or Cycle\Database\Injection\Expression for column-to-column comparisons.
• JSON filtering: Use whereJson(), whereJsonContains(), whereJsonContainsKey(), etc., to query JSON fields.

// Operator comparison
$select->where('level', '>=', 10);

// BETWEEN
$select->where('comments.id', 'between', 1, 4);

// Array syntax with operators
$select->where(['comments.id' => ['between' => [1, 4]]]);

// Logical grouping with @or
$select->where([
    "@or" => [
        ['comments.message' => 'msg 1'],
        ['comments.message' => 'msg 3'],
    ],
]);

// Nested logic with closures
$select->where(function (\Cycle\ORM\Select\QueryBuilder $q): void {
    $q->where('comments.message', 'msg 3')
      ->orWhere(function (\Cycle\ORM\Select\QueryBuilder $q): void {
          $q->where('id', 1);
      });
});

// JSON path filtering
$select->whereJson('settings->theme', 'dark');