Download the PHP package krak/aql without Composer
On this page you can find all versions of the php package krak/aql. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package aql
AQL - API Query Language
API Query Language is a library designed to validate/transform string expressions to be used in API's for querying/filtering data. It allows user generated expressions to be used for querying data sets yet allows full verification to prevent any unwanted expression types.
Installation
Install with composer at krak/aql
.
Usage
An example might be the easiest way to understand what this library does.
The AQL\Engine::process
does several things.
- It parses the expression into an AST. Any syntax or lexing errors will be thrown here. This includes bad characters or an invalid expression.
- It runs semantic analysis on the generated AST which will verify that the expression makes sense and can enforce any custom domain rules. In the example above, it makes sure the fields being compared are within the
orders.{status,created_at}
domain. - It runs any custom transformations
- It then compiles the AST back into a string to be used for generating queries.
The final $processed_query
is now validated and can be used as part of an SQL where clause or something similar. Thus, it provides a way for API's to support a powerful query interface while providing total control of the queries generated.
Sort Queries
In addition to expression queries that can be used in database WHERE
clause. The library also supports parsing sort expressions which might show up in a database ORDER BY
clause.
Visitors
Visitors provide a way to transform the AST. In context of the engine, visitors are run after semantic analysis. Each visitor implements Krak\AQL\AST\Visitor
. The AST accepts the visitor and then traverses itself with a Depth First Pre-Order Traversal.
Chain Visitor
The chain visitor Krak\AQL\AST\ChainVisitor
accepts an array of other visitors. As it the AST is being traversed, it delegates to each of the other visitors. This allows for many transformations in one Pass.
DoubleToSingleQuotes Visitor
This visitor Krak\AQL\Visitor\DoubleToSingleQuotesVisitor
transforms double quoted strings to single quotes.
So this input:
would be be mapped to:
RenameId Visitor
This visitor Krak\AQL\Visitor\RenameIdVisitor
renames identifiers. You can use dot notation to access sub identifiers.
Using this rename visitor, it'd apply the following transformation:
Goes to:
FuncEval Visitor
The FuncEval lets your evaluate a function and transform it into another Element value.
It can turn an input:
to:
Checkout example/func-eval.php to see a working example.
Semantic Analysis
Semantic Analysis provides extra validation of the parsed AST to make sure the parsed expression is semantically correct.
SA Enforcers are simply just visitors that will throw an SAException
if the AST failed semantic analysis. SA is done via a single pass because it makes use of the AST\ChainVisitor
.
To utilize SA, you create your list of enforces and construct the SemanticAnalysis
object.
EnforceDomain
Enforces identifiers are within a certain domain.
This would allow any identifier path like user.id
, user.email
, user.group.id
and a few others.
EnforceFunc
Enforces only certain functions to be used.
This would allow only the now
and date
functions to be used, anything else would throw an exception.
Parser
There are two interfaces into the AQLParser: ExpressionParser and SortParser.
The ExpressionParser will assume a string input is an expression and parse accordingly. The SortParser will assume a string is a SortExpressionList and parse accordingly. Each Parser will return a root AST node of Expression or SortExpressionList accordingly.
Operators
From highest to lowest precedence
EBNF (Grammar)
Expression ::= AndExpression | AndExpression "OR" Expression
AndExpression ::= OpExpression | OpExression "AND" AndExpression
OpExpression ::= Element
OpExpression ::= Element "<" OpExpression
OpExpression ::= Element ">" OpExpression
OpExpression ::= Element "=" OpExpression
OpExpression ::= Element "!=" OpExpression
OpExpression ::= Element "<=" OpExpression
OpExpression ::= Element ">=" OpExpression
OpExpression ::= Element "LIKE" OpExpression
OpExpression ::= Element "IN" "(" ValueList ")"
Element ::= Value | IdExpression | Func | "(" Expression ")"
Value ::= string | number
ValueList ::= Value | Value "," ValueList
IdExpression ::= identifier | identifier "." IdExpression
Func ::= identifier "(" ElementList ")"
ElementList ::= Element | Element "," ElementList
SortExpressionList ::= SortExpression | SortExpression "," SortExpressionList
SortExpression ::= IdExpression "DESC"
SortExpression ::= IdExpression "ASC"
SortExpression ::= IdExpression
string = "[^"]\*"
number = (\d*\.\d+|\d+)
identifier = [_a-zA-Z][_a-zA-Z0-9]*
Tests
Tests are executed via Peridot