> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fiquela.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run your first FiQueLa query against a structured file in under five minutes.

This guide shows three ways to open a file and run a query. All approaches produce the same result — choose the one that fits your style.

<Steps>
  <Step title="Install FiQueLa">
    If you haven't already, add the package to your project:

    ```bash theme={null}
    composer require 1biot/fiquela
    ```

    Then include the autoloader:

    ```php theme={null}
    require __DIR__ . '/vendor/autoload.php';
    ```
  </Step>

  <Step title="Approach 1: Open a file with Stream\Provider">
    Use `Stream\Provider::fromFile` to open a file and call `->query()` to start building a query with the fluent API. The format is inferred automatically from the file extension.

    ```php theme={null}
    use FQL\Enum\Operator as Op;
    use FQL\Stream;

    $xml = Stream\Provider::fromFile('./products.xml');

    $results = $xml->query()
        ->selectAll()
        ->from('SHOP.SHOPITEM')
        ->where('EAN', Op::EQUAL, '1234567891011')
        ->or('PRICE', Op::LESS_THAN_OR_EQUAL, 200)
        ->orderBy('PRICE')->desc()
        ->limit(10)
        ->execute()
        ->fetchAll();

    print_r(iterator_to_array($results));
    ```

    You can also open specific stream classes directly:

    ```php theme={null}
    use FQL\Stream;

    $xml = Stream\Xml::open('./products.xml');
    ```

    <Tip>
      Pass an explicit `Enum\Format` constant as the second argument to `fromFile` when the extension is ambiguous or missing: `Stream\Provider::fromFile('./data', Enum\Format::XML)`.
    </Tip>
  </Step>

  <Step title="Approach 2: FileQuery syntax with Query\Provider">
    `Query\Provider::fromFileQuery` accepts a compact string that encodes the format, file path, and data path in one expression. This is useful for quick one-liners.

    ```php theme={null}
    use FQL\Enum\Operator as Op;
    use FQL\Query;

    $results = Query\Provider::fromFileQuery('xml(./products.xml).SHOP.SHOPITEM')
        ->selectAll()
        ->where('EAN', Op::EQUAL, '1234567891011')
        ->or('PRICE', Op::LESS_THAN_OR_EQUAL, 200)
        ->orderBy('PRICE')->desc()
        ->limit(10)
        ->execute()
        ->fetchAll();

    print_r(iterator_to_array($results));
    ```

    The FileQuery string format is:

    ```
    format(pathToFile[, params]).path.to.data
    ```

    Examples:

    ```
    xml(feed.xml).SHOP.ITEM
    csv(data.csv, "windows-1250", ";").*
    json(data.json).data.users
    ```
  </Step>

  <Step title="Approach 3: FQL string syntax with Query\Provider">
    `Query\Provider::fql` accepts a full SQL-like string. This is the most expressive option and mirrors the FQL syntax closely.

    ```php theme={null}
    use FQL\Query;

    $query = <<<FQL
        SELECT *
        FROM xml(./products.xml).SHOP.SHOPITEM
        WHERE
            EAN = "1234567891011"
            OR PRICE <= 200
        ORDER BY PRICE DESC
        LIMIT 10
    FQL;

    $results = Query\Provider::fql($query)
        ->execute()
        ->fetchAll();

    print_r(iterator_to_array($results));
    ```
  </Step>

  <Step title="Inspect the output">
    All three approaches produce the same array structure:

    ```php theme={null}
    Array
    (
        [0] => Array
            (
                [NAME] => "Product 1"
                [EAN] => "1234567891011"
                [PRICE] => 300.00
            )
        [1] => Array
            (
                [NAME] => "Product 2"
                [EAN] => "1234567891012"
                [PRICE] => 150.00
            )
        [2] => Array
            (
                [NAME] => "Product 3"
                [EAN] => "1234567891013"
                [PRICE] => 150.00
            )
        ...
    )
    ```

    `fetchAll()` returns a `Generator`. Wrap it with `iterator_to_array()` to get a plain array, or iterate it directly in a `foreach` loop.
  </Step>
</Steps>

## Next steps

<Columns cols={2}>
  <Card title="Fluent API" icon="code" href="/querying/fluent-api">
    Learn every method available for building queries in PHP.
  </Card>

  <Card title="FQL syntax" icon="terminal" href="/querying/fql-syntax">
    Write full SQL-like query strings with all supported clauses.
  </Card>
</Columns>