# Expressions

> Enable features by defining rules that evaluate against properties of an actor and a feature context.

> **NOTE**
> Expressions are an experimental feature and are subject to change. Please [provide feedback](mailto:support@flippercloud.io?subject=Expressions) if you use them.

Flipper Expressions are a powerful new way to enable features that support complex logic. They are language-agnostic and are stored in JSON, so they can sync between your application and Flipper Cloud.

## Enabling an expression {#enable}

The simplest expression is a comparison of a property on the actor to a given value. For example, if we have a `User` model with an `age` property, we can enable a feature for users of a given age:

```ruby
must_be_21 = Flipper.property(:age).gte(21)
Flipper.enable :night_club, must_be_21
```

Now we can test it for two actors of different ages:

```ruby
# Under age
Flipper.enabled? :night_club, User.new(age: 18) #=> false

# Of age
Flipper.enabled? :night_club, User.new(age: 21) #=> true
```

The `Property` expression extracts a property from the actor (by calling [`#flipper_properties`](#flipper_properties) on it), and in this case we use the `GreaterThanOrEqualTo` (aliased to `gte`) expression to compares it to the constant 21.

You can compare any two values using `eq`, `gt`, `lt`, `gte`, `lte`, or `ne`.

## Combining expressions

What if you want to enable a feature for users who are over 21 and have either paid or are a VIP? No problem, you can group expressions together using `all` and `any`, and even nest groups inside each other:

```ruby
over_21 = Flipper.property(:age).gte(21)
paid = Flipper.property(:paid).eq(true)
vip = Flipper.property(:vip).eq(true)

Flipper.enable :night_club, Flipper.all(over_21, Flipper.any(paid, vip))
```

Now we can test it for three different actors:

```ruby
# Unpaid
Flipper.enabled? :night_club, User.new(2, age: 18, paid: false) #=> false
# Paid
Flipper.enabled? :night_club, User.new(1, age: 18, paid: true) #=> true
# Unpaid, but VIP
Flipper.enabled? :night_club, User.new(3, age: 18, paid: false, vip: true) #=> true
```

These groups require at least one sub-expression and can be nested to create complex rules.

## Time-based expressions {#time}

You can enable features based on time using the `Now` and `Time` expressions. These work without an actor, so no `flipper_properties` are required.

### Scheduled enablement

Enable a feature starting at a specific time:

```ruby
expression = Flipper.now.gte(Flipper.time("2026-03-01T00:00:00Z"))
Flipper.enable :new_feature, expression
```

### Expiring feature

Enable a feature until a specific time:

```ruby
expression = Flipper.now.lt(Flipper.time("2026-04-01T00:00:00Z"))
Flipper.enable :promo_banner, expression
```

### Time window

Enable a feature during a specific time range:

```ruby
start_time = "2026-03-01T00:00:00Z"
end_time = "2026-04-01T00:00:00Z"

expression = Flipper.all(
  Flipper.now.gte(Flipper.time(start_time)),
  Flipper.now.lt(Flipper.time(end_time))
)
Flipper.enable :spring_sale, expression
```

### Combined with actor properties

Combine time-based expressions with property checks:

```ruby
expression = Flipper.all(
  Flipper.property(:plan).eq("basic"),
  Flipper.now.gte(Flipper.time("2026-03-01T00:00:00Z"))
)
Flipper.enable :new_feature, expression
```

### Expression types

- `Flipper.now` — Returns the current time in UTC. Takes no arguments.
- `Flipper.time(value)` — Parses a time value. Accepts ISO 8601 strings (e.g. `"2026-03-01T00:00:00Z"`) or epoch timestamps (e.g. `1708300800`). Always returns UTC.

## Version expressions {#semver}

Use `SemVer` to compare app versions by [Semantic Versioning](https://semver.org) rules instead of as strings, so `2.10.0` is greater than `2.9.0` and `1.0.0-beta.1` is less than `1.0.0`. Wrap both sides of the comparison:

```ruby
expression = Flipper.semver(Flipper.property(:app_version)).gte(Flipper.semver("2.3.1"))
Flipper.enable :new_onboarding, expression
```

In the expression builder, choose **Version** from the **+ Add** menu. It shows up once every app that synced the environment in the last 30 days runs a flipper release newer than 1.4.2.

### Version range

```ruby
app_version = Flipper.semver(Flipper.property(:app_version))

expression = Flipper.all(
  app_version.gte(Flipper.semver("2.3.1")),
  app_version.lt(Flipper.semver("3.0.0"))
)
Flipper.enable :new_onboarding, expression
```

### Version rules

- Follows [SemVer 2.0.0](https://semver.org) precedence, including prereleases (`1.0.0-alpha` < `1.0.0-beta` < `1.0.0`). Build metadata is ignored, so `1.0.0+1` equals `1.0.0+2`.
- A leading `v` is allowed (`v2.3.1`), and missing minor or patch numbers count as `0` (`2.3` is `2.3.0`).
- Pass versions as strings. Floats like `2.10` would read as `2.1`, so they aren't treated as versions.
- An actor with a missing or malformed version never matches greater than or less than (or equal to). Equal and not equal compare it as no version, so it does match not equal to `2.3.1`.
- Your app needs a flipper release newer than 1.4.2. Apps on 1.4.2 or older treat a feature with a `SemVer` expression as if it had no expression, so it's on for them only through its other gates. They also can't change or import over that expression until they upgrade.

## Feature dependencies {#feature-dependencies}

You can make a feature depend on another feature using `Flipper.feature_enabled` and `Flipper.feature_disabled`. This allows you to create feature flag dependencies without custom code.

### Enable only if another feature is on

```ruby
Flipper.enable(:search_beta)
Flipper.enable :search_v2, Flipper.feature_enabled(:search_beta)
```

The actor is passed through, so if the referenced feature is enabled for specific actors, the dependent feature respects that:

```ruby
Flipper.enable_actor(:search_beta, user)
Flipper.enable :search_v2, Flipper.feature_enabled(:search_beta)

Flipper.enabled?(:search_v2, user)        #=> true
Flipper.enabled?(:search_v2, other_user)  #=> false
```

### Enable only if another feature is off

```ruby
Flipper.enable :new_checkout, Flipper.feature_disabled(:old_checkout)
```

### Combined with other expressions

```ruby
Flipper.enable :advanced_search, Flipper.all(
  Flipper.feature_enabled(:basic_search),
  Flipper.property(:plan).eq("premium")
)
```

Circular dependencies (A depends on B, B depends on A) are detected automatically and return `false`.

Feature dependencies need flipper 1.4.0 or newer. Apps on 1.3.6 or older treat a feature with one as if it had no expression, and can't change or import over it until they upgrade. In the expression builder, **Feature Enabled** and **Feature Disabled** show up once every app that synced the environment in the last 30 days runs flipper 1.4.0 or newer.

## `flipper_properties`

To use expressions, you'll need to ensure that actors respond to `flipper_properties` and return a hash of properties that you want to use in expressions. This is defined on ActiveRecord models by default. If you want to use expressions with a different model, you can define a method that returns a hash of properties:

```ruby
class User < Struct.new(:id, :flipper_properties)
  include Flipper::Identifier
end

basic_user = User.new(1, {"plan" => "basic", "age" => 30})
premium_user = User.new(2, {"plan" => "premium", "age" => 40})
```

---

To learn more, check out the plethora of code samples in [examples/expressions.rb](https://github.com/flippercloud/flipper/blob/main/examples/expressions.rb).
