\MySQLTableReport

class MySQLTableReport Generic reporting class. Given a configuration file, that describes the tables and fields to be searched, and information to connect to a database, take form data and generate an SQL query to run.

The report object is made to address a certain class of reports: Time series data, to aggregate by some arbitrary column and return the SUM/MIN/MAX/AVG/etc of other columns.

Basic usage: $report = new MySQLTableReport( $datasource, $tables, $report);

// run the query and get the result and header data $result = $report->execute($sql); $columns = $report->get_column_names();

// ... display as desired.

the parameters above have the following forms: $datasource = array( 'host' => $host, // the mysql server hostname 'port' => $port, // optional port number 'user' => $user, // the user credential 'password' => $pass, // the password for the user 'db' => $db, // the database name );

$tables = array( 'fact_table_name' => 'fact', // table_name => alias 'dimension_table_name' => 'dimension', // table_name => alias );

The aliases used for tables are mostly anything you choose except that one table must have the alias 'fact'. This is considered the root table to which any additional tables can be joined. There can be only one fact table, but you can have any number of dimension tables as long as each have unique aliases

$report = array(

 // the JOIN clause for any dimension tables.  Specify the exact clause used
 // for each table alias
 'join'      => array(
     'dimension'     =>  "USING (id)",
 ),

 // fields for the tables; defined by the table's alias and not the real table name
 // this allows the exact same report to be used on tables with the same structure
 // but different names
 'fields'    => array(
     'fact'  => array(
         'name'      => 'clear|where',

         // note that these aren't field names in the table, but we need
         // a place to put them for the form processor to handle them
         // the filters here will make sure the data gets added to the right
         // part of the query, and not the WHERE clause like other fields.
         'group'     => 'group',
         'order'     => 'order',
         'having'    => 'having',
         'limit'     => 'limit',
     ),

     'dimension' => array(
         'date'      => 'date_range|clear|where',
         'price'     => 'ge|clear|where'
     )

 ), // end fields

 // custom fields are allowed as well
 'custom_fields' => array(
         'epoch'     =>  'FROM_UNIXTIME(date)',
         'snippet'   =>  'LEFT(info,15)'
 )

);

Summary

Methods
Properties
Constants
__construct()
set_non_aggregate_columns()
set_pivot_values()
get_pivot_values()
get_tables()
get_table_by_alias()
get_form_fields()
get_custom_fields()
get_table_fields()
get_distinct_values()
get_form_field_values()
select()
from()
join()
where()
group()
order()
limit()
having()
raw_where()
pivot()
date_range()
reldate()
clear()
ge()
le()
gt()
lt()
ne()
like()
process_form_data()
remove_schema_name()
query()
get_column_names()
execute()
get_search_uri()
No public properties found
No constants found
No protected methods found
No protected properties found
N/A
init_report()
connect_to_datasource()
get_column_aggregate_function()
filter_where()
check_mysql_error()
$datasource
$tables
$report
$form_fields
$pivot
$form_data_processed
$sql
$select
$from
$join
$where
$having
$order
$limit
$raw_where
$non_aggregate_columns
$CONNECT_TIMEOUT
N/A

Properties

$datasource

$datasource : 

Type

$tables

$tables : 

Type

$report

$report : 

Type

$form_fields

$form_fields : 

Type

$pivot

$pivot : 

Type

$form_data_processed

$form_data_processed : 

Type

$sql

$sql : 

Type

$select

$select : 

Type

$from

$from : 

Type

$join

$join : 

Type

$where

$where : 

Type

$having

$having : 

Type

$order

$order : 

Type

$limit

$limit : 

Type

$raw_where

$raw_where : 

Type

$non_aggregate_columns

$non_aggregate_columns : 

Type

$CONNECT_TIMEOUT

$CONNECT_TIMEOUT : 

Type

Methods

__construct()

__construct(array  $datasource, array  $tables, array  $report) 

create a new instance, pass configuration information describing the datasource and the report tables and fields.

Parameters

array $datasource

Database connection information required :host,user,password,db; optional: port

array $tables

Tables to use for this report. format is array( 'table_name' => 'alias' ) there must be at least one "fact" table, and optionally a "dimension" table

array $report

config array describing the table structure and other options

set_non_aggregate_columns()

set_non_aggregate_columns(array  $columns) 

Parameters

array $columns

set_pivot_values()

set_pivot_values(string  $col_name, array  $values) 

pivot operations require some setup -- this defines the list of values to turn into additional columns when we ask the report to pivot a column.

Parameters

string $col_name

the name of the column to pivot

array $values

the list of values

get_pivot_values()

get_pivot_values(string  $col_name) : array

return the list of values for a given pivot column

Parameters

string $col_name

the name of the pivot column

Returns

array —

the list of values defined by set_pivot_values

get_tables()

get_tables() : array

returns the list of table names, not the aliases

Returns

array

get_table_by_alias()

get_table_by_alias(string  $alias) : string

gets the concrete name of a table for the given alias

Parameters

string $alias

The alias name to fetch the table for

Throws

\Exception

if the alias doesn't exist

Returns

string —

The real table name

get_form_fields()

get_form_fields() : array

return the list of form fields defined by the configuration parameters used to construct this object. Field names are prefixed by the table *alias*

so if the configuration section looked like : 'fields' => array( 'fact' => array( 'checksum' => '...', ), 'dimension' => array( 'hostname' => '...', ),

The result would be an array with the values ('fact-checksum', 'dimension-hostname').

These are the form field names that will be checked to build the search parameters.

Returns

array —

the form fields

get_custom_fields()

get_custom_fields() : array

returns a list of custom fields names.

Custom fields are additional columns that can be used in the SELECT clause, but not as WHERE or other conditions. They are defined in the configuration used to create the object

Returns

array —

the custom field list

get_table_fields()

get_table_fields(string  $table_name = null) : array

select the field names for the report tables from the database.

Parameters

string $table_name

optional table name. If none is provided, all tables defined in the report will be queried.

Returns

array —

the list of columns defined in the database tables.

get_distinct_values()

get_distinct_values(string  $table, string  $colname) : array

given a table and column, find all the unique values. This is a utility method often used when building dropdown lists on a search form, or getting values for pivot operations.

Parameters

string $table

the table name

string $colname

the column name

Returns

array —

the list of unique values

get_form_field_values()

get_form_field_values() : array

return an associate array with form_field_name => value for all fields.

Returns

array —

the array of field names and values

select()

select(string  $field, string  $alias, string  $aggregate) : \MySQLTableReport

add a column to the select field list

Parameters

string $field

the field name

string $alias

the field alias

string $aggregate

how to optionally aggregate values in this column

Returns

\MySQLTableReport

from()

from(array  $table) : \MySQLTableReport

define the primary table to select from

Parameters

array $table

The table to select from; the format is array(table_name, alias)

Returns

\MySQLTableReport

join()

join(array  $table) : \MySQLTableReport

add a table to the JOIN clause

Parameters

array $table

The table to join; the format is array(table_name, alias)

Returns

\MySQLTableReport

where()

where(string  $key, string  $var_name, string  $value, string  $op = null) : \MySQLTableReport

add a condition to the WHERE clause.

Parameters

string $key

the full column name including table alias

string $var_name

the name of the form variable for this column

string $value

the form value

string $op

the conditional operator to use; default =

Returns

\MySQLTableReport

group()

group(string  $col_name, string  $var_name, string  $expression) : \MySQLTableReport

set the GROUP BY expression

Parameters

string $col_name

the name of the form field as a column

string $var_name

the form variable name

string $expression

the group by expression

Returns

\MySQLTableReport

order()

order(  $key,   $field, string  $expression) : \MySQLTableReport

set the ORDER BY clause

Parameters

$key
$field
string $expression

the order by expression

Returns

\MySQLTableReport

limit()

limit(  $key,   $field, string  $expression) : \MySQLTableReport

set the LIMIT clause

Parameters

$key
$field
string $expression

the limit expression

Returns

\MySQLTableReport

having()

having(  $key,   $field, string  $expression) : \MySQLTableReport

set the HAVING clause

Parameters

$key
$field
string $expression

the having expression

Returns

\MySQLTableReport

raw_where()

raw_where(string  $key, string  $field, string  $expression) 

raw_where is an unprocessed string that is added to the WHERE clause

Parameters

string $key

ignored

string $field

ignored

string $expression

The raw WHERE expression

pivot()

pivot(string  $col_name, string  $var_name, string  $expression) : \MySQLTableReport|string

preform a pivot on a column. Get the unique list of values and return them as a conditional aggregate expression to be added to the select clause. Right now only one aggregate type is supported: SUM Also a little black magic is used to get the column name from the synthetic column name needed here. The column in the form and config should be called: pivot-{$column_name} and it's value should be the column to return when the expression is true.

For example, if you have a hostname column with a count of signups, and you want to pivot on the hostname and return the aggregate signups for each host as its own column, then the form field should look like:

Count signups per-host

The report object config would look like:

'fields' => array( 'dimension' => array( 'pivot-hostname' => 'pivot|select', ) )

Then remember to set the unique list of value for this pivot operation:

$report = new MySQLTableReport( ... ); $hosts = $report->get_distinct_values('dimension','hostname'); $report->set_pivot_values('dimension-pivot-hostname', $hosts);

Parameters

string $col_name

The name of the pivot column

string $var_name

The field variable name

string $expression

The column to return in the IF($col_name}='value' ... ) expression

Returns

\MySQLTableReport|string

date_range()

date_range(string  $col_name, string  $var_name, string  $expression) : array

look for a range of date values for the given column, and return values to be added to the WHERE clause

This is used when you have a column like "invoice_date" in the report, but what you really want to search for is a range of dates between a given start and end date.

To do that, create form fields with _start and _end added to the name, and pass the column to this processor. It will search for the appropriate form fields and build the range.

The config settings would look like:

'fields' => array( 'dimension' => array( 'invoice_date' => 'date_range|clear|where', ) )

Parameters

string $col_name

the base column name

string $var_name

the base field variable name

string $expression

ignored

Returns

array —

the list of expressions to pass to the where function

reldate()

reldate(  $col_name,   $var_name,   $expression,   $op) 

Parameters

$col_name
$var_name
$expression
$op

clear()

clear(string  $col_name, string  $var_name, string  $expression,   $op = null) : \MySQLTableReport

Remove blank strings as values in form fields.

Most cases, the forms you create can have empty fields which mean those conditions should be omitted from the WHERE clause. However, the form will send and empty string. When you want an empty field to be removed from the WHERE clause, pass it through the clear filter first.

'fields' => array( 'dimension' => array( 'hostname' => 'clear|where', // if hostname is blank, do not include it in the query. ) )

Parameters

string $col_name

the name of the form field as a column

string $var_name

the form variable name

string $expression

the value of the field

$op

Returns

\MySQLTableReport

ge()

ge(string  $col_name, string  $var_name, string  $expression) : array

apply a "greater than or equal to" operator to a WHERE condition, instead of the default equality matching

By default a configuration section like this would produce equality matching:

'fields' => array( 'dimension' => array( 'price' => 'clear|where', // generates SQL such as: WHERE price = ) )

If you need a range of values, include the appropriate operator as a filter:

'fields' => array( 'dimension' => array( 'price' => 'clear|ge|where', // generates SQL such as: WHERE price >= ) )

Parameters

string $col_name

The column name

string $var_name

The field variable name

string $expression

The field value

Returns

array —

condition to pass to next filter

le()

le(string  $col_name, string  $var_name, string  $expression) : array

less than or equal to: see documentation for ge()

Parameters

string $col_name

The column name

string $var_name

The field variable name

string $expression

The field value

Returns

array —

condition to pass to next filter

gt()

gt(string  $col_name, string  $var_name, string  $expression) : array

greater than: see documentation for ge()

Parameters

string $col_name

The column name

string $var_name

The field variable name

string $expression

The field value

Returns

array —

condition to pass to next filter

lt()

lt(string  $col_name, string  $var_name, string  $expression) : array

less than: see documentation for ge()

Parameters

string $col_name

The column name

string $var_name

The field variable name

string $expression

The field value

Returns

array —

condition to pass to next filter

ne()

ne(string  $col_name, string  $var_name, string  $expression) : array

not equals: see documentation for ge()

Parameters

string $col_name

The column name

string $var_name

The field variable name

string $expression

The field value

Returns

array —

condition to pass to next filter

like()

like(string  $col_name, string  $var_name, string  $expression) : array

like: see documentation for ge()

Parameters

string $col_name

The column name

string $var_name

The field variable name

string $expression

The field value

Returns

array —

condition to pass to next filter

process_form_data()

process_form_data() 

Read all form data and process values. This will be called automatically by query() and execute() methods.

remove_schema_name()

remove_schema_name(  $column) 

Parameters

$column

query()

query() : string

generate the SQL query and return it as a string.

Returns

string —

the SQL query build by this report object

get_column_names()

get_column_names() : array

Returns a list of all column names. These will be exactly the same as the columns returned by the query.

Returns

array —

the list of column names

execute()

execute(string  $sql = null) : array

Execute the generated query on the configured database and return a result handle

Parameters

string $sql

optional sql to execute.

Throws

\Exception

if there is an error executing the query

Returns

array —

array that contains the result set

get_search_uri()

get_search_uri(array  $exceptions = null) : string

return a urlencoded string of parameters that were used in this report.

Parameters

array $exceptions

List of variables names not to append

Returns

string —

The url string

init_report()

init_report() 

reset internal variables

connect_to_datasource()

connect_to_datasource() 

make a connection to the database, die with an error if this doesn't work

get_column_aggregate_function()

get_column_aggregate_function(\type  $name) : null|string

given a column name, try to guess the aggregate function name. For now this expects columns with a format like colname_cnt colname_max colname_avg

It checks the last letters after an underscore and returns an aggregate function that most closely matches. Supported types are: _sum _cnt = SUM _avg, _median = AVG _min, _95, _stddev = MIN _max = MAX

Parameters

\type $name

Returns

null|string

filter_where()

filter_where() 

removes all where conditions where the value of the expression is null.

check_mysql_error()

check_mysql_error(\MySQLi_Result  $result) 

check the result of a mysqli query and throw and exception if there was an error

Parameters

\MySQLi_Result $result

handle to the result set

Throws

\Exception

if there was a query error