Filters

Build Stats v2 filters fluently with where() and orWhere(). Each takes a field (a Dimension, Property or string), an operator (a FilterOperator or string) and a value — a scalar or a list:

use RoundlyConsulting\Plausible\Enums\Dimension;
use RoundlyConsulting\Plausible\Enums\FilterOperator;
use RoundlyConsulting\Plausible\Enums\Metric;

$result = Plausible::stats()
    ->for('my-site.com')
    ->metrics(Metric::Visitors)
    ->where(Dimension::VisitBrowser, FilterOperator::Is, 'Chrome')
    ->where('visit:os', 'is', ['Mac', 'Windows'])                 // implicit AND, list value
    ->orWhere(Dimension::VisitCountry, FilterOperator::Is, 'US')  // OR with the previous
    ->run();

Multiple where() calls combine with an implicit AND. orWhere() folds the previous filter and the new one into an or group, and further orWhere() calls extend that same group; a leading orWhere() behaves like where(). Both compile to Plausible’s array form:

// ->where(Dimension::VisitBrowser, FilterOperator::Is, 'Chrome')
['is', 'visit:browser', ['Chrome']];

// ->where('visit:browser', 'is', 'Chrome')
// ->orWhere('visit:browser', 'is', 'Firefox')
// ->orWhere('visit:browser', 'is', 'Safari')
['or', [
    ['is', 'visit:browser', ['Chrome']],
    ['is', 'visit:browser', ['Firefox']],
    ['is', 'visit:browser', ['Safari']],
]];

Custom event properties

// Filter on a custom event property — Dimension::custom('plan') returns 'event:props:plan'
Plausible::stats()
    ->for('my-site.com')
    ->metrics(Metric::Visitors, Metric::Events)
    ->where(Dimension::custom('plan'), FilterOperator::Is, 'pro')
    ->run();

Raw filters

filter() accepts both raw shapes. A string uses the legacy v1 syntax and applies to aggregate(), timeseries() and breakdown(); several are joined with a semicolon. An array uses the v2 form and applies to run():

// v1 terminals take the legacy string syntax; several filters are joined with ';'
Plausible::stats()
    ->for('my-site.com')
    ->filter('visit:browser==Chrome')
    ->filter('visit:country==FR')
    ->aggregate();

// run() takes the v2 array form — the same shape where() compiles to
Plausible::stats()
    ->for('my-site.com')
    ->filter(['is', 'visit:browser', ['Chrome']])
    ->run();

where(), orWhere() and array filters target the run() terminal only — the v1 terminals ignore them, so use string filters there.

Operators

Case	Wire value
`FilterOperator::Is`	is
`FilterOperator::IsNot`	is_not
`FilterOperator::Contains`	contains
`FilterOperator::ContainsNot`	contains_not
`FilterOperator::Matches`	matches
`FilterOperator::MatchesNot`	matches_not
`FilterOperator::And_`	and
`FilterOperator::Or_`	or
`FilterOperator::Not`	not
`FilterOperator::HasDone`	has_done
`FilterOperator::HasNotDone`	has_not_done

Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

More ways to support, including crypto

By donating, you agree to our donation terms.

Support our open source work Join us on Patreon

Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

Get a quote in 48 hours Browse all packages