FlupdoGenericListing Class Reference

A very generic listing based on Flupdo::SelectBuilder. More...

Inheritance diagram for FlupdoGenericListing:

Public Member Functions
	__construct (AbstractMachine $machine,\Flupdo::Flupdo::SelectBuilder $query_builder, $query_filters, $machine_table, $machine_filters, $machine_properties, $machine_references)
	Prepare query builder. More...
	getQueryBuilder ()
	Get raw query builder. More...
	query ()
	Execute SQL query or do whatever is required to get this listing populated.
	describeProperties ()
	Get description of all properties (columns) in the listing.
	fetchAll ()
	Returns an array of all items in the listing. More...

Protected Attributes
	$machine
	Parent state machine, which created this listing.
	$query
	SQL query to execute.
	$result
	PDOStatement, result of the query.

Detailed Description

A very generic listing based on Flupdo::SelectBuilder.

Default Filter Syntax

Syntax is designed for use in query part of URL. First, filter name is looked up in statemachine filters. If not found, filter name is considered a property name and if matches, equality condition is added. Otherwise if operator is detected at the end of property name, given condition is added.

Note

Please keep in mind that there is '=' character in URL between filter name and value. For example '<' filter looks like ...?property<=value.

Warning

Filters are in fact simple key-value structure. Conditions described below are only an ilusion. All this only means that for each state machine property a group of filters is generated (on demand).

Conditions:

• ! means "not equal".
• < means "lesser or equal".
• << means "less than".
• > means "greater or equal".
• >> means "greater than".
• : is range check. The value must be in format min..max or min...max. Two dots means min <= x < max. Three or more dots include max (min <= x <= max; using BETWEEN operator). The value may be also an array of two elements or with 'min' and 'max' keys.
• ~ is REGEXP operator.
• % is LIKE operator.
• !:, !~ and !% are negated variants of previous three operators.

Predefined filters:

• limit (int; default = 100)
• offset (int; default = undefined)
• order-by (property/column name; default = undefined)
• order-asc (bool; default = true; applied only when order-by is set)

Example:

Select all items, where foo is greater or equal to 5, and bar is between 10 and 20 (excluding 20), and category is 'fruit'.

http://example.com/items?foo>=5&bar:=10..20&category=fruit

$filter = array(
    'foo>' => 5,
    'bar:' => array(10, 20),
    'category' => 'fruit',
)

Custom filters

FlupdoMachine machine can have filters option set. This option defines custom filters. Custom filters will override predefined filters of the same name.

Each filter is list of statements added to Flupdo::SelectBuilder. Each filter must have these properties defined:

• stmt: Name of SelectBuilder method which adds the statement.
• sql: Raw SQL code with positional parameters (question marks).
• params: Filter names wich values will be passed as query parameters. These must be in the same order as in sql.

Note

Operators of default filters have nothing to do with custom filters.

Filter can be defined as a simple filter using query property, or as value-dependent filter using query_map property. The query_map will select one of specified filters by filter value. The query is used when query_map is missing or no value is matched.

Example

"filters": {
    "path": {
        "query": [
            {
                "stmt": "where",
                "sql": "`path_mask` = ? OR `path_mask` = \"*\" OR ? REGEXP CONCAT(\"^\", REPLACE(`path_mask`, \"*\", \"[^/]+\"), \"$\")",
                "params": [ "path", "path" ]
            }
        ]
    },
    "date": {
        "query_map": {
            "past": [
                {
                    "stmt": "where",
                    "sql": "mtime < NOW()",
                    "params": [ ]
                }
            ],
            "future": [
                {
                    "stmt": "where",
                    "sql": "mtime >= NOW()",
                    "params": [ ]
                }
            ]
        },
        "query": [
           {
               "stmt": "where",
               "sql": "mtime BETWEEN NOW() - INTEVAL ? DAY AND NOW + INTERVAL ? DAY",
               "params": [ "date", "date" ]
           }
        ]
    }
}

Possible use:

• http://example.com/item?date=past&path=/foo/bar – select items modified in past and matching given path.
• http://example.com/item?date=2 – select items modified within +/- 2 days from now.

Note

Additional properties may be added to filter definition. It is expected that GUI will be generated from this definition as well.

Constructor & Destructor Documentation

__construct	(	AbstractMachine	$machine,
		\Flupdo::Flupdo::SelectBuilder	$query_builder,
			$query_filters,
			$machine_table,
			$machine_filters,
			$machine_properties,
			$machine_references
	)

Prepare query builder.

Parameters

$machine	State machine implementation to inspect.
$query_builder	Query builder where filters will be added.
$query_filters	Requested filters to add to $query_builder.
$machine_filters	Custom filter definitions (how things should be filtered, not filtering itself).
$machine_properties	State machine properties definitions.
$machine_references	State machine references to other state machines.

Here is the call graph for this function:

Member Function Documentation

getQueryBuilder

(

)

Get raw query builder.

It may be useful to configure query outside of this listing, but it is ugly. It is also specific to FlupdoGenericListing only.

fetchAll

(

)

Returns an array of all items in the listing.

This decodes properties.

Implements IListing.

Here is the call graph for this function: