immachakata / ci4-relationships
Easily add and manage database relationships in CodeIgniter 4
Requires
- php: ^7.4 || ^8.0
- codeigniter4/framework: ^4.0
Requires (Dev)
- phpunit/phpunit: ^9.6 || ^10.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 02:59:03 UTC
README
A Laravel Eloquent-style relationships package for CodeIgniter 4 Models and Entities.
CodeIgniter 4 ships with Model and Entity, but leaves relationship wiring, eager loading, pivot tables, polymorphic associations, existence filtering, and aggregates to manual joins and repetitive queries. This package adds an expressive, Laravel-compatible relationship layer directly onto standard CodeIgniter 4 Model and Entity classes—without replacing CI4's query builder, validation, casts, or soft deletes.
Table of Contents
- Beginner's Mental Model
- Why This Update Exists (What Changed & Why)
- Installation & Quick Start
- Upgrading from v1.x (Namespace & Legacy Bridge)
- 1. Defining Relationships on Models (
RelationshipsTrait) - 2. Eager Loading & Lazy Eager Loading
- 3. Querying Relationship Existence
- 4. Relationship Aggregates (Counts, Sums, Averages, Exists)
- 5. Relation Modifiers (Defaults, One-of-Many, Pivot & Morph Options)
- 6. Querying & Writing Directly Through a Relation
- 7. Polymorphic Morph Maps
- 8. Entity Support (
EntityRelationshipsTrait) - 9. Inspection & Utility Methods
- Testing
Beginner's Mental Model
If you are new to ORM relationships, here are the only four concepts you need:
- Relationship method: A method on your
Model(likepublic function posts()) that describes how this table connects to another table. - Eager loading (
with()): Instead of running 1 query to get 50 users and then 50 separate queries to get each user's posts (the N+1 problem),with('posts')fetches all 50 users in 1 query and all their posts in 1WHERE user_id IN (...)query, then stitches them together automatically. - Existence queries (
has()/whereHas()): Filter the parent table based on its children (e.g., "only give me users who have at least 1 published post"). - Entity vs Array results:
- If your Model returns
arrayorstdClass, usewith(...)to eager load relations, or$model->posts()->for($user)->...when querying/writing for a specific row. - If your Model returns an
EntityusingEntityRelationshipsTrait, you can also do$user->posts(lazy property access) and$user->posts()->create(...)directly on the entity.
- If your Model returns
Why This Update Exists (What Changed & Why)
Earlier versions of this package (v1.x) only supported basic hasOne/hasMany inside initialize() and had several hidden pitfalls in real applications:
- Method-based relationships now work (plus
initialize()backwards compatibility)
Why: Previously,with()failed unless a relation existed in both$this->relationsand as a method. Now standard Laravel-style methods (public function posts() { return $this->hasMany(...); }) work seamlessly alongside legacyinitialize()calls. - Isolated non-shared Model instances (no query builder bleed)
Why: CodeIgniter'smodel($class)returns a shared singleton by default. Reusing a shared instance across nested or consecutive eager loads leakedwhere/select/orderByclauses between queries. Every relation now spawns a fresh non-shared model instance while reusing the parent's DB connection. - Automatic
orWheregrouping inside constraints
Why: Calling->orWhere(...)inside awith(['posts' => fn ($q) => ...])closure previously broke SQL operator precedence (WHERE user_id IN (...) AND a = 1 OR b = 2), returning rows that belonged to other parents. Any constraint containingORis now wrapped in parentheses automatically. - Entity
save()andhasChanged()safety
Why: Assigning eager-loaded relations onto aCodeIgniter\Entity\Entitypreviously dirtied$attributes, making$entity->hasChanged()returntrueand causing$model->save($entity)to crash trying to save relation arrays into DB columns. Relations are now kept separate from$attributes(viaEntityRelationshipsTrait::$_relationsor synced$originalon plain entities). - Consistent return types, empty values, UUIDs, and foreign key guessing
Why: Fixed swapped$foreignKey/$localKeyarguments, fixed key guessing to use the parent's$primaryKey(including UUID/string primary keys), normalized missinghasOneresults tonull(not[]), and prevented invalidWHERE IN ()SQL when parent IDs are empty ornull. - Per-query state cleanup & circular
$withguard
Why: Activewith(),without(), and aggregate state is reset before running child queries so nested loads never inherit leftover flags, and default$witharrays guard against infinite loops on mutual relationships (User -> Profile -> User). - Consistent package namespace (
IsaacMachakata\Ci4Relationships) withv1.xcompatibility bridge
Why: Moves away from the genericCI4Extensions\Databasenamespace toIsaacMachakata\Ci4Relationshipsto match the rest of theIsaacMachakata\Ci4*ecosystem, while keeping a deprecatedCI4Extensions\Databasetrait bridge duringv2.xso existing projects don't break on upgrade.
Installation & Quick Start
composer require immachakata/ci4-relationships
<?php namespace App\Models; use CodeIgniter\Model; use IsaacMachakata\Ci4Relationships\RelationshipsTrait; class UserModel extends Model { use RelationshipsTrait; protected $table = 'users'; protected $primaryKey = 'id'; public function profile() { return $this->hasOne(ProfileModel::class); } public function posts() { return $this->hasMany(PostModel::class); } } // Fetch users with their profile and posts in 3 queries total (no N+1) $users = model(UserModel::class)->with('profile', 'posts')->findAll();
Upgrading from v1.x (Namespace & Legacy Bridge)
The primary namespace is now IsaacMachakata\Ci4Relationships (instead of CI4Extensions\Database):
// Before (v1.x) use CI4Extensions\Database\RelationshipsTrait; // Now (v2.x+) use IsaacMachakata\Ci4Relationships\RelationshipsTrait; use IsaacMachakata\Ci4Relationships\EntityRelationshipsTrait; use IsaacMachakata\Ci4Relationships\Relations\Relation; use IsaacMachakata\Ci4Relationships\Relations\Pivot;
- Zero-breakage bridge: Deprecated bridge traits for
CI4Extensions\Database\RelationshipsTraitandCI4Extensions\Database\EntityRelationshipsTraitare included throughoutv2.xso existing imports continue working immediately while you migrate (scheduled for removal inv3.0.0). - Legacy
initialize()syntax: Existing models that register relationships insideinitialize()continue to work unchanged:public function initialize() { $this->hasOne('avatar', AvatarModel::class, 'user_id'); $this->hasMany('links', LinkModel::class, 'user_id'); }
1. Defining Relationships on Models (RelationshipsTrait)
Add use RelationshipsTrait; to your CodeIgniter\Model subclass and return one of the relationship definitions below.
hasOne($related, ?string $foreignKey = null, ?string $localKey = null)
Defines a one-to-one relationship where the related table holds the foreign key pointing back to this model (e.g., profiles.user_id -> users.id). Returns a HasOne instance. Resolves to null when no matching row exists (unless withDefault() is used).
- Default keys:
$localKeydefaults to$this->primaryKey('id');$foreignKeydefaults tosingular($this->table) . '_' . $localKey('user_id'). - Example:
public function profile() { return $this->hasOne(ProfileModel::class, 'user_id', 'id'); }
- Use case / Edge case: Use when a parent may or may not have a single optional detail row (e.g.,
User -> Profile,Order -> Invoice). Even if the database accidentally contains duplicate child rows,hasOneattaches a single match; uselatestOfMany()/oldestOfMany()when multiple rows exist and you want a specific winner.
hasMany($related, ?string $foreignKey = null, ?string $localKey = null)
Defines a one-to-many relationship where each parent can own zero or more child rows (e.g., posts.user_id -> users.id). Returns a HasMany instance. Always resolves to an array ([] when empty).
- Default keys: Same as
hasOne. - Example:
public function posts() { return $this->hasMany(PostModel::class); } // You can also bake default filters or ordering into a dedicated relation method: public function publishedPosts() { return $this->hasMany(PostModel::class) ->where('status', 'published') ->orderBy('published_at', 'DESC'); }
- Use case / Edge case: Safely handles parents with
0children (returns[]), soft-deleted children (automatically excluded unlesswithDeleted()is applied), and string/UUID primary keys.
belongsTo($related, ?string $foreignKey = null, ?string $ownerKey = null, ?string $relationName = null)
Defines the inverse of hasOne or hasMany—where this model holds the foreign key pointing to the parent/owner table (e.g., posts.user_id -> users.id). Returns a BelongsTo instance.
- Default keys:
$ownerKeydefaults to the related model's$primaryKey;$foreignKeydefaults tosnakeCase($methodName) . '_' . $ownerKey(so a method namedauthor()guessesauthor_id, whileuser()guessesuser_id). - Example:
public function author() { // Method name is 'author', but column is 'user_id', so pass 'user_id' explicitly: return $this->belongsTo(UserModel::class, 'user_id', 'id'); }
- Use case / Edge case: Ideal for self-referencing trees (
CategoryModel::parent()->belongsTo(self::class, 'parent_id')) and nullable foreign keys (e.g.,posts.user_id = NULLfor guest posts—returnsnullwithout crashing SQLWHERE IN, or a fallback viawithDefault()).
belongsToMany($related, ?string $table = null, ?string $foreignPivotKey = null, ?string $relatedPivotKey = null, ?string $parentKey = null, ?string $relatedKey = null, ?string $relationName = null)
Defines a many-to-many relationship connected through an intermediate (pivot) table (e.g., users <-> role_user <-> roles). Returns a BelongsToMany instance.
- Default keys & table:
$table: Alphabetical singular join of both table names (roles+users->'role_user').$foreignPivotKey:singular($this->table) . '_' . $parentKey('user_id').$relatedPivotKey:singular($relatedTable) . '_' . $relatedKey('role_id').
- Example:
public function roles() { return $this->belongsToMany(RoleModel::class, 'role_user', 'user_id', 'role_id') ->withPivot('assigned_by', 'role_label') ->withTimestamps(); }
- Use case / Edge case: Automatically strips internal
__pivot_*aliases and hydrates cleanpivotdata onto every related item—as an associative array on array models, or as aPivotEntity ($role->pivot->role_labeland$role->pivot['role_label']) on object/Entity models.
hasOneThrough($related, $through, ?string $firstKey = null, ?string $secondKey = null, ?string $localKey = null, ?string $secondLocalKey = null)
Defines a distant one-to-one relationship accessed through an intermediate model (e.g., Country -> User -> latest Post). Returns a HasOneThrough instance.
- Key order:
$firstKey: Column on$throughpointing to$this('country_id'onusers).$secondKey: Column on$relatedpointing to$through('user_id'onposts).$localKey: Primary/local key on$this('id'oncountries).$secondLocalKey: Primary/local key on$through('id'onusers).
- Example:
public function latestPost() { return $this->hasOneThrough(PostModel::class, UserModel::class) ->orderBy('posts.id', 'DESC'); }
- Use case / Edge case: Avoids manually loading intermediate rows just to grab one related record. Automatically excludes soft-deleted intermediate
$throughrows unless->withDeletedParents()is called.
hasManyThrough($related, $through, ?string $firstKey = null, ?string $secondKey = null, ?string $localKey = null, ?string $secondLocalKey = null)
Defines a distant one-to-many relationship through an intermediate model (e.g., all Posts in a Country through User). Returns a HasManyThrough instance.
- Example:
public function posts() { return $this->hasManyThrough(PostModel::class, UserModel::class); }
- Use case / Edge case: Works cleanly with
with(),withCount('posts'),has('posts'), andwhereHas('posts', ...). Soft-deleted intermediate users are excluded automatically so deleted users' posts do not leak into country totals.
morphOne($related, string $name, ?string $type = null, ?string $id = null, ?string $localKey = null)
Defines a polymorphic one-to-one relationship where a single shared table (e.g., images) can store one record for many different model types (Post, User, Product). Returns a MorphOne instance.
- Default columns:
$typedefaults to"{$name}_type"('imageable_type');$iddefaults to"{$name}_id"('imageable_id'). - Example:
public function image() { return $this->morphOne(ImageModel::class, 'imageable'); }
- Use case / Edge case: Supports
withDefault(),ofMany(),latestOfMany(), andoldestOfMany()just likehasOne, while automatically filtering and writingimageable_type.
morphMany($related, string $name, ?string $type = null, ?string $id = null, ?string $localKey = null)
Defines a polymorphic one-to-many relationship (e.g., both PostModel and VideoModel have many CommentModel rows stored in one comments table). Returns a MorphMany instance.
- Example:
public function comments() { return $this->morphMany(CommentModel::class, 'commentable'); }
- Use case / Edge case: Creating a comment via
$post->comments()->create(['body' => 'Hi'])automatically fills bothcommentable_idandcommentable_type(respectingRelation::morphMap()).
morphTo(?string $name = null, ?string $type = null, ?string $id = null, ?string $ownerKey = null)
Defines the inverse polymorphic relationship on the shared child model (e.g., CommentModel::commentable() returning either a Post or a Video). Returns a MorphTo instance.
- Default columns:
$namedefaults to the method name ('commentable');$typedefaults to'commentable_type';$iddefaults to'commentable_id'. - Example:
// On CommentModel public function commentable() { return $this->morphTo(); }
- Use case / Edge case: Groups all comments by
commentable_typeand executes one query per distinct target model instead of one query per comment. Note: SQLhas()/whereHas()andwithCount()are intentionally disallowed onmorphTo()(throwingBadMethodCallException) because a single SQL subquery cannot target dynamic tables per row.
morphToMany($related, string $name, ?string $table = null, ?string $foreignPivotKey = null, ?string $relatedPivotKey = null, ?string $parentKey = null, ?string $relatedKey = null)
Defines a polymorphic many-to-many relationship (e.g., both PostModel and VideoModel sharing TagModel through a taggables table with tag_id, taggable_id, taggable_type). Returns a MorphToMany instance.
- Default table/keys:
$tabledefaults toplural($name)('taggables');$foreignPivotKeydefaults to"{$name}_id"('taggable_id');$relatedPivotKeydefaults tosingular($relatedTable) . '_' . $relatedKey('tag_id'). - Example:
// On PostModel & VideoModel public function tags() { return $this->morphToMany(TagModel::class, 'taggable'); }
- Use case / Edge case:
attach(),detach(),sync(), andtoggle()automatically scope bytaggable_type, so syncing tags onPost #1never deletes tags belonging toVideo #1.
morphedByMany($related, string $name, ?string $table = null, ?string $foreignPivotKey = null, ?string $relatedPivotKey = null, ?string $parentKey = null, ?string $relatedKey = null)
Defines the inverse of morphToMany (e.g., on TagModel, retrieve all Posts or all Videos that have this tag). Returns a MorphToMany instance with $inverse = true.
- Example:
// On TagModel public function posts() { return $this->morphedByMany(PostModel::class, 'taggable'); } public function videos() { return $this->morphedByMany(VideoModel::class, 'taggable'); }
- Use case / Edge case: Lets you call
$tagModel->with('posts', 'videos')->find($tagId)or$tag->posts()->count()cleanly from the shared tag model.
hasRelation(string $name): bool & resolveRelation(string $name): Relation
Introspection helpers on RelationshipsTrait.
hasRelation($name)checks whether$nameis registered in$this->relationsor exists as a non-static, zero-required-argument relation method on the child model (safely ignoring built-inCodeIgniter\Model/BaseModelmethods).resolveRelation($name)invokes or clones the relation and throwsInvalidArgumentExceptionif the relation is missing or doesn't return aRelationinstance.- Use case: Used internally by
EntityRelationshipsTraitand useful if you build generic serializers, API filters, or admin panels that inspect model relationships dynamically.
2. Eager Loading & Lazy Eager Loading
with($relations, $clause = null): self
Queues one or more relationships to be eager-loaded on the next find(), findAll(), first(), or paginate() call.
- Accepted formats:
- Single name:
->with('posts') - Multiple arguments:
->with('profile', 'posts', 'roles') - Array of names:
->with(['profile', 'posts']) - Single relation + constraint closure:
->with('posts', fn ($q) => $q->where('status', 'published')) - Array mixing dot-notation, column selection, and closures:
$countries = model(CountryModel::class)->with([ 'users:id,country_id,name', 'users.posts' => fn ($q) => $q->where('status', 'published'), 'users.posts.comments.author:id,name', ])->findAll();
- Single name:
- Use case / Edge case: When using column selection (
'users:id,country_id,name'), always include the foreign/local key columns needed to match children to parents (country_idonusers,idif children below it need it). Multiplewith()calls merge cleanly rather than overwriting each other.
withTree(array $tree): self
Merges a pre-parsed eager-load tree directly into $this->activeRelations.
- Use case: Primarily used internally to forward nested dot-notation branches (like
'posts.comments.author') down to child models without re-parsing strings.
without($relations): self
Excludes one or more relationships from the model's default $with array (or previously queued with()) for the next query only.
// UserModel has: protected array $with = ['profile', 'roles']; $users = model(UserModel::class)->without('profile')->findAll(); // or multiple: ->without(['profile', 'roles']) / ->without('profile', 'roles')
- Use case / Edge case: Useful when an endpoint needs a lightweight list without heavy default relations, while still keeping other defaults intact.
withoutRelations(): self
Disables all default $with and $withCount properties as well as any queued with()/withCount() for the next query only.
$rawUsers = model(UserModel::class)->withoutRelations()->findAll();
- Use case / Edge case: Essential in background jobs, exports, or login checks where a model defines default
$withrelations that you want to skip completely for maximum speed.
load(&$rows, $relations, $clause = null)
Eager-loads relationships onto a single row/Entity or a list of rows/Entities that were already fetched from the database (without re-querying the parent rows).
$users = $userModel->findAll(); $userModel->load($users, 'profile', 'posts'); // Also works on a single row or with a constraint closure: $user = $userModel->find(1); $userModel->load($user, 'posts', fn ($q) => $q->where('status', 'published'));
- Use case / Edge case: Useful when you only know which relations you need after inspecting the fetched records (e.g., loading extra details only if a condition in controller logic passes). Safely handles
nullor[]inputs as no-ops.
loadMissing(&$rows, $relations, $clause = null)
Same as load(), except it skips any row where the relation is already loaded—preventing duplicate database queries and preserving already-hydrated/modified data.
$userModel->loadMissing($users, 'profile', 'posts');
- Use case / Edge case: Works across partially loaded collections (e.g., row 0 already has
profile, row 1 does not—it only queries for row 1) and recurses into nested relations ('posts.comments') when the parent relation is already present.
3. Querying Relationship Existence
All existence methods add a correlated SQL EXISTS / NOT EXISTS / COUNT(*) subquery to the parent query, keeping parent rows deduplicated and pagination totals accurate.
has(string $relation, string $operator = '>=', int $count = 1, string $boolean = 'AND', ?callable $callback = null): self
Filters parent records that have a certain number of related records (defaults to at least 1). Supports dot-notation ('users.posts.comments').
// At least 1 post $users = model(UserModel::class)->has('posts')->findAll(); // At least 3 posts $users = model(UserModel::class)->has('posts', '>=', 3)->findAll(); // Exactly 2 posts $users = model(UserModel::class)->has('posts', '=', 2)->findAll();
- Use case / Edge case: Automatically uses fast
EXISTS (...)for>= 1andNOT EXISTS (...)for< 1, falling back to(SELECT COUNT(*) ...) $operator $countfor other counts. Valid operators:=,!=,<>,<,<=,>,>=(invalid operators throwInvalidArgumentException).
orHas(string $relation, string $operator = '>=', int $count = 1): self
Same as has(), joined with SQL OR instead of AND.
$users = model(UserModel::class) ->has('posts') ->orHas('videos') ->findAll();
- Use case: "Users who have created either a post OR a video."
doesntHave(string $relation, string $boolean = 'AND', ?callable $callback = null): self
Filters parent records that have zero matching related records (shorthand for has($relation, '<', 1)).
$inactiveUsers = model(UserModel::class)->doesntHave('posts')->findAll();
- Use case / Edge case: Finding orphaned or unused records (e.g., categories with no products, users with no orders). Soft-deleted child records do not count as existing, so a user whose only post was soft-deleted will properly match
doesntHave('posts').
orDoesntHave(string $relation): self
Same as doesntHave(), joined with SQL OR.
$users = model(UserModel::class) ->where('active', 0) ->orDoesntHave('profile') ->findAll();
- Use case: "Users who are inactive OR haven't completed their profile."
whereHas(string $relation, ?callable $callback = null, string $operator = '>=', int $count = 1): self
Like has(), but lets you pass a closure to filter which related records count toward existence. Supports nested dot-notation ('users.posts.comments').
$users = model(UserModel::class) ->whereHas('posts', fn ($q) => $q->where('views >', 150)) ->findAll(); // Nested dot notation: countries with at least 1 approved comment $countries = model(CountryModel::class) ->whereHas('users.posts.comments', fn ($q) => $q->where('approved', 1)) ->findAll();
- Use case / Edge case: Handles self-referencing models (
CategoryModel::whereHas('children', fn ($q) => $q->where('active', 1))) by automatically aliasing the inner table (__rel_self) so SQL doesn't complain about ambiguous table names.
orWhereHas(string $relation, ?callable $callback = null, string $operator = '>=', int $count = 1): self
Same as whereHas(), joined with SQL OR.
$users = model(UserModel::class) ->where('id', 3) ->orWhereHas('posts', fn ($q) => $q->where('views', 200)) ->findAll();
- Use case: Combining direct column filters with alternative relationship conditions.
whereDoesntHave(string $relation, ?callable $callback = null): self
Filters parent records that have no related records matching the given constraint closure.
// Users who have NO published posts (includes users with 0 posts OR only draft posts) $users = model(UserModel::class) ->whereDoesntHave('posts', fn ($q) => $q->where('status', 'published')) ->findAll();
- Use case / Edge case: Crucial difference from
whereHas(..., 'status !=', 'published')—a user with zero posts wouldn't match a positivewhereHas, whereaswhereDoesntHavecorrectly includes both users with 0 posts and users with only drafts.
orWhereDoesntHave(string $relation, ?callable $callback = null): self
Same as whereDoesntHave(), joined with SQL OR.
$users = model(UserModel::class) ->where('active', 0) ->orWhereDoesntHave('posts', fn ($q) => $q->where('status', 'published')) ->findAll();
- Use case: Auditing accounts that are disabled OR have zero published content.
4. Relationship Aggregates (Counts, Sums, Averages, Exists)
Query-Time Aggregates (Executed as SQL Subqueries)
All with* aggregate methods run as subqueries in the parent SELECT list, so you can orderBy() the resulting alias. They work alongside select() regardless of whether you call select() before or after withCount().
-
withCount($relations): self
Adds{relation}_count(cast toint,0when none). Supports custom aliases ('posts as published_count') and constraint closures:$users = model(UserModel::class) ->withCount([ 'posts', 'posts as published_posts_count' => fn ($q) => $q->where('status', 'published'), ]) ->orderBy('posts_count', 'DESC') ->findAll();
-
withSum($relations, string $column): self
Adds{relation}_sum_{column}(cast tointorfloat, ornullif no rows).$users = model(UserModel::class)->withSum('posts', 'views')->findAll(); // $users[0]['posts_sum_views']
-
withAvg($relations, string $column): self
Adds{relation}_avg_{column}(cast tofloat, ornullif no rows).$users = model(UserModel::class)->withAvg('posts', 'views')->findAll();
-
withMin($relations, string $column): self
Adds{relation}_min_{column}(ornullif no rows).$users = model(UserModel::class)->withMin('posts', 'views')->findAll();
-
withMax($relations, string $column): self
Adds{relation}_max_{column}(ornullif no rows).$users = model(UserModel::class)->withMax('posts', 'views')->findAll();
-
withExists($relations): self
Adds{relation}_exists(cast tobool:trueorfalse). Faster thanwithCount()when you only need a yes/no badge.$users = model(UserModel::class)->withExists('profile')->findAll(); // $users[0]['profile_exists'] === true
-
withAggregate($relations, string $column, ?string $function = null): self
Low-level method powering all the methods above—useful if you want a custom SQL aggregate function (e.g.,GROUP_CONCATor custom expression). -
Use case / Edge case for all
with*aggregates:- You can define
protected array $withCount = ['posts'];on a Model to attach counts by default (and suppress them withwithoutRelations()). - On Entities, aggregate fields are synced with
$originalso$entity->hasChanged()staysfalseand$model->save($entity)stays safe. - All
with*aggregates respect soft deletes on the related model.
- You can define
Lazy Aggregates (For Already-Fetched Rows or Entities)
Each with* method has a matching load* method that executes a single GROUP BY batch query against already-fetched rows/Entities:
loadCount(&$rows, $relations)— Adds{relation}_count(int).loadSum(&$rows, $relations, string $column)— Adds{relation}_sum_{column}.loadAvg(&$rows, $relations, string $column)— Adds{relation}_avg_{column}.loadMin(&$rows, $relations, string $column)— Adds{relation}_min_{column}.loadMax(&$rows, $relations, string $column)— Adds{relation}_max_{column}.loadExists(&$rows, $relations)— Adds{relation}_exists(bool).loadAggregate(&$rows, $relations, string $column, ?string $function = null)— Underlying batch aggregate loader.
$users = $userModel->findAll(); $userModel->loadCount($users, ['posts', 'roles']); $userModel->loadSum($users, 'posts', 'views'); $userModel->loadExists($users, 'profile');
- Use case / Edge case: Great when you forgot to call
withCount()during the initial query, or when loading counts conditionally after fetching a paginated result. Works identically on single rows, arrays of rows, or Entities ($user->loadCount('posts')).
5. Relation Modifiers (Defaults, One-of-Many, Pivot & Morph Options)
These methods are chained directly onto the relation object returned inside your model's relationship method (or inside a with(['rel' => fn ($rel) => ...]) closure).
withDefault($callback = true): self (HasOne, BelongsTo, MorphOne)
Returns a fallback array, stdClass, Entity, or closure result instead of null when no related record exists.
public function profile() { return $this->hasOne(ProfileModel::class)->withDefault([ 'bio' => 'No bio yet', ]); } // Or with a callback receiving ($defaultInstance, $parentRow): public function author() { return $this->belongsTo(UserModel::class, 'user_id')->withDefault(function ($user, $post) { $user['name'] = 'Guest Author'; return $user; }); }
- Use case / Edge case: Eliminates
Null Objectchecks in views ($post['author']['name']never throws an undefined offset/property error on orphaned records). Matches the related model's$returnType(array,object, orEntityclass) automatically.
ofMany($column = null, string $aggregate = 'max', ?callable $relation = null): self (HasOne, MorphOne)
Converts a one-to-many table into a one-of-many single record per parent (picking the row with the max or min value on one or more columns, with primary key tie-breaking).
public function topPost() { return $this->hasOne(PostModel::class)->ofMany('views', 'max'); } // Multi-column tie-breaker: public function currentPrice() { return $this->hasOne(PriceModel::class)->ofMany([ 'effective_at' => 'max', 'id' => 'max', ]); }
- Use case / Edge case: Fetches only the winning row per parent instead of loading thousands of historical rows into PHP. Also works inside
whereHas('topPost', ...)via an automaticNOT EXISTStie-breaker subquery.
latestOfMany($column = null): self & oldestOfMany($column = null): self (HasOne, MorphOne)
Convenient shortcuts for ofMany($column, 'max') and ofMany($column, 'min'). $column defaults to the related model's primary key ('id'). Accepts a single column name or an array of columns.
public function latestPost() { return $this->hasOne(PostModel::class)->latestOfMany(); // max(id) } public function oldestLogin() { return $this->hasOne(LoginModel::class)->oldestOfMany('logged_in_at'); }
- Use case: Getting a user's most recent order, latest status log, or first subscription without extra subqueries in your controllers.
withPivot($columns): self (BelongsToMany, MorphToMany)
Specifies additional columns from the intermediate pivot table to include in hydrated pivot data (accepts an array or variadic strings).
return $this->belongsToMany(RoleModel::class)->withPivot('assigned_by', 'role_label');
- Use case: Essential whenever your pivot table stores metadata beyond the two foreign keys (e.g.,
quantityandunit_priceonorder_product).
withTimestamps(string $createdAt = 'created_at', string $updatedAt = 'updated_at'): self (BelongsToMany, MorphToMany)
Automatically includes created_at and updated_at in pivot reads and automatically populates them during attach(), sync(), and updateExistingPivot().
return $this->belongsToMany(RoleModel::class)->withTimestamps();
- Use case / Edge case: Automatically formats timestamps according to your parent model's
$dateFormat('datetime','date', or'int').
as(string $accessor): self (BelongsToMany, MorphToMany)
Renames the pivot key/property on hydrated related items to something more descriptive.
return $this->belongsToMany(PodcastModel::class)->as('subscription')->withPivot('expires_at'); // Access via $podcast['subscription']['expires_at'] or $podcast->subscription->expires_at
- Use case: Makes domain code read naturally (
$user->podcasts[0]->subscription->expires_atinstead of->pivot->expires_at).
using(string $pivotClass): self (BelongsToMany, MorphToMany)
Uses a custom Pivot Entity subclass when hydrating object/Entity results instead of the default IsaacMachakata\Ci4Relationships\Relations\Pivot.
return $this->belongsToMany(RoleModel::class)->using(UserRolePivot::class);
- Use case: Useful when you want custom casts (
$casts), getters, or helper methods on the pivot record itself.
Pivot Filtering & Ordering (BelongsToMany, MorphToMany)
Filter or sort many-to-many results by columns on the intermediate pivot table:
wherePivot(string $column, $operator = null, $value = null, string $boolean = 'AND'): selforWherePivot(string $column, $operator = null, $value = null): selfwherePivotIn(string $column, array $values): selfwherePivotNotIn(string $column, array $values): selfwherePivotNull(string $column): selfwherePivotNotNull(string $column): selforderByPivot(string $column, string $direction = 'asc'): self
$users = model(UserModel::class)->with([ 'roles' => fn ($q) => $q->wherePivot('role_label', 'Writer')->orderByPivot('created_at', 'desc'), ])->findAll();
- Use case / Edge case: Automatically qualifies pivot column names with the pivot table name so columns like
created_atorstatusnever collide with columns of the same name on the related table.
withDeletedParents(bool $val = true): self (HasOneThrough, HasManyThrough)
Includes soft-deleted intermediate ($through) records when traversing a through relationship.
public function allPostsIncludingDeletedUsers() { return $this->hasManyThrough(PostModel::class, UserModel::class)->withDeletedParents(); }
- Use case: Compliance/audit reports where you still want to see orders belonging to archived/soft-deleted customers.
morphWith(array $with): self (MorphTo)
Specifies different nested relationships to eager-load depending on which model type each polymorphic row resolves to.
$comments = model(CommentModel::class)->with([ 'commentable' => fn ($morphTo) => $morphTo->morphWith([ PostModel::class => ['author'], VideoModel::class => ['user'], ]), ])->findAll();
- Use case / Edge case: Solves the classic polymorphic problem where
Posthasauthor()whileVideohasuser(), letting you load each type's specific relations in batches without throwing an "undefined relation" error.
for($parentRow): self (All Relations)
Binds a specific parent row (array, stdClass, or Entity) to a Relation instance so you can run direct queries or writes when your model returns arrays instead of Entities using EntityRelationshipsTrait.
$userModel = model(UserModel::class); $user = $userModel->find(1); $published = $userModel->posts()->for($user)->where('status', 'published')->findAll(); $userModel->posts()->for($user)->create(['title' => 'New Post']);
- Use case: Gives array-based and
stdClass-based models 100% of the same direct query/write capabilities as Entity models.
6. Querying & Writing Directly Through a Relation
When a relation is bound to a parent—either automatically via $entity->posts() (EntityRelationshipsTrait) or via ->for($parent)—you can chain any CodeIgniter 4 Query Builder / Model method (where, orWhere, like, orderBy, limit, withDeleted, etc.) and execute the methods below.
Direct Query Execution Methods (Relation)
toQuery(): Model
Builds and returns the configured relatedModelinstance with parent constraints and pending calls applied (without executing it yet).
Use case / Edge case: Useful for inspecting the compiled SQL ($user->posts()->toQuery()->builder()->getCompiledSelect()) or passing the configured query to custom helpers. ThrowsLogicExceptionif no parent row is bound.findAll(?int $limit = null, int $offset = 0): array
Executes the query and returns all matching related rows (hydratingpivotonBelongsToMany/MorphToManyand stripping internal__through_parent_keyonThroughrelations).get(?int $limit = null, int $offset = 0): array
Laravel-style alias forfindAll().first()
Returns the first matching related row, ornull(or default model ifwithDefault()is configured onHasOne/BelongsTo/MorphOne).find($id = null)
Finds a related record (or array of IDs) by primary key, scoped to the parent—meaning$user->posts()->find(99)returnsnullif post 99 belongs to a different user!
Use case / Edge case: Prevents IDOR (Insecure Direct Object Reference) bugs when editing/viewing a user's child record by ID.findColumn(string $columnName): ?array
Returns a flat array of values for a single column scoped to the parent (e.g.,$user->posts()->findColumn('title')).paginate(?int $perPage = null, string $group = 'default', ?int $page = null, int $segment = 0): ?array
Paginates related records scoped to the parent, setting$pageron the underlying query model.count(bool $reset = true): int&countAllResults(bool $reset = true, bool $test = false): int
Counts matching related records scoped to the parent without loading rows into PHP.exists(): bool&doesntExist(): bool
Returnstrue/falsedepending on whether at least 1 matching related record exists for the parent.sum(string $column),avg(string $column),min(string $column),max(string $column)
Runs SQLSUM,AVG,MIN, orMAXon$columnscoped to the parent (respecting soft deletes). Returnsnullif no rows match (avg()returns?float,sum()returnsint|float|null).chunk(int $size, Closure $callback): void
Processes matching related records in batches of$size, invoking the callback once per record (not once per batch). Returnfalsefrom the callback to stop early.// Process a user's posts 100 records at a time without loading them all at once. $userModel->posts()->for($user)->chunk(100, function ($post) { // Send a notification, export the row, etc. }); // An Entity relation is already bound to its parent. $user->posts()->chunk(100, function ($post) { // Stop after finding the first post that needs attention. if ($post->status === 'needs_review') { return false; } });
Use case / Edge case: Usechunk()for exports or maintenance jobs where loading every child into memory would be expensive. CodeIgniter'sModel::chunk()raises aDataExceptionwhen there are no matching rows, so checkexists()first if an empty relation is expected.update($data): bool
Mass-updates all related rows matching the relation (and any chainedwhere()calls) scoped to the parent. Accepts an array or object.// Update just the loaded post, while still ensuring it belongs to this user. $user = $userModel->with('posts')->find($userId); $post = $user['posts'][0]; $userModel->posts()->for($user) ->where('id', $post['id']) ->update(['status' => 'archived']); // Or update every draft post belonging to this Entity's user. $user->posts()->where('status', 'draft')->update(['status' => 'review']);
Use case / Edge case: Add a child ID condition when only one loaded record should change. Without it,update()changes every child matching the relation and additional filters. The parent relation constraint prevents updating a record belonging to another parent.delete($id = null, bool $purge = false): bool
Deletes related records scoped to the parent (soft-deleting automatically if the related model uses$useSoftDeletes = true, unless$purge = true).// Array/stdClass model: load the parent with its posts, then delete one post // through the parent-scoped relation. $user = $userModel->with('posts')->find($userId); $post = $user['posts'][0]; $userModel->posts()->for($user)->delete($post['id']); // Entity model using EntityRelationshipsTrait: the relation is bound to $user. $user = $userModel->with('posts')->find($userId); $post = $user->posts[0]; $user->posts()->delete($post->id);
Use case / Edge case:with('posts')only loads the posts; it does not make the loaded array/entity itself a delete operation. Deleting through the relation scopes the request to that user, so a post ID belonging to another user will not be deleted. With soft deletes enabled, this is a soft delete; passtrueas the second argument (delete($postId, true)) to permanently delete it.
HasOne, HasMany, MorphOne, MorphMany Write Methods
save($record): bool
Automatically sets the foreign key (andmorphTypeon morph relations) to the parent's key and saves$record(insert or update) via the related model.$post = ['title' => 'Saved via relation', 'status' => 'published']; $user->posts()->save($post);
saveMany(array $records): bool
Callssave()for each record in$records, returningfalseimmediately if any save fails.create(array $attributes = [])
Merges the parent's foreign key (andmorphType) into$attributes, inserts using the related model (instantiating its Entity if$returnTypeis an Entity class), and returns the newly fetched row/Entity (orfalseon validation/insert failure).$post = $user->posts()->create(['title' => 'Hello World', 'status' => 'published']);
createMany(array $records): array
Creates multiple related records in sequence and returns an array of the created rows/Entities.
BelongsTo & MorphTo Write Methods
associate($model)(BelongsTo) /associate($model, ?string $morphModelClass = null)(MorphTo)
Sets the foreign key (andmorphTypeforMorphTo) on the bound child row/Entity and caches the relation if it usesEntityRelationshipsTrait. Does not hit the DB until you$model->save($child)—matching Laravel's behavior so you can set multiple fields before oneUPDATE.// BelongsTo (accepts an Entity, array, stdClass, or raw ID): $postModel->author()->for($post)->associate($user); $postModel->save($post); // MorphTo (pass target Model class unless $target uses EntityRelationshipsTrait): $commentModel->commentable()->for($comment)->associate($post, PostModel::class); $commentModel->save($comment);
dissociate()(BelongsTo, MorphTo)
Sets the foreign key (andmorphTypeonMorphTo) tonullon the bound child row/Entity.$postModel->author()->for($post)->dissociate(); $postModel->save($post);
BelongsToMany & MorphToMany Pivot Mutation Methods
attach($ids, array $attributes = []): bool
Inserts one or more pivot rows for the parent. Accepts a single ID, an Entity/object, an array of IDs, or[id => ['pivot_col' => 'val']]. Automatically addsmorphTypeonMorphToManyand timestamps ifwithTimestamps()is enabled.$user->roles()->attach(1); $user->roles()->attach([1, 2 => ['role_label' => 'Lead']], ['assigned_by' => 99]);
detach($ids = null): int
Removes specific related IDs (or all pivot records for this parent if$ids === null) and returns the number of affected rows. OnMorphToMany, safely restricts deletion to$this->morphType = $this->morphClass.sync(array $ids, bool $detaching = true): array
Synchronizes the pivot table so only the given IDs remain attached. Supports[1, 2 => ['role_label' => 'Editor']]. Returns['attached' => [...], 'detached' => [...], 'updated' => [...]]. Use case / Edge case: Ideal for multi-select checkboxes in forms—you pass the submitted role IDs andsync()computes the exact inserts, deletes, and pivot attribute updates automatically.syncWithoutDetaching(array $ids): array
Shortcut forsync($ids, false)—attaches new IDs and updates existing pivot attributes without removing anything already attached.toggle($ids): array
Attaches IDs that aren't currently attached and detaches IDs that already are. Returns['attached' => [...], 'detached' => [...]]. Use case: Like/bookmark/favorite toggles or feature-flag opt-ins.updateExistingPivot($id, array $attributes): bool
Updates extra pivot columns on an existing pivot link for$id(automatically refreshingupdated_atwhenwithTimestamps()is enabled).
7. Polymorphic Morph Maps
Static methods on IsaacMachakata\Ci4Relationships\Relations\Relation:
Relation::morphMap(?array $map = null, bool $merge = true): array
Registers (or retrieves) a mapping between short string aliases and Model FQCNs.Relation::morphMap([ 'post' => PostModel::class, 'video' => VideoModel::class, ]);
Relation::enforceMorphMap(array $map, bool $merge = true): array
Registers the morph map and enforces that every polymorphic model has an alias (throwingInvalidArgumentExceptionif an unmapped model is used). Use case / Edge case: Put this inConfig\Boot\production.phporBaseControllerso refactoring namespaces never breaks existing database rows, and unmapped models fail loudly during development/tests.Relation::requiresMorphMap(?bool $value = null): bool
Gets or sets whether a morph map is required.Relation::getMorphedModel(string $alias): ?string
Returns the Model FQCN for an alias, ornullif not mapped.Relation::getMorphAlias(string $class): string
Returns the alias for a Model FQCN (or the FQCN itself if not enforced, or throws ifenforceMorphMapis active).
8. Entity Support (EntityRelationshipsTrait)
Add use EntityRelationshipsTrait; to any CodeIgniter\Entity\Entity subclass to unlock Laravel-style object access:
<?php namespace App\Entities; use CodeIgniter\Entity\Entity; use IsaacMachakata\Ci4Relationships\EntityRelationshipsTrait; class User extends Entity { use EntityRelationshipsTrait; }
Magic Property & Method Access
$entity->relationName(__get,__set,__isset,__unset)
If the relation is already loaded in$_relations, returns it immediately. Otherwise, lazily executes the query once, caches the result in$_relations, and returns it. Setting or unsetting a relation stores/removes it in$_relationswithout touching$attributes.
Edge case: Real columns,datamapaliases, and customget*()getters always take priority over relation lookup.$entity->relationName()(__call)
Returns the parent-boundRelationinstance (->for($this)) so you can chain query builder methods ($user->posts()->where('status', 'published')->findAll()) or writes ($user->posts()->create(...),$user->roles()->sync([1, 2])).
Entity Methods
load($relations): self— Lazy-loads one or more relations onto this entity ($user->load('profile', 'posts')).loadMissing($relations): self— Loads relations onto this entity only if not already loaded.loadCount($relations): self— Lazy-loads{relation}_countonto this entity.relationLoaded(string $name): bool— Returnstrueif$namehas already been loaded on this entity (even if its value isnullor[]).getRelation(string $name)— Returns the loaded relation value without triggering lazy loading (nullif unloaded).getRelations(): array— Returns the entire$_relationsarray.setRelation(string $name, $value): self— Manually assigns a relation value in$_relationswithout dirtyinghasChanged().setRelations(array $relations): self— Replaces all loaded relations at once.unsetRelation(string $name): self— Clears a cached relation (the next property access will re-query if needed).setModelClass(string $modelClass, $connection = null): self&getModelClass(): ?string
Automatically called byRelationshipsTraitwhenever a model loads the entity so the entity knows which model defines its relations. If you instantiate an entity manually (new User(['id' => 1])) without querying through a model first, you can setprotected string $modelClass = UserModel::class;on the entity or call$user->setModelClass(UserModel::class).toArray(bool $onlyChanged = false, bool $cast = true, bool $recursive = false): array
When$onlyChanged === false, merges loaded relations recursively into the output array (sojson_encode($user)includes loaded relations automatically). When$onlyChanged === true, excludes relations.toRawArray(bool $onlyChanged = false, bool $recursive = false): array(inherited from CI4Entity)
Reads$attributesonly, meaningModel::save($entity)never accidentally includes loaded relations inINSERT/UPDATEqueries.
9. Inspection & Utility Methods
On Relation Instances
Useful when inspecting relation metadata or building custom tooling:
getParent(): Model— Returns the parent model instance.getRelatedClass(): string— Returns the related model class name.getRelated(): Model— Returns (and lazily creates) the related model instance.newRelatedInstance(): Model— Creates a fresh non-shared related model instance.getRelationName(): string/setRelationName(string $name): self— Gets or sets the relation's property name.setSelectedColumns(?array $columns): self— Sets columns to select during eager loading.- Key getters:
HasOneOrMany:getForeignKeyName(),getLocalKeyName()BelongsTo:getForeignKeyName(),getOwnerKeyName()BelongsToMany:getTable(),getForeignPivotKeyName(),getRelatedPivotKeyName(),getParentKeyName(),getRelatedKeyName()MorphOneOrMany:getMorphType(),getMorphClass()(plusgetForeignKeyName(),getLocalKeyName())MorphTo:getMorphType(),getForeignKeyName()MorphToMany:getMorphType(),getMorphClass()(plus allBelongsToManygetters)
PivotEntity (IsaacMachakata\Ci4Relationships\Relations\Pivot):getTable(): ?string— Returns the pivot table name.- Implements
ArrayAccess(offsetExists,offsetGet,offsetSet,offsetUnset) so pivot data works identically as$item->pivot->color$item->pivot['col'].
Testing
The package includes a comprehensive PHPUnit test suite backed by an in-memory SQLite database covering all relation types, nested eager loading, N+1 query count assertions, soft deletes, UUID keys, aggregates, existence queries, and Entity operations:
composer test
Credits
Originally forked from michalsn/codeigniter-nested-model then later heavily updated with Gemini Hydrogen for v2.