Weave Code
Compoships Laravel Package
awobaz/compoships
Compoships adds composite-key relationship support to Laravel's Eloquent ORM, letting you define hasMany, belongsTo and other relations that match two or more columns. Ideal for third-party or legacy schemas; use the Model base class or the Compoships trait.
Compoships is a Laravel package that enables Eloquent relationships across multiple columns, a common need when working with legacy or third-party schemas that lack single-column foreign keys. It solves eager-loading failures caused by standard where clauses and supports composite-key matching without changing Eloquent’s core behavior.
- Define hasMany, belongsTo, and other relationships using two or more columns
- Works correctly with eager loading
- Extend
Awobaz\Compoships\Database\Eloquent\Modelor use theComposhipstrait - Ideal for pre-existing databases and composite keys
Frequently asked questions about Compoships
- How do I install Compoships in a Laravel application?
- Install it with composer require awobaz/compoships, then either extend the Awobaz Compoships Model base class in your models or add the Compoships trait to each model involved in a composite relationship. No service provider registration and no configuration file are required, so a pilot can be running the same day you install it.
- Which Eloquent relationship types does Compoships support?
- Compoships covers hasOne, hasMany, belongsTo and belongsToMany relationships defined across two or more columns, including eager loading via with(). Those four cover the realistic legacy and third-party schema cases, which makes the package reasonably complete for most teams.
- Does Compoships work with eager loading?
- Yes, eager loading is the primary reason the package exists. Composite eager loads generate cross-product-style predicates, so row count multiplied by key arity drives parameter counts and overall query cost. Benchmark it with large parent collections before putting it on a high-traffic path.
- Why does where('team_id', $this->team_id) fail inside an Eloquent relationship?
- During eager loading Eloquent builds the relationship query before parent models are hydrated, so $this->team_id is null when the where clause is evaluated. Compoships solves this by overriding the relation's key-matching internals, such as getRelationExistenceQuery, so parent key values are injected correctly for each batch of models.
- Do both models need to use the Compoships trait or base model?
- Yes. Both sides of any composite relationship must opt in, either by using the trait or by extending the Awobaz base model. That is a hard invariant of the package, so enforce it with static analysis or a code review rule rather than relying on team convention.
- Which Laravel and PHP versions does Compoships support?
- The README does not publish an explicit compatibility matrix, so check the composer.json constraints and the repository CI configuration before committing. Because the package overrides Framework internals like setKeysForSaveQuery and setKeysForSelectQuery, which Laravel minor releases have historically moved, run your own CI matrix against every Laravel and PHP version in your support window.
- Does Compoships support composite primary keys for saves and deletes?
- Yes. Defining a $compositeKey property enables composite primary key write paths covering save, delete, soft deletes and refresh. A misdeclared key throws InvalidUsageException, but a syntactically valid yet semantically wrong declaration can update or delete the wrong row, so strongly prefer read-only relationships for an initial rollout.
- How are nullable columns handled in composite relationships?
- Version 2.x changed the behavior for nullable columns and is explicitly flagged as potentially breaking, and relationships where every key value is null are not currently supported. That failure is data-dependent, so no static check will catch it. Audit your target tables for nullable discriminators and estimate how many rows would fall into the all-null case.
- Can I use Compoships with model factories and queued jobs?
- Yes to both, with caveats. ComposhipsFactory supports composite keys in model factories, which is where teams most often break things silently. The package also ships a QueueableCompositeCollection wrapper for queue serialization; be aware that queueing a plain Collection instead restores an empty collection, a documented failure mode worth testing explicitly.
- Is Compoships production ready, and what are the alternatives?
- It is a small single-maintainer package, roughly a few hundred lines across relation subclasses, with solid star counts but no verified dependent count, so treat adoption at scale as unverified. Validate it with a CI matrix, confirm target tables have matching composite indexes in the correct column order, and keep a fork-and-patch contingency since forking cost is low. Eloquent has no built-in equivalent, so the real choice is this package, a custom relation subclass, or restructuring the schema.
Weaver
How can I help you explore Laravel packages today?