PHPackages                             1biot/fiquela - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. 1biot/fiquela

ActiveLibrary[File & Storage](/categories/file-storage)

1biot/fiquela
=============

FiQueLa - File Query Language - PHP library for querying files

v2.10.2(1mo ago)4435MITPHPPHP >=8.2CI passing

Since Dec 19Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/1biot/FiQueLa)[ Packagist](https://packagist.org/packages/1biot/fiquela)[ RSS](/packages/1biot-fiquela/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (24)Versions (69)Used By (0)

FiQueLa: File Query Language
============================

[](#fiquela-file-query-language)

> *\[fi-kju-ela\]*

[![Packagist Version](https://camo.githubusercontent.com/f631ff5a5e2ed7f1403b91600dd667fd44f93764afaeb20570640f7e8a8b6fbc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f3162696f742f66697175656c61)](https://camo.githubusercontent.com/f631ff5a5e2ed7f1403b91600dd667fd44f93764afaeb20570640f7e8a8b6fbc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f3162696f742f66697175656c61)[![CI](https://github.com/1biot/fiquela/actions/workflows/ci.yml/badge.svg)](https://github.com/1biot/fiquela/actions/workflows/ci.yml)[![Packagist Dependency Version](https://camo.githubusercontent.com/b84036385cbd2ca7dff09e021e66a1f2ea72011e00283d6b2fa7c8dadc91aa2a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f3162696f742f66697175656c612f706870)](https://camo.githubusercontent.com/b84036385cbd2ca7dff09e021e66a1f2ea72011e00283d6b2fa7c8dadc91aa2a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f3162696f742f66697175656c612f706870)[![Packagist License](https://camo.githubusercontent.com/971439eb1f5a14d69e6712636a9bd12891bf6bda5776e8e4376f3335c56820d1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f3162696f742f66697175656c61)](https://camo.githubusercontent.com/971439eb1f5a14d69e6712636a9bd12891bf6bda5776e8e4376f3335c56820d1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f3162696f742f66697175656c61)

[![Coverage](https://camo.githubusercontent.com/2b5c55e58d639704768aee39379442c0c7bd513e93e27322880d1c07d1e3e7eb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f7665726167652d38332e36382532352d79656c6c6f77)](https://camo.githubusercontent.com/2b5c55e58d639704768aee39379442c0c7bd513e93e27322880d1c07d1e3e7eb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f7665726167652d38332e36382532352d79656c6c6f77)[![PHPUnit Tests](https://camo.githubusercontent.com/d00349d7b9b3d38d91f82e4e79011b13dee60d3afb7f581d947edf0371a92eae/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f504850556e69742d74657374732533415f3639312d6c69676874677265656e)](https://camo.githubusercontent.com/d00349d7b9b3d38d91f82e4e79011b13dee60d3afb7f581d947edf0371a92eae/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f504850556e69742d74657374732533415f3639312d6c69676874677265656e)[![PHPStan](https://camo.githubusercontent.com/66617294b56332dffe4e2475914ac4e87fa608b334da37e8a9792c7a1bc3f5a8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068707374616e2d6c6576656c5f382d6c69676874677265656e)](https://camo.githubusercontent.com/66617294b56332dffe4e2475914ac4e87fa608b334da37e8a9792c7a1bc3f5a8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068707374616e2d6c6576656c5f382d6c69676874677265656e)

**F**i**Q**ue**L**a lets you query files like a database, with SQL-like syntax or a fluent PHP API. Filter, join, group, aggregate, and transform data from **XML**, **XLS**, **ODS**, **CSV**, **JSON**, **NDJSON**, **YAML**, and **NEON** without setting up a database. It is built for real-world data processing with streaming support, explain/debug tooling, and strongly typed operators.

**Features**:

- 📂 **Supports multiple formats**: Work seamlessly with XML, CSV, JSON, NDJSON, YAML, NEON, and XLS.
- 🛠️ **SQL-inspired syntax**: Perform `SELECT`, `JOIN`, `WHERE`, `GROUP BY`, `HAVING`, `ORDER BY` and more.
- ✍️ **Flexible querying**: Write SQL-like strings or use the fluent API.
- 📊 **Powerful expressions and functions**: Use `CASE WHEN`, `IF`, grouped conditions, `XOR`, `REGEXP`, aggregates, and utility functions.
- 🚀 **Stream-first processing**: Optimized for large JSON, XML, and CSV files with low memory pressure where possible.
- 🧑‍💻 **Developer-Friendly**: Map results to DTOs for easier data manipulation.
- ⭐ **Unified API across all supported formats**: Use a consistent API for all your data needs.

### Why FiQueLa

[](#why-fiquela)

- Query files with familiar SQL concepts while keeping everything in PHP.
- Join data across sources and formats in one query.
- Handle advanced logic with nested condition groups and statement functions.
- Inspect execution using explain output and debugger tooling.

**Table of Contents**:

- [Overview](#1-overview)
- [Installation](#2-installation)
- [Supported Formats](#3-supported-formats)
- [Getting Started](#4-getting-started)
- [Documentation](#5-documentation)
    - [Opening Files](docs/opening-files.md)
    - [Fluent API](docs/fluent-api.md)
    - [File Query Language](docs/file-query-language.md)
    - [Fetching Data](docs/fetching-data.md)
    - [Query Life Cycle](docs/query-life-cycle.md)
    - [Query Inspection and Benchmarking](docs/query-inspection-and-benchmarking.md)
    - [API Reference](docs/api-reference.md)
- [Examples](#6-examples)
- [Ecosystem](#7-ecosystem)
    - [FiQueLa CLI](#fiquela-cli)
    - [FiQueLa API](#fiquela-api)
    - [FiQueLa Studio](#fiquela-studio)
- [Known issues](#8-known-issues)
- [Roadmap](#9-roadmap)
- [Contributions](#10-contributions)

1. Overview
-----------

[](#1-overview)

Why limit SQL to databases when it can be just as effective for structured files? **F**i**Q**ue**L**a brings SQL-like querying to file-based data and keeps your workflow fully in PHP.

Key highlights:

- **Universal querying**: Filter, sort, join, and aggregate data across multiple file formats.
- **Real SQL-like behavior**: Use `GROUP BY`, `HAVING`, nested conditions, `CASE WHEN`, `IF`, and many built-in functions.
- **Flexible integration**: Query through fluent API or SQL-like strings, whichever matches your use case.
- **Operational tooling**: Use debugger and explain plans to understand performance and execution.

Use **F**i**Q**ue**L**a to:

- Simplify data extraction and analysis from structured files.
- Combine data from multiple sources with ease.
- Create lightweight data processing pipelines without a full-fledged database.

**F**i**Q**ue**L**a empowers developers to unlock the potential of file-based data with the familiar and expressive language of SQL.

2. Installation
---------------

[](#2-installation)

Install via [Composer](https://getcomposer.org/):

```
composer require 1biot/fiquela
```

Install packages for optional features:

```
composer require tracy/tracy
```

### Dependencies

[](#dependencies)

- **`league/csv`**: Required for CSV file support.
- **`halaxa/json-machine`**: Required for JSON stream support.
- **`symfony/yaml`**: Required for YAML file support.
- **`nette/neon`**: Required for NEON file support.
- **`openspout/openspout`**: Required for XLSX and ODS file support.
- **`tracy/tracy`**: Optional for using Debugger

3. Supported Formats
--------------------

[](#3-supported-formats)

FormatNameClassFile SupportString Support`csv`CSV`FQL\Stream\Csv`✅❌`xml`XML`FQL\Stream\Xml`✅❌`xls`XLS/XLSX`FQL\Stream\Xls`✅❌`ods`ODS`FQL\Stream\Ods`✅❌`jsonFile`JSON Stream`FQL\Stream\JsonStream`✅❌`ndJson`Newline Delimited JSON`FQL\Stream\NDJson`✅❌`json`JSON (json\_decode)`FQL\Stream\Json`✅✅`yaml`YAML`FQL\Stream\Yaml`✅✅`neon`NEON`FQL\Stream\Neon`✅✅### Directory provider

[](#directory-provider)

Is special provider `FQL\Stream\Dir` class. It allows you to use directory as a source. You can query all files recursively by queries.

4. Getting Started
------------------

[](#4-getting-started)

Here’s a quick example of how **F**i**Q**ue**L**a can simplify your data queries:

```
use FQL\Enum;
use FQL\Query;

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

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

This query returns rows that match either a specific EAN or a price threshold, sorted by price and limited to 10 records.

Or using the FQL syntax:

```
use FQL\Query;

$query =  "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
        )
    ...
)
```

5. Documentation
----------------

[](#5-documentation)

For more details about **F**i**Q**ue**L**a and her capabilities, explore the documentation sections.

- [Opening Files](docs/opening-files.md)
- [Fluent API](docs/fluent-api.md)
- [File Query Language](docs/file-query-language.md)
- [Fetching Data](docs/fetching-data.md)
- [Query Life Cycle](docs/query-life-cycle.md)
- [Query Inspection and Benchmarking](docs/query-inspection-and-benchmarking.md)
- [API Reference](docs/api-reference.md)

6. Examples
-----------

[](#6-examples)

Check the examples and run them using Composer. All examples uses `\FQL\Query\Debugger` and methods `inspectQuery`, `inspectSql`, `inspectStreamSql` or `benchmarkQuery` to show the results.

```
composer examples
# or
composer example:csv
composer example:join
composer example:json
composer example:neon
composer example:sql
composer example:xml
composer example:yaml
composer example:explain
```

Check step **Examples** at [actions](https://github.com/1biot/fiquela/actions/runs/12992585648/job/36232767074) or run `composer example:csv` and output will look like this:

```
=========================
### Debugger started: ###
=========================
> Memory usage (MB): 1.3191 (emalloc)
> Memory peak usage (MB): 1.7326 (emalloc)
------------------------------
> Execution time (s): 8.5E-5
> Execution time (ms): 0.085
> Execution time (µs): 85
> Execution memory peak usage (MB): 0
=========================
### Inspecting query: ###
=========================
==================
### SQL query: ###
==================
> SELECT
>   ean ,
>   defaultCategory ,
>   EXPLODE(defaultCategory, " > ") AS categoryArray ,
>   price ,
>   ROUND(price, 2) AS price_rounded ,
>   MOD(price, 100) AS modulo_100 ,
>   MOD(price, 54) AS modulo_54
> FROM csv(products-w-1250.csv, "windows-1250", ";").*
> GROUP BY defaultCategory
> ORDER BY defaultCategory DESC
================
### Results: ###
================
> Result class: FQL\Results\InMemory
> Results size memory (KB): 3.55
> Result exists: true
> Result count: 15
========================
### Fetch first row: ###
========================
array (7)
   'ean' => 5010232964877
   'defaultCategory' => 'Testování > Drogerie'
   'categoryArray' => array (2)
   |  0 => 'Testování'
   |  1 => 'Drogerie'
   'price' => 121.0
   'price_rounded' => 121.0
   'modulo_100' => 21.0
   'modulo_54' => 13.0

>>> SPLIT TIME  Memory peak usage (MB): 3.2262 (emalloc)
------------------------------
> Execution time (s): 0.040016
> Execution time (ms): 40.016
> Execution time (µs): 40016
> Execution memory peak usage (MB): 1.4936
========================
### Benchmark Query: ###
========================
> 2 500 iterations
==================
### SQL query: ###
==================
> SELECT
>   ean ,
>   defaultCategory ,
>   EXPLODE(defaultCategory, " > ") AS categoryArray ,
>   price ,
>   ROUND(price, 2) AS price_rounded ,
>   MOD(price, 100) AS modulo_100 ,
>   MOD(price, 54) AS modulo_54
> FROM csv(products-w-1250.csv, "windows-1250", ";").*
> GROUP BY defaultCategory
> ORDER BY defaultCategory DESC
=========================
### STREAM BENCHMARK: ###
=========================
> Size (KB): 2.78
> Count: 15
> Iterated results: 37 500
>>> SPLIT TIME  Memory peak usage (MB): 3.2262 (emalloc)
------------------------------
> Execution time (s): 36.402098
> Execution time (ms): 36402.098
> Execution time (µs): 36402098
> Execution memory peak usage (MB): 0
============================
### IN_MEMORY BENCHMARK: ###
============================
> Size (KB): 3.55
> Count: 15
> Iterated results: 37 500
>>> SPLIT TIME  Memory peak usage (MB): 3.2262 (emalloc)
------------------------------
> Execution time (s): 0.01743
> Execution time (ms): 17.43
> Execution time (µs): 17430
> Execution memory peak usage (MB): 0
=======================
### Debugger ended: ###
=======================
> Memory usage (MB): 3.1343 (emalloc)
> Memory peak usage (MB): 3.2262 (emalloc)
------------------------------
> Final execution time (s): 36.459756
> Final execution time (ms): 36459.756
> Final execution time (µs): 36459756

```

7. Ecosystem
------------

[](#7-ecosystem)

FiQueLa is more than just a PHP library. It comes with a CLI tool, a REST API server, and a web-based query explorer.

### FiQueLa CLI

[](#fiquela-cli)

[**fiquela-cli**](https://github.com/1biot/fiquela-cli) is a command-line tool for querying structured files directly from the terminal. It supports local file querying, remote API connections, and an interactive REPL mode with paginated table output.

```
# Install
curl -fsSL https://raw.githubusercontent.com/1biot/fiquela-cli/main/install.sh | bash

# Query a local file
fiquela-cli --file=data.csv "SELECT name, price FROM * WHERE price > 100;"

# Interactive mode
fiquela-cli --file=data.csv
```

Requires PHP 8.2+ with readline, curl, and zlib extensions.

### FiQueLa API

[](#fiquela-api)

[**fiquela-api**](https://github.com/1biot/fiquela-api) is a RESTful server for querying structured files over HTTP. It provides file management, query execution, result export (CSV, TSV, JSON), and query history tracking with JWT authentication.

[![Deploy to DO](https://camo.githubusercontent.com/1959f5da42c67ccef3538861164e5d4bb24c70a9920a996eedb4ce5c4c2a3946/68747470733a2f2f7777772e6465706c6f79746f646f2e636f6d2f646f2d62746e2d626c75652e737667)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/1biot/fiquela-api/tree/main?refcode=92025543cb9f)

Requires credentials configuration via environment variables. Optionally enable S3 backup (Cloudflare R2) for file storage. For more information visit the [repository](https://github.com/1biot/fiquela-api?tab=readme-ov-file#-credentials).

Key endpoints: `POST /api/auth/login` for JWT authentication, `POST /api/v1/query` for executing queries, `GET /api/v1/files` for file management, `GET /api/v1/export/{hash}` for downloading results. All endpoints except login require `Authorization: Bearer `.

### FiQueLa Studio

[](#fiquela-studio)

[**studio.fiquela.io**](https://studio.fiquela.io) is a web-based visual query explorer for building and running FQL queries interactively. Requires a running [FiQueLa API](#fiquela-api) instance to connect to.

8. Known issues
---------------

[](#8-known-issues)

- ⚠️ Functions `JOIN`, and `ORDER BY` are not memory efficient, because joining data or sorting data requires to load all data into memory. It may cause memory issues for large datasets. But everything else is like ⚡️.

9. Roadmap
----------

[](#9-roadmap)

- **Operator BETWEEN**: Add operator `BETWEEN` for filtering data and add support for dates and ranges.
- **XLS/XLSX**: Add Excel file support.
- **Custom cast type**: Add support for custom cast type for `SELECT` clause.
- **Add explain method**: Add method `explain()` for explaining query execution from actual query debugger and provide more complex information about query.
- **PHPStan 8**: Fix all PHPStan 8 errors.
- **Tests**: Increase test coverage (80%+).
- **Optimize GROUP BY**: Optimize `GROUP BY` for more memory efficient data processing.
- **DELETE, UPDATE, INSERT**: Support for manipulating data in files. - Instead of this, it will comes support for exporting data to files (CSV, NDJson, MessagePack, and more...) by `INTO` clause.
- **Next file formats**: Add next file formats [MessagePack](https://msgpack.org/), [Parquet](https://parquet.apache.org/docs/file-format/), [INI](https://en.wikipedia.org/wiki/INI_file) and [TOML](https://toml.io/en/)
- **Documentation**: Create detailed guides and examples for advanced use cases.
- **Tests**: Increase test coverage (90%+).
- **Hashmap cache**: Add hashmap cache (Redis, Memcache) for more memory efficient data processing.

10. Contributions
-----------------

[](#10-contributions)

If you have suggestions or would like to contribute to these features, feel free to open an issue or a pull request!

**How to contribute:**

- Fork the repository
- Create a new branch
- Make your changes
- Create a pull request
- All tests must pass
- Wait for approval
- 🚀

###  Health Score

50

—

FairBetter than 95% of packages

Maintenance92

Actively maintained with recent releases

Popularity21

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity65

Established project with proven stability

 Bus Factor1

Top contributor holds 93.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~9 days

Recently: every ~2 days

Total

51

Last Release

42d ago

Major Versions

v1.5.0 → v2.0.0-beta2025-01-28

PHP version history (2 changes)v1.0.0PHP >=8.1

v2.4.0PHP >=8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/13da3fbfa40eb5a98e777311648bb526c4e38e50b9bc6abaeccb55ae2fea2d02?d=identicon)[1biot](/maintainers/1biot)

---

Top Contributors

[![lebeda](https://avatars.githubusercontent.com/u/1889394?v=4)](https://github.com/lebeda "lebeda (208 commits)")[![1biot](https://avatars.githubusercontent.com/u/61222114?v=4)](https://github.com/1biot "1biot (15 commits)")

---

Tags

aggregation-functionscsv-parserdata-queryingdata-transformationjson-streamndjson-parserneon-parserphpquery-buildersql-syntaxstructured-datastructured-filesxls-readerxml-readeryaml-parser

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/1biot-fiquela/health.svg)

```
[![Health](https://phpackages.com/badges/1biot-fiquela/health.svg)](https://phpackages.com/packages/1biot-fiquela)
```

###  Alternatives

[kimai/kimai

Kimai - Time Tracking

4.6k7.4k1](/packages/kimai-kimai)[silverstripe/framework

The SilverStripe framework

7213.5M2.5k](/packages/silverstripe-framework)[craftcms/cms

Craft CMS

3.6k3.6M2.6k](/packages/craftcms-cms)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

19462.3M1.3k](/packages/drupal-core)[glhd/conveyor-belt

14797.0k](/packages/glhd-conveyor-belt)[shlinkio/shlink

A self-hosted and PHP-based URL shortener application with CLI and REST interfaces

4.8k4.3k](/packages/shlinkio-shlink)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)