Weave Code
Compoships Laravel Package
awobaz/compoships
Adds composite-key relationship support to Laravel Eloquent. Define hasOne/hasMany/belongsTo relations matching two or more columns so eager loading works with legacy or third‑party schemas, using a custom base Model or Compoships trait.
Multi-columns relationships for Laravel's Eloquent ORM
Frequently asked questions about Compoships
- How do I define a hasMany relationship with two foreign keys in Laravel using Compoships?
- Use the `hasComposhipsMany()` method and specify the composite foreign keys. For example, `return $this->hasComposhipsMany(Task::class, 'user_id', 'team_id', 'user_id', 'team_id');` where the first two args are the local model’s composite keys and the last two are the foreign keys on the related model.
- Does Compoships work with Laravel 13? What’s the latest stable version?
- Yes, Compoships supports Laravel 13 up to version 2.5.5. Always pin to a specific version (e.g., `2.5.5`) in your `composer.json` to avoid compatibility issues. Check the [GitHub releases](https://github.com/topclaudy/compoships/releases) for updates.
- Can I use Compoships with belongsTo relationships?
- Yes, Compoships supports `belongsComposhipsTo()` for inverse relationships. Example: `return $this->belongsComposhipsTo(User::class, 'user_id', 'team_id', 'id', 'team_id');` where the first two args are the foreign keys on your model, and the last two are the local model’s primary keys.
- Will Compoships break eager loading (e.g., `with()`) for composite relationships?
- No, Compoships preserves eager loading functionality. Relationships defined with `hasComposhipsMany()` or `belongsComposhipsTo()` will work seamlessly with `with()`, `load()`, or `withCount()`. Test with `DB::enableQueryLog()` to verify query generation.
- What if my composite foreign keys include nullable columns? Does Compoships handle partial nulls?
- Compoships allows partial nulls in composite keys (e.g., one column nullable, another not). However, it **does not support** cases where *all* composite keys are null. If your schema requires this, adjust the database constraints or use a surrogate key instead.
- How do I test models using Compoships in PHPUnit?
- Use the `ComposhipsFactory` trait in your model factories to generate composite relationships. Example: `public function definition(): array { return ['user_id' => 1, 'team_id' => 2]; }`. For testing, extend `ComposhipsFactory` in your factories and use `create()` or `factory()->create()` as usual.
- Are there performance considerations when using composite keys with Compoships?
- Yes, **indexing is critical**. Ensure your composite foreign keys are indexed in the database (e.g., `ALTER TABLE tasks ADD INDEX (user_id, team_id)`). Without indexes, queries will perform poorly. Use `DB::enableQueryLog()` to audit generated SQL for missing indexes.
- Can I mix Compoships with other Eloquent extensions (e.g., Spatie’s activity log)?
- Generally yes, but test for conflicts. Compoships modifies relationship definitions but doesn’t interfere with query scopes or observers. If using Spatie’s `laravel-activitylog`, ensure your composite relationships are defined *before* activity log hooks to avoid query overrides.
- What’s the upgrade path if I later normalize my schema (e.g., add surrogate keys)?
- Compoships is designed for temporary use. Once you normalize (e.g., replace composite keys with a single `id`), remove the Compoships trait/base class and revert to standard Eloquent relationships. Use feature flags or database migrations to phase out composite dependencies gradually.
- Does Compoships support polymorphic relationships or belongsToMany?
- No, Compoships currently only supports `hasOne`, `hasMany`, and `belongsTo` variants (e.g., `hasComposhipsMany`, `belongsComposhipsTo`). Polymorphic or many-to-many relationships require custom implementations or schema changes. Track [GitHub issues](https://github.com/topclaudy/compoships/issues) for future support.
Weaver
How can I help you explore Laravel packages today?