Skip to main content

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.

​
Overview

Namespace: FQL\Exception All FiQueLa exceptions extend either a standard PHP exception class or FQL\Exception\Exception (which itself extends \Exception). You can catch them by specific type or use the base classes to catch groups. 
use FQL\Query\Provider;
use FQL\Exception\FileNotFoundException;
use FQL\Exception\InvalidFormatException;
use FQL\Exception\Exception as FQLException;

try {
    $results = Provider::fromFile('data.json')
        ->select('id', 'name')
        ->execute();
} catch (FileNotFoundException $e) {
    // File does not exist or is not readable
} catch (InvalidFormatException $e) {
    // Unrecognised file extension or format
} catch (FQLException $e) {
    // Any other FiQueLa exception
}

​
Base exception

​
Exception

FQL\Exception\Exception extends \Exception
Root base class for most FiQueLa-specific exceptions. Catch this to handle any FiQueLa error that is not a logic error or a standard PHP SPL exception.

​
File and I/O exceptions

​
FileNotFoundException

FQL\Exception\FileNotFoundException extends Exception
Thrown when the file passed to fromFile(), open(), or any stream factory cannot be found on the filesystem or is not readable. Thrown by: Stream\Provider::fromFile(), Query\Provider::fromFile(), Csv::open(), and all other stream open() methods. 
use FQL\Exception\FileNotFoundException;

try {
    $query = \FQL\Query\Provider::fromFile('/non/existent/file.json');
} catch (FileNotFoundException $e) {
    echo 'File not found: ' . $e->getMessage();
}

​
FileAlreadyExistsException

FQL\Exception\FileAlreadyExistsException extends \RuntimeException
Thrown when attempting to create or write to a file that already exists and overwriting is not permitted.

​
UnableOpenFileException

FQL\Exception\UnableOpenFileException extends \Exception
Thrown when a file is found but cannot be opened for reading (e.g. due to OS-level permissions or a corrupted file handle).

​
FileQueryException

FQL\Exception\FileQueryException extends InvalidArgumentException
Thrown when a FileQuery string (the URI-style path used by fromFileQuery() and into()) is malformed or references a missing target file. Thrown by: ResultsProvider::into(), Query\Provider::fromFileQuery().

​
Format and argument exceptions

​
InvalidFormatException

FQL\Exception\InvalidFormatException extends Exception
Thrown when the file extension cannot be mapped to a known format, or when fromString() is called with an unsupported format. Also thrown for invalid CSV parameters (bad delimiter, unsupported encoding, etc.). Thrown by: Format::fromExtension(), Stream\Provider::fromFile(), Stream\Provider::fromString(), Format::fromString(). 
use FQL\Exception\InvalidFormatException;

try {
    $stream = \FQL\Stream\Provider::fromFile('archive.zip');
} catch (InvalidFormatException $e) {
    echo 'Unsupported format: ' . $e->getMessage();
}

​
InvalidArgumentException

FQL\Exception\InvalidArgumentException extends \InvalidArgumentException
Base class for all argument-validation exceptions in FiQueLa. Thrown when a method receives a value that is out of range or of the wrong type — for example, passing an unsupported operator string to Operator::fromOrFail(), or providing a non-scalar BETWEEN range.

​
UnexpectedValueException

FQL\Exception\UnexpectedValueException extends \UnexpectedValueException
Thrown when a value does not match the expected domain — for example, when trying to override already-set WHERE or HAVING conditions.

​
Query construction exceptions

These exceptions are thrown during query building (before execute() is called).

​
QueryLogicException

FQL\Exception\QueryLogicException extends \LogicException
Thrown when mutually exclusive query clauses are combined — specifically:
  • Using DISTINCT together with GROUP BY.
  • Using GROUP BY together with DISTINCT.
  • Using UNION with mismatched column counts between the main query and a union query.
use FQL\Exception\QueryLogicException;

try {
    $query->distinct()->groupBy('category'); // throws
} catch (QueryLogicException $e) {
    echo 'Query logic error: ' . $e->getMessage();
}

​
SelectException

FQL\Exception\SelectException extends InvalidArgumentException
Prefixes its message with SELECT:. Thrown when:
  • A field is selected more than once with select().
  • A modulo() division produces an unexpected value.

​
AliasException

FQL\Exception\AliasException extends InvalidArgumentException
Prefixes its message with AS:. Thrown when as() is called with:
  • An empty alias string.
  • An alias that is already used.
  • No preceding selected field to alias.
  • A field that was already aliased.

​
JoinException

FQL\Exception\JoinException extends InvalidArgumentException
Prefixes its message with JOIN:. Thrown when:
  • A join is added with an empty alias.
  • on() is called without a preceding join.

​
OrderByException

FQL\Exception\OrderByException extends InvalidArgumentException
Prefixes its message with ORDER BY:. Thrown when:
  • The same field is added to orderBy() twice.
  • asc() or desc() is called when no ordering has been set.

​
SortException

FQL\Exception\SortException extends InvalidArgumentException
Prefixes its message with ORDER BY:. Thrown by the sort execution phase when an unexpected error occurs while sorting the result set.

​
CaseException

FQL\Exception\CaseException extends InvalidArgumentException
Prefixes its message with CASE:. Thrown when the CASE expression builder methods are called out of order:
  • whenCase() without a preceding case().
  • elseCase() without a preceding case() or whenCase().
  • elseCase() called twice.
  • endCase() without a preceding case().

​
Runtime exceptions

​
NotImplementedException

FQL\Exception\NotImplementedException extends Exception
Thrown when a method or feature is not yet implemented. The constructor accepts a callable and generates a descriptive message like "Static method FQL\Stream\Csv::string not implemented yet." Currently thrown by Csv::string() (creating a CSV stream from a string is not supported).

​
SQL parser and function registry exceptions

These exceptions were introduced in FiQueLa 3.0 alongside the new SQL pipeline and FunctionRegistry.

​
ParseException

FQL\Sql\Parser\ParseException extends UnexpectedValueException
Thrown by Sql\Provider::compile(), parseExpression(), parseCondition(), and Query\Provider::fql() when an FQL string is syntactically invalid. The exception carries the offending token and its line/column information so callers can surface precise error locations. 
use FQL\Sql\Parser\ParseException;
use FQL\Sql\Provider as Sql;

try {
    Sql::compile('SELECT id name FROM csv(data.csv).*'); // missing comma
} catch (ParseException $e) {
    echo $e->getMessage(); // includes line/column of the offending token
}

​
UnknownFunctionException

FQL\Exception\UnknownFunctionException extends Exception
Thrown when a query references a function name that is not registered in the global FunctionRegistry. Register the function with FunctionRegistry::register(MyFn::class) at bootstrap before running the query.

​
FunctionRegistrationException

FQL\Exception\FunctionRegistrationException extends Exception
Thrown by FunctionRegistry::register(), override(), unregister(), and loadConfig() when a registration cannot be completed — for example, registering a class that does not implement ScalarFunction or AggregateFunction, or attempting to register a name that already exists without using override(). See Custom functions for the full registry API.

​
Exception hierarchy

\Exception
├── FQL\Exception\Exception
│   ├── FileNotFoundException
│   ├── InvalidFormatException
│   ├── NotImplementedException
│   ├── UnknownFunctionException
│   └── FunctionRegistrationException
├── \RuntimeException
│   └── FileAlreadyExistsException
├── \InvalidArgumentException
│   └── FQL\Exception\InvalidArgumentException
│       ├── FileQueryException
│       ├── SelectException
│       ├── AliasException
│       ├── JoinException
│       ├── OrderByException
│       ├── SortException
│       └── CaseException
├── \LogicException
│   └── QueryLogicException
├── \UnexpectedValueException
│   ├── FQL\Exception\UnexpectedValueException
│   └── FQL\Sql\Parser\ParseException
└── \Exception (direct)
    └── UnableOpenFileException