DEV Community

Cover image for FiQueLa — SQL-like Queries for Structured Files in PHP
1biot
1biot

Posted on • Originally published at github.com

FiQueLa — SQL-like Queries for Structured Files in PHP

#php #tooling #development

Have you ever wished you could treat structured files — like JSON, XML, CSV, XLS, YAML, or NEON — the way you treat a database? What if you could query them with SQL-like syntax, filter, join, sort, and aggregate — all without the overhead of a database? That’s exactly what I built: FiQueLa — a lightweight PHP library for querying structured files with a familiar, powerful API.

🚀 Why FiQueLa?

In many projects, data lives outside databases — in spreadsheets, configuration files, exported logs, or large JSON dumps. Traditional approaches usually involve parsing these files and writing loops or custom logic to extract the data you need. That quickly gets messy and hard to maintain.

With FiQueLa, you can:

  • Treat different file formats uniformly
  • Query data using SQL-like syntax
  • Build fluent and intersecting queries
  • Handle large files efficiently with streaming support

Whether you’re building data pipelines, ETL tools, scripts, or command-line utilities — FiQueLa can simplify your workflow.

📦 What It Supports

FiQueLa works with a wide range of structured file formats and provides a unified querying interface across all of them.

Supported formats

  • XML
    Stream-friendly parsing suitable for large XML documents.

  • CSV
    Built on top of league/csv for reliable and flexible CSV handling.

  • XLS / XLSX (Excel)
    Powered by phpoffice/phpspreadsheet, read-only support for spreadsheet data, allowing you to query rows just like any other structured source.

  • JSON
    Native support, including efficient streaming for large files.

  • NDJSON (Newline-delimited JSON)
    Ideal for logs and incremental data processing.

  • YAML
    Powered by symfony/yaml, great for configuration files.

  • NEON
    Supported via nette/neon, commonly used in the PHP ecosystem.

All formats can be queried using the same SQL-like syntax or fluent API, so switching between them doesn’t require learning anything new.

🧠 Familiar SQL-like Queries

You can use FiQueLa in two ways:

1. Fluent API

Prefer the traditional SQL style? You can write full SQL-like strings:

use FQL\Query\Provider;

$results = 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();
Enter fullscreen mode Exit fullscreen mode

2. SQL Syntax

Prefer the traditional SQL style? You can write full SQL-like strings:

use FQL\Query;

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

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

⚡ Stream-friendly & Efficient

FiQueLa leverages streaming parsers (e.g., json-machine for JSON) to process large files without loading everything into memory. That lets you run queries against datasets with tens of thousands of records without breaking a sweat.

🛠 Features You’ll Love

  • Unified API across formats
  • Advanced functions like SUM, COUNT, GROUP_CONCAT, ARRAY_MERGE, DATE_FORMAT, and more
  • Map results to DTOs for clean data transformation
  • Powerful filtering, sorting, grouping just like SQL
  • Composable and readable queries

🧩 How It Helps You

Use FiQueLa if you:

  • Need fast extraction or transformation of data from files
  • Work with configuration or structured data outside of a database
  • Want an expressive, reusable query layer
  • Prefer writing queries you and your teammates can easily understand

📈 What’s Next

The project is actively evolving. Some planned enhancements include:

  • More file formats like MessagePack, Parquet and TOML
  • An explain plan for query debugging
  • Better memory optimization for JOIN and ORDER BY
  • Test coverage improvements

🔗 Get Started

Install FiQueLa using Composer:

composer require 1biot/fiquela
Enter fullscreen mode Exit fullscreen mode

Then add any optional format dependencies you need:

composer require league/csv halaxa/json-machine symfony/yaml nette/neon phpoffice/phpspreadsheet tracy/tracy
Enter fullscreen mode Exit fullscreen mode

Explore examples and docs on the repository, and try FiQueLa with your own datasets.

🙌 Final Thoughts

FiQueLa blends the power of SQL with the flexibility of file-based data — making complex queries simpler and more expressive, regardless of format. If data lives in files, you should be able to query it with confidence and elegance. That’s what I wanted to build — and that’s what FiQueLa delivers.

I’d love your feedback, contributions, and suggestions — check out the repo and let’s make file querying better together! 🚀

👉 1biot/FiQueLa

Top comments (0)