# Query evaluation

Learn how to evaluate queries in real-time.

This guide provides practical examples of using the Symfony SDK to evaluate [CQL queries](/reference/cql/introduction) from your application.

## Basic usage

Inject the [`Plug`](/reference/sdk/php/api/core/plug) service and call [`evaluate`](/reference/sdk/php/api/core/plug/evaluate) to run [CQL queries](/reference/cql/introduction) 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:

**src/Controller/HomeController.php**

```php
<?php

namespace App\Controller;

use Croct\Plug\Plug;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class HomeController extends AbstractController
{
    #[Route('/', name: 'home')]
    public function index(Plug $croct): Response
    {
        $returning = $croct->evaluate('user is returning');

        return $this->render('home/index.html.twig', ['returning' => $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:

```php
$location = $croct->evaluate('location');
```

In this case, the result of the evaluation is a [geographic location](/reference/cql/data-types/location/location):

**Query result**

```json
{
  "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
}
```

*In the browser version of this page, this example is evaluated live for the visitor.*

## Fault tolerance

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

Pass a [fallback](/reference/sdk/php/api/options/evaluation-options/with-fallback), and the SDK returns it whenever the query cannot be evaluated:

```php
use Croct\Plug\EvaluationOptions;

$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 an [exception](/reference/sdk/php/api/exceptions/croct-exception), 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:

```php
use Croct\Plug\EvaluationOptions;

$options = EvaluationOptions::defaults()->withAttribute('countries', ['United States', 'Canada', 'Mexico']);
$result = $croct->evaluate("context's countries include location's countryName", $options);
```

Any [attribute](/reference/sdk/php/api/options/evaluation-options/with-attribute) you pass will be available in the query as the [`context`](/reference/cql/data-types/web/web-context) variable.

## Explore

- [CQL reference](/reference/cql/expressions/basics): Learn how to write queries using the CQL language.
- [evaluate method](/reference/sdk/php/api/core/plug/evaluate): Explore the method documentation and available options.