Where

The where() method allows you specify condition clauses. It accepts a field, an operator and a value. However, just like the select method, the API you are working with may not support operators at all. If so, then you might have to settle using where() as a regular key-value construct.

Arguments

where() accepts the following arguments:

• $field: string|array name of field or key-value pair, where key = field name, value = mixed.
• $operator: mixed operator or value
• $value: mixed (optional) value. If omitted, then $operator acts as value.

$response = $client
        ->where('name', 'john')
        ->get('/users');

/users?name=john

/users?filter[name]=john

/users?$filter=name eq 'john'

Operator

When passing an operator to the where() method, each grammar will attempt to add it to the final query string. There is no limitation of the types of operators you can use, provided the operator is stated as string. Consider the following example.

$response = $client
        ->where('year', 'gt', 2020)
        ->get('/users');

/users?year[gt]=2020

/users?filter[year][gt]=2020

/users?$filter=year gt 2020

Multiple Conditions

You may add as many conditions as you require. The following illustrates multiple conditions on the same field.

$response = $client
        ->where('year', 'gt', 2020)
        ->where('year', 'lt', 2051)
        ->get('/users');

/users?year[gt]=2020&year[lt]=2051

/users?filter[year][gt]=2020&filter[year][lt]=2051

/users?$filter=year gt 2020 and year lt 2051

Via Array

If you pass an array as the first argument, then the query builder will interpret it as a list of conditions. Each key acts as the name of the field (or filter name), whereas the value acts as operator / value.

$response = $client
        ->where([
            'year' => [
                'gt' => 2021,
                'lt' => 2031
            ],
            'name' => 'john'
        ])
        ->get('/users');

/users?year[gt]=2021&year[lt]=2031&name=john

/users?filter[year][gt]=2021&filter[year][lt]=2031&filter[name]=john

/users?$filter=year gt 2021 and year lt 2031 and name eq 'john'

Array Values

When dealing with array values, you should be aware of how your chosen grammar produces it's final query string. Consider a situation the API you are working allows you to perform "where users in list" filtering. You might construct your condition in the following way.

$response = $client
        ->where('users', 'in', [1, 2, 3, 4])
        ->get('/users');

The above shown example will produce the following query string. Depending on your needs, this outcome might not be favourable for you.

/users?users[in][0]=1&users[in][1]=2&users[in][2]=3&users[in][3]=4

/users?filter[users][in][0]=1&filter[users][in][1]=2&filter[users][in][2]=3&filter[users][in][3]=4

/users?$filter=users in (1,2,3,4)

Alternatively, you could convert array values in to a comma-separated list. If so, then you could create your condition in the following way:

$response = $client
        ->where('users', 'in', implode(',', [1, 2, 3, 4]))
        ->get('/users');

/users?users[in]=1,2,3,4

/users?filter[users][in]=1,2,3,4

/users?$filter=users in `1,2,3,4`

Where Raw

The whereRaw() method can be used for stating conditions as raw expressions. Alternatively, you may also use the raw method instead.

Two arguments are supported by the whereRaw() method:

• $expression: string the raw expression
• $bindings: array (optional) binding values

$response = $client
        ->whereRaw('filter=user eq :amount', [ 'amount' => 10 ])
        ->get('/users');

/users?filter=user eq 10

/users?filter=user eq 10

/users?$filter=filter=user eq 10

Or Where

orWhere() and orWhereRaw() can be used to add "or" conjunctions in your http query string. However, apart from OData, these are NOT considered conventional. Chances are pretty good that these are NOT supported by API you are working with, if "or" conjunctions are supported at all.

$response = $client
        ->where('name', 'john')
        ->orWhere('gender', 'male')
        ->get('/users');

/users?name=john&|gender=male

/users?filter[name]=john&filter[|gender]=male

/users?$filter=name eq 'john' or gender eq 'male'

If your target API does support "or" conjunctions, yet these grammars fail to deliver the desired syntax for such, please consider creating a custom grammar.