Eloquent JSON Relations

Eloquent JSON Relations extends Laravel’s Eloquent ORM with relationship types that resolve foreign keys stored inside JSON columns rather than in their own columns. It adds JSON-aware variants of BelongsTo, HasOne, HasMany, HasOneThrough, HasManyThrough, MorphTo, MorphOne, and MorphMany, plus two new relationship types (BelongsToJson and HasManyJson) for many-to-many associations stored as JSON arrays of IDs or objects, with no pivot table required.

The package is a drop-in trait (HasJsonRelationships) applied to Eloquent models, and it ships dialect-specific query grammars for MySQL, MariaDB, PostgreSQL, SQLite, and SQL Server so the underlying JSON path extraction compiles to the correct SQL for each database. It is widely used in Laravel applications that store loosely-structured or denormalized relationship data (settings blobs, tag arrays, flexible pivot metadata) but still want first-class Eloquent relationship semantics like eager loading and query constraints.

What You Get

• JSON-aware versions of BelongsTo, HasOne, HasMany, HasOneThrough, HasManyThrough, MorphTo, MorphOne, and MorphMany
• New BelongsToJson and HasManyJson relationship types for many-to-many associations stored as JSON arrays, with attach/detach/sync/toggle support
• Support for JSON arrays of plain IDs or arrays of objects with extra pivot-style attributes
• Composite JSON keys for matching on multiple columns at once
• Dialect-specific query grammars for MySQL, MariaDB, PostgreSQL, SQLite, and SQL Server so JSON path queries compile correctly per database
• Has-many-through relationships across a JSON-keyed intermediate table when paired with eloquent-has-many-deep

Common Use Cases

• Modeling a many-to-many relationship (e.g. users to roles) as a JSON array column instead of maintaining a separate pivot table
• Resolving a foreign key that is nested inside a JSON settings/options blob on an existing table
• Storing pivot-style metadata (like an ‘active’ flag) alongside each related ID inside a JSON array of objects
• Adding referential integrity to JSON-keyed relationships via generated/computed columns on MySQL, MariaDB, or SQL Server
• Indexing JSON-keyed relationship columns with MySQL multi-valued indexes or PostgreSQL GIN indexes for query performance

Under The Hood

Architecture The package centers on the HasJsonRelationships trait, which overrides getAttribute/getAttributeValue so -> and [] path syntax in a relationship’s foreign-key string is parsed into a JSON accessor rather than a plain column name, then dispatches to JSON-aware relation classes (BelongsToJson, HasManyJson, HasOneJson, plus JSON variants of the standard Eloquent relation types) under src/Relations/. A parallel src/Relations/Postgres/ namespace overrides query compilation specifically for PostgreSQL’s jsonb operators, since its JSON path syntax diverges from MySQL/SQLite. Tech Stack Pure PHP 8.3+ targeting Laravel 13’s illuminate/database, with an optional dependency on the companion eloquent-has-many-deep package for has-many-through chains; dev tooling runs PHPStan at level 10, PHPUnit 12 via Orchestra Testbench, and Docker Compose services for exercising MySQL, MariaDB, PostgreSQL, and SQL Server in CI. Code Quality The 45 test files under tests/ are organized per relationship type and per database dialect, and the phpstan.neon.dist config enforces the strictest analysis level, indicating a codebase that takes type safety and cross-database correctness seriously; the IsJsonRelation trait centralizes shared query-building logic to avoid duplicating JSON path handling across relation classes. API Design The public API deliberately mirrors native Eloquent relationship method names (belongsToJson, hasManyJson, hasOneJson) and requires only adding the HasJsonRelationships trait to a model, so existing Eloquent knowledge (eager loading, query constraints, attach/detach/sync) transfers directly with minimal new concepts to learn.