Query evaluation

This guide provides practical examples of using the PHP SDK to evaluate CQL queries from your application.

Basic usage

The SDK provides an evaluate method that allows you to run CQL queries in real-time. This method returns the result of the evaluation.

For example, to check whether the current user is returning to your application you can use the following query:

<?phpuse Croct\Plug\Croct;
$croct = Croct::fromDotenv();$returning = $croct->evaluate('user is returning');

The result of the evaluation is not restricted to boolean values. For example, you can use the following query to find out the location from which the user is accessing your application:

<?phpuse Croct\Plug\Croct;
$croct = Croct::fromDotenv();$location = $croct->evaluate('location');

In this case, the result of the evaluation is a geographic location:

{  "continent": "North America",  "continentCode": "NA",  "country": "United States",  "countryCode": "US",  "region": "New York",  "regionCode": "NY",  "state": "New York",  "stateCode": "NY",  "city": "Denver",  "district": null,  "timeZone": null}

Fault tolerance

We recommend always handling errors when evaluating queries to protect your application from unexpected errors, downtime, and network failures.

Pass a fallback through the withFallback option, and the SDK returns it whenever the query cannot be evaluated:

<?phpuse Croct\Plug\Croct;use Croct\Plug\EvaluationOptions;
$croct = Croct::fromDotenv();$options = EvaluationOptions::defaults()->withFallback(false);$returning = $croct->evaluate('user is returning', $options);

In this example, the $returning variable is set to false if the evaluation fails, ensuring that the application continues to work as expected. Without a fallback, a failed evaluation throws a CroctException, which you can catch to handle the error yourself.

Context variables

In some cases, you may want to pass additional information that can be used by the query in the evaluation process.

For example, let’s say you want to check whether the user is accessing your application from one of a list of countries. The SDK allows you to pass this information as an attribute to the query:

<?phpuse Croct\Plug\Croct;use Croct\Plug\EvaluationOptions;
$croct = Croct::fromDotenv();$options = EvaluationOptions::defaults()->withAttribute('countries', ['United States', 'Canada', 'Mexico']);$result = $croct->evaluate("context's countries include location's countryName", $options);

Any attribute passed through the withAttribute option will be available in the query as a context variable.