PHPackages                             mashirou1234/laravel-when-on-relation - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. mashirou1234/laravel-when-on-relation

ActiveLibrary[Database & ORM](/categories/database)

mashirou1234/laravel-when-on-relation
=====================================

Adds conditional callbacks on Laravel Eloquent relationship instances.

v0.1.0(1mo ago)02MITPHPPHP ^8.3CI passing

Since May 31Pushed 1mo agoCompare

[ Source](https://github.com/mashirou1234/laravel-when-on-relation)[ Packagist](https://packagist.org/packages/mashirou1234/laravel-when-on-relation)[ Docs](https://github.com/mashirou1234/laravel-when-on-relation)[ RSS](/packages/mashirou1234-laravel-when-on-relation/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (5)Versions (2)Used By (0)

Laravel When On Relation
========================

[](#laravel-when-on-relation)

[![Latest Version on Packagist](https://camo.githubusercontent.com/1fc1f1392ece2fee5d4d73093152873e4a0d114a63438b936c418d3f9904cd15/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d61736869726f75313233342f6c61726176656c2d7768656e2d6f6e2d72656c6174696f6e2e737667)](https://packagist.org/packages/mashirou1234/laravel-when-on-relation)[![Tests](https://github.com/mashirou1234/laravel-when-on-relation/actions/workflows/tests.yml/badge.svg)](https://github.com/mashirou1234/laravel-when-on-relation/actions/workflows/tests.yml)[![License](https://camo.githubusercontent.com/a52b2aa3549af29952f619b311f3b4e1b5cb12cdf009e40649d79f62924cf386/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6d61736869726f75313233342f6c61726176656c2d7768656e2d6f6e2d72656c6174696f6e2e737667)](LICENSE.md)

This package adds a `whenOnRelation()` macro to Eloquent relationship instances.

Installation
------------

[](#installation)

```
composer require mashirou1234/laravel-when-on-relation
```

The service provider is registered automatically by Laravel package discovery.

Usage
-----

[](#usage)

It is intended for cases where a conditional callback needs the relationship instance itself:

```
use Illuminate\Database\Eloquent\Relations\BelongsToMany;

$user->posts()
    ->whenOnRelation($condition, function (BelongsToMany $relation) {
        return $relation->wherePivotIn('post_id', [1, 2]);
    });
```

The callback receives the relationship instance and the resolved condition value:

```
$user->posts()
    ->whenOnRelation($roleId, function (BelongsToMany $relation, int $roleId) {
        return $relation->wherePivot('role_id', $roleId);
    });
```

This package does not add a query builder method that accepts a relationship name:

```
// Not supported:
User::query()->whenOnRelation('posts', ...);
```

Why
---

[](#why)

Calling `when()` on an Eloquent relationship is forwarded to the underlying Eloquent builder. That keeps existing callbacks working, but it means the callback receives an `Illuminate\Database\Eloquent\Builder` instead of the relationship instance.

`whenOnRelation()` leaves the existing `when()` behavior unchanged and provides an opt-in helper for relation-specific methods such as `wherePivotIn()`.

Requirements
------------

[](#requirements)

- PHP 8.3 or higher
- Laravel 13.x / Illuminate 13.x

Testing
-------

[](#testing)

```
composer test
```

Run `composer lint` to check formatting.

Please see [CONTRIBUTING.md](CONTRIBUTING.md) before proposing behavior changes. Security reporting is covered in [SECURITY.md](SECURITY.md).

License
-------

[](#license)

The MIT License (MIT).

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance89

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

55d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/29796060?v=4)[Mashirou](/maintainers/mashirou1234)[@mashirou1234](https://github.com/mashirou1234)

---

Top Contributors

[![mashirou1234](https://avatars.githubusercontent.com/u/29796060?v=4)](https://github.com/mashirou1234 "mashirou1234 (4 commits)")

---

Tags

composereloquentlaravelphprelationlaraveleloquentrelationwhen

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/mashirou1234-laravel-when-on-relation/health.svg)

```
[![Health](https://phpackages.com/badges/mashirou1234-laravel-when-on-relation/health.svg)](https://phpackages.com/packages/mashirou1234-laravel-when-on-relation)
```

###  Alternatives

[mongodb/laravel-mongodb

A MongoDB based Eloquent model and Query builder for Laravel

7.1k8.4M98](/packages/mongodb-laravel-mongodb)[kirschbaum-development/eloquent-power-joins

The Laravel magic applied to joins.

1.6k32.6M46](/packages/kirschbaum-development-eloquent-power-joins)[psalm/plugin-laravel

Psalm plugin for Laravel

3345.3M347](/packages/psalm-plugin-laravel)[yajra/laravel-oci8

Oracle DB driver for Laravel via OCI8

8793.2M25](/packages/yajra-laravel-oci8)[glushkovds/phpclickhouse-laravel

Adapter of the most popular library https://github.com/smi2/phpClickHouse to Laravel

2051.5M2](/packages/glushkovds-phpclickhouse-laravel)[reedware/laravel-relation-joins

Adds the ability to join on a relationship by name.

2111.3M18](/packages/reedware-laravel-relation-joins)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)