PHPackages                             stellarwp/field-conditions - 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. [Utility & Helpers](/categories/utility)
4. /
5. stellarwp/field-conditions

ActiveLibrary[Utility & Helpers](/categories/utility)

stellarwp/field-conditions
==========================

A set of serializable classes for handling conditional logic for fields in PHP

1.1.1(3y ago)4606.1k—7%[1 issues](https://github.com/stellarwp/field-conditions/issues)1GPL-2.0-or-laterPHP

Since Feb 9Pushed 2y ago7 watchersCompare

[ Source](https://github.com/stellarwp/field-conditions)[ Packagist](https://packagist.org/packages/stellarwp/field-conditions)[ RSS](/packages/stellarwp-field-conditions/feed)WikiDiscussions develop Synced 2d ago

READMEChangelog (3)Dependencies (4)Versions (5)Used By (1)

Introduction
============

[](#introduction)

This is a small PHP library for defining and processing field conditions. By "field" conditions we're referring to conditions for use with a set of fields, such as a form. A field condition consists of a field name, a comparison operator, the value to compare against, and the logical operator to use when combining multiple conditions. For example:

```
$condition = new FieldCondition('name', '=', 'John', 'and');
```

This condition would be true if the value of the field named "name" is equal to "John".

Finally, all conditions can be serialized into JSON. The intended scenario is for passing said conditions to the front-end to be used in JavaScript. Simply use the `json_encode()`function to serialize the condition or condition set.

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

[](#installation)

It is recommended to install this library using [Composer](https://getcomposer.org/). To do so, run the following command:

```
composer require stellarwp/field-conditions
```

If using this in WordPress, it is strongly recommended that you [use Strauss](https://github.com/stellarwp/global-docs/blob/main/docs/strauss-setup.md)to avoid conflicts with other plugins.

### Configuration

[](#configuration)

The library includes a `Config` class which can be used for setting configuration options. At this time, the only configuration is the ability to override the `InvalidArgumentException`, in case you need your own exception to be used here.

```
use StellarWP\FieldConditions\Config;

Config::setInvalidArgumentExceptionClass(MyInvalidArgumentException::class);
```

How to use
----------

[](#how-to-use)

Typically, conditions will be stored within a `ConditionSet` object. This object tracks the conditions and provides methods for determining whether the conditions pass or fail a given set of data.

There are two types of conditions:

- `FieldCondition` - A condition that compares a field value to a given value.
- `NestedCondition` - A condition that contains other conditions.

There are two types of condition sets:

- `SimpleConditionSet` - A flat set of FieldConditions
- `ComplexConditionSet` - An infinitely deep set of FieldConditions and NestedConditions

### Defining your conditions

[](#defining-your-conditions)

First, you will want to instantiate your condition set. If you only want a flat set of conditions that cannot be nested, then use a `SimpleConditionSet`. Otherwise, use a `ComplexConditionSet`.

Next, you can pass your conditions to the condition set:

```
use StellarWP\FieldConditions\ComplexConditionSet;
use StellarWP\FieldConditions\FieldCondition;
use StellarWP\FieldConditions\NestedCondition;
use StellarWP\FieldConditions\SimpleConditionSet;

$simpleSet = new SimpleConditionSet(); // you can pass conditions here as well

$simpleSet
    ->where('name', '=', 'John')
    ->and('age', '>', 18)
    ->or('age', '', 18)
    ->or(function(NestedCondition $condition) {
        $condition
            ->where('name', '=', 'Jane')
            ->and('age', '>', 21);
    });
```

Condition instances can also be passed to the `where`, `and`, and `or` methods. Note that the logical operator in the condition will be overwritten by the method used.

```
$conditionSet = new SimpleConditionSet();

$nestedCondition = new NestedCondition();

$conditionSet
    ->where(new FieldCondition('name', '=', 'John'));
    ->and($nestedCondition);
```

It's also possible to append conditions to an existing condition set:

```
$conditionSet = new SimpleConditionSet();
$conditionSet->append(
    new FieldCondition('name', '=', 'John'),
    new FieldCondition('age', '>', 18)
);
```

### Checking values against conditions

[](#checking-values-against-conditions)

Once you have your condition set, you will want to pass values to the condition set to check whether the given data passes the set of conditions.

```
$data = [
    'name' => 'John',
    'age' => 19,
];

$simpleSet
    ->where('name', '=', 'John')
    ->and('age', '>', 18);

$conditionSet->passes($data); // true
$conditionSet->fails($data); // false
```

### A note about logical operators (and/or) in conditions

[](#a-note-about-logical-operators-andor-in-conditions)

One thing that may be confusing is how logical operations work in conditions. Consider the following:

```
$conditionSet = new SimpleConditionSet(
    new FieldCondition('name', '=', 'John'),
    new FieldCondition('age', '>', 18, 'or')
);
```

Logically, this reads as "name equals John OR age is greater than 18". What makes this feel strange is that the logical operator appears at the end of the second condition. This makes it feel like the OR is being applied to the end of the second condition. In reality, the OR is being applied to the start of the condition.

The logical operator is applied to the start of the condition, as the logical operation applies to the current condition, not the next. This is why the typical way to write the sets is using the `where()`, `and()`, and `or()` methods, so it feels more natural.

Lastly, the default logical operator is AND, so it is only necessary to specify the logical operator when using OR.

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance15

Infrequent updates — may be unmaintained

Popularity39

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 94.4% 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

Every ~25 days

Total

3

Last Release

1189d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e3171496e198834c638911ad3c3220bec77871cdf6557eaa9e2a58d16600a1a1?d=identicon)[bordoni](/maintainers/bordoni)

![](https://www.gravatar.com/avatar/70a2847a265444714b48c64eceb3ca742baa3a56757ce65b18bd7bbbbf910312?d=identicon)[dpanta94](/maintainers/dpanta94)

![](https://www.gravatar.com/avatar/97fd764aa710e8d8263a7e3b3fececdfd736b8aad8055227bf592ddf50ad15ba?d=identicon)[stellarwp](/maintainers/stellarwp)

![](https://www.gravatar.com/avatar/ec4ef25906386b60f5f66b3d03064e3bb700bedc94ee8558918565612c74aef3?d=identicon)[johnhooks](/maintainers/johnhooks)

---

Top Contributors

[![JasonTheAdams](https://avatars.githubusercontent.com/u/2024145?v=4)](https://github.com/JasonTheAdams "JasonTheAdams (17 commits)")[![borkweb](https://avatars.githubusercontent.com/u/430385?v=4)](https://github.com/borkweb "borkweb (1 commits)")

---

Tags

wordpress-librarywordpress-php-library

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/stellarwp-field-conditions/health.svg)

```
[![Health](https://phpackages.com/badges/stellarwp-field-conditions/health.svg)](https://phpackages.com/packages/stellarwp-field-conditions)
```

PHPackages © 2026

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