Download the PHP package lmc/api-filter without Composer

API Filter

Parser/builder for filters from API query parameters.

It is just a parser/builder for filters, it is not a place for business logic so it should be wrapped by your class if you want to be more strict about filters. Same if you want different settings per entity/table, it should be done by a specific wrapper around this library.

Table of Contents

• Installation
• Usage
  • Initialization
  • With Doctrine Query Builder
  • With simple SQL
• Supported filters
  • Equals
  • Not Equals
  • Greater than
  • Greater than or Equals
  • Lower than
  • Lower than or Equals
  • IN
• Tuples in filters
• Examples
  • IN + EQ
  • GT + LT (between)
  • EQ Tuple
• Functions in filters
  • Example for fullName function
  • Function parameters definition
    • By string
    • By array
    • By object
    • Combinations
  • Register and Execute function
• Exceptions and error handling
• Development

Installation

Usage

For example lets have query parameters from following request

Initialization

With Doctrine Query Builder Applicator

• requires doctrine/orm installed
• applying filters uses cloned QueryBuilder -> original QueryBuilder is untouched

Example

Shorter example (same as ☝)

With SQL Applicator

• ❗it is just a naive implementation and should be used carefully❗
• it still might be used on simple SQLs without ORDER BY, GROUP BY etc. because it simply adds filters as a WHERE conditions

SQL Applicator must be registered explicitly

Example

Shorter example (same as ☝)

Supported filters

Equals - EQ (=)

Both examples ☝ are equal

Not Equals - NEQ (!=)

Greater Than - GT (>)

Greater Than Or Equals - GTE (>=)

Lower Than - LT (<)

Lower Than Or Equals - LTE (<=)

IN

• Tuples are not allowed in IN filter

Function

• there is much more options and possibilities with functions which you can see here

Tuples in filters

Tuples

• are important in filters if you have some values, which must be sent together
• are composed of two or more values (Tuple of one value is just a value)
• items must be in ( ) and separated by ,
  • array in Tuple must be in [ ] and items separated by ;
• it is advised NOT to use a space between values because of the URL specific behavior
• for more information about Tuples see https://github.com/MortalFlesh/MFCollectionsPHP#immutabletuple

Column with Tuple

Columns declared by Tuple behaves the same as a single value but its value must be a Tuple as well. Columns can contain a filter specification for each value.

• default filter is EQ for a single value and IN for an array of values (in Tuple)

Values with Tuple

Values in the Tuple must have the same number of items as is the number of columns. Values can contain a filter specification for all values in a Tuple.

❗NOTE: A filter specification must not be in both columns and values.

Usage

☝ means that you have two columns first and second and they must be sent together. Column first must equal the value "one" and column second must equal the value "two".

Examples

❗For simplicity of examples, they are shown on the SQL Applicator which is NOT auto-registered❗

IN + EQ filter

GT + LT filter (between)

EQ with Tuple

More Examples

Equals (implicit and explicit)

Result:

Multiple filters (implicit and explicit)

By single values

By Tuples

Result:

Multiple filters

You can mix all types of filters (tuples, explicit, implicit).

Perfect wife by generic filters

By single values

By Tuples

Result:

Want to see movies by generic filters

By single values

By Tuples

Result:

Functions in filters

With function you can handle all kinds of problems, which might be problematic with just a simple filters like eq, etc.

Example for fullName function

Let's see how to work with functions and what is required to do. We will show it right on the example.

Expected api

☝️ example above shows what we want to offer to our consumers. It's easy and explicit enough.

It may even hide some inner differences, for example with simple filters, database column must have same name as field in filter, but with function, we can change it.

Let's say that in database we have something like:

Initialization

First of all, you have to define functions you want to use.

Method declareFunction will create a function with filters based on parameters.
There is also registerFunction method, which allows you to pass any function you want. This may be useful when you dont need filter functionality at all or have some custom storage, etc.

Parsing and applying filters

Now when request with ?fullName=(Jon,Snow) come, ApiFilter can parse it to:

Supported function usage

All examples below results the same. We have that many options, so we can allow as many different consumers as possible.

Function Parameters Definition

To declare or register function, you have to define its parameters. There are many ways/needs to do it.

Defined as string

This is the easiest way to do it. You just define a name.

It means:

• you want eq filter (or IN for array) and the column name and parameter name are the same
• the value for this parameter is mandatory

Defined as array

This allows you to pass more options for a paramater.

Only one item

If you declare it just by giving the only item, it is the same as definition by string above.

More than one item

It means

• firstName parameter uses eq filter, has first_name column in storage and is mandatory
• surname parameter uses eq filter, has lastname column in storage and its value is Snow (which will always be used and no value can override it)

Defined as object

This allows you to pass same options as with the array, but explicitly defined object. (It even has some special constructor methods to simplify creation)

Combinations

All options can be combined to best suite the parameter.

Declaration

Usage

Register and Execute function

Example below is just for explicit demonstration, you should probably never allow execute SQL queries like this.

Usage in PHP

Usage of the API

All examples below results the same. We have that many options, so we can allow as many different consumers as possible.

Exceptions and error handling

Known exceptions occurring inside ApiFilter implements Lmc\ApiFilter\Exception\ApiFilterExceptionInterface. The exception tree is:

Please note if you register a custom applicator to the ApiFilter (via $apiFilter->registerApplicator()), it may throw other exceptions which might not implement ApiFilterExceptionInterface.

Development

Install

Tests

Todo

• defineAllowed: (this should be on DI level)
  • Fields (columns)
  • Filters
  • Values
• add more examples:
  • different configuration per entity/table