Compoships

Compoships extends Laravel’s Eloquent ORM with support for relationships defined across two or more columns. Eloquent natively assumes a single foreign key, which makes it awkward to model legacy or third-party schemas that key records on composite columns; Compoships fills that gap by letting relationship methods match on arrays of columns.

Applied via a trait on your models, it overrides Eloquent’s relationship builders so hasMany, hasOne, belongsTo, and belongsToMany accept multiple foreign and local keys while preserving eager loading and query constraints. This keeps composite-key associations working the same way single-key relationships do, without dropping into raw SQL or manual where clauses.

What You Get

• A model trait that enables composite-key relationship definitions
• Array-based foreign and local keys for hasMany, hasOne, belongsTo, and belongsToMany
• Correct eager loading of multi-column relationships
• Backed-enum value resolution for composite keys
• Compatibility with modern Laravel and Eloquent versions

Common Use Cases

• Mapping relationships against legacy databases that use composite keys
• Modeling tenant- or team-scoped associations keyed by more than one column
• Integrating with third-party schemas that lack single surrogate keys

Under The Hood

Architecture - The package centers on a Compoships trait that models use. The trait overrides Eloquent hooks like getAttribute() and qualifyColumn() to accept arrays of columns, and pulls in a HasRelationships concern that supplies composite-key-aware versions of Eloquent’s relationship builders. Custom Relations classes (BelongsTo, BelongsToMany, etc.) and a custom query Builder extend Laravel’s own to add matching WHERE conditions per key column, with database-specific grammar classes (MySQL, MariaDB, Postgres, SQLite, SQL Server) handling dialect differences.

Tech Stack - Pure PHP (php ^8.2) built directly on illuminate/database (Laravel 12/13), PSR-4 autoloaded under Awobaz\Compoships. Development uses PHPUnit 11/12, FakerPHP, and a shell-driven test matrix (run-matrix-tests.sh) to validate against multiple Laravel versions.

Code Quality - The code is small, focused, and closely tracks Eloquent internals, overriding just the methods needed to thread array keys through attribute access, query building, and eager loading. A dedicated tests/ suite with model factories exercises the relationship types across SQLite, and per-grammar classes show attention to cross-database correctness. Because it hooks deep into Eloquent, upgrades require the maintained version matrix to stay green.

API Design - Adoption is nearly frictionless: add the trait, then pass arrays instead of strings as the foreign/local keys in ordinary hasMany/belongsTo calls. The public surface is unchanged from stock Eloquent, so developers reuse familiar relationship syntax and only the key arguments differ, keeping the learning curve minimal.