Perforce Chronicle 2012.2/486814
API Documentation
Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes

P4Cms_Record_Filter Class Reference

Constructs fstat filter expressions specifically for filtering records via fetchAll(). More...

Inheritance diagram for P4Cms_Record_Filter:
P4_File_Filter

List of all members.

Public Member Functions

 __construct ($filterOptions=null)
 The constructor accepts an optional string or array of filter conditions to apply to the new filter object.
 add ($field, $value, $comparison=self::COMPARE_EQUAL, $connective=self::CONNECTIVE_AND, $caseInsensitive=null)
 Extend parents add to assume Record field (attribute) conditions are being added to the filter.
 addFstat ($field, $value, $comparison=self::COMPARE_EQUAL, $connective=self::CONNECTIVE_AND, $caseInsensitive=null)
 Add a fstat field condition to the filter.
 addSearch ($fields, $query)
 Add filters to search for keywords across the given fields.
 getOption ($name)
 Retrieve a custom option by name.
 setOption ($name, $value)
 Store custom filter options that don't correspond to built-in options.

Public Attributes

const FALSE_EXPRESSION = '-'

Protected Member Functions

 _normalizeFilterOptions ($field, $filter)
 Called from the constructor to normalize an array of options for field or fstat filters.

Protected Attributes

 $_options = array()

Detailed Description

Constructs fstat filter expressions specifically for filtering records via fetchAll().

Copyright:
2011-2012 Perforce Software. All rights reserved
License:
Please see LICENSE.txt in top-level folder of this distribution.
Version:
2012.2/486814

Constructor & Destructor Documentation

P4Cms_Record_Filter::__construct ( $  filterOptions = null)

The constructor accepts an optional string or array of filter conditions to apply to the new filter object.

String conditions are handled by P4_File_Filter.

Example simple form: array( 'fields' => array('title' => 'News', 'body' => 'today'), 'fstat' => array('headAction' => 'edit', 'headType' => 'xtext'), 'search' => array('fields' => array('title', 'body'), 'query' => 'search keywords'), 'categories' => array('foo', 'bar')

Example complex form: array( 'fields' => array( array( 'field' => 'title', 'value' => 'News', 'comparison' => P4Cms_Record_Filter::COMPARE_EQUAL, 'connective' => P4Cms_Record_Filter::CONNECTIVE_OR, 'caseInsensitive' => true), array( 'field' => 'body', 'value' => 'today', 'comparison' => P4Cms_Record_Filter::COMPARE_CONTAINS, 'connective' => P4Cms_Record_Filter::CONNECTIVE_OR)), 'fstat' => array( array( 'field' => 'headAction', 'value' => 'edit', 'comparison' => P4Cms_Record_Filter::COMPARE_EQUAL, 'connective' => P4Cms_Record_Filter::CONNECTIVE_OR, 'caseInsensitive' => false), array( 'field' => 'headType', 'value' => 'xtext', 'comparison' => P4Cms_Record_Filter::COMPARE_EQUAL, 'connective' => P4Cms_Record_Filter::CONNECTIVE_AND, 'caseInsensitive' => false)), 'search' => array('fields' => array('title', 'body'), 'query' => 'search keywords'), 'categories' => array('foo', 'bar')

Parameters:
string | array$filterOptionsstring expression or array of filter options.

Reimplemented from P4_File_Filter.

    {
        // let parent handle string arguments.
        if (is_string($filterOptions)) {
            return parent::__construct($filterOptions);
        }

        // if argument is not an array with elements, get out
        if (!is_array($filterOptions) || empty($filterOptions)) {
            return;
        }

        // process different types of filter conditions:
        //  - record field conditions
        //  - fstat field conditions
        //  - search conditions
        //  - unknown conditions (stored as custom options).
        foreach ($filterOptions as $type => $filters) {
            if ($type == 'fields' || $type == 'fstat') {
                $method = $type == 'fields' ? 'add' : 'addFstat';
                foreach ($filters as $field => $filter) {
                    call_user_func_array(
                        array($this, $method),
                        $this->_normalizeFilterOptions($field, $filter)
                    );
                }
            } else if ($type == 'search') {
                if (isset($filters['fields']) && isset($filters['query'])) {
                    $this->addSearch($filters['fields'], $filters['query']);
                }
            } else {
                $this->setOption($type, $filters);
            }
        }
    }

Member Function Documentation

P4Cms_Record_Filter::_normalizeFilterOptions ( $  field,
$  filter 
) [protected]

Called from the constructor to normalize an array of options for field or fstat filters.

Two forms of input: simple and complex.

In the simple case, the field (taken from the array key) is a string and the filter is the value we are filtering for (taken from the array value).

In the complex case, the field is numeric and the filter is an array of filter options including the field name and the value we are searching for.

Parameters:
string | null$fieldoptional field name - if null, field is in filter array.
string | array | null$filterfilter options or filter value if field is given.
Returns:
array an array of filter options that has all of the required keys 
    {
        // determine if filter options are simple or complex
        // if field is an integer, we are assuming the complex usage
        // in which case filter must be an array of filter options.
        if (is_integer($field) && !is_array($filter)) {
            throw new InvalidArgumentException('Field filter options must be an array.');
        }

        // normalize complex and simple cases.
        //  - complex case is a numeric field and all filter options in an array under filter
        //  - simple case is a string field and value provided under filter
        if (is_integer($field)) {
            // complex case
            return array(
                'field'           => isset($filter['field'])           ? $filter['field']      : null,
                'value'           => isset($filter['value'])           ? $filter['value']      : null,
                'comparison'      => isset($filter['comparison'])      ? $filter['comparison'] : static::COMPARE_EQUAL,
                'connective'      => isset($filter['connective'])      ? $filter['connective'] : static::CONNECTIVE_AND,
                'caseInsensitive' => isset($filter['caseInsensitive']) ? $filter['caseInsensitive'] : null
            );
        } else {
            // simple case
            return array(
                'field'           => $field,
                'value'           => $filter,
                'comparison'      => static::COMPARE_EQUAL,
                'connective'      => static::CONNECTIVE_AND,
                'caseInsensitive' => null
            );
        }
    }
P4Cms_Record_Filter::add ( $  field,
$  value,
$  comparison = self::COMPARE_EQUAL,
$  connective = self::CONNECTIVE_AND,
$  caseInsensitive = null 
)

Extend parents add to assume Record field (attribute) conditions are being added to the filter.

Will not work for 'file' fields.

Parameters:
string$fieldRecord field to filter on
null | string | array$valueValue we are comparing to as string, null or array of strings. If an array is given, condition will pass if any of the values satisfy the comparison.
string$comparisonoptional - comparison operator to use, defaults to Equal
string$connectiveoptional - logical connective operator
null | boolean$caseInsensitiveoptional - case-insensitive matching preference, default to null.
Returns:
P4Cms_Record_Filter provides fluent interface.

Reimplemented from P4_File_Filter.

    {
        if (!is_string($field) || empty($field)) {
            throw new InvalidArgumentException(
                "Cannot add condition. Field must be a non-empty string."
            );
        }
        return $this->addFstat('attr-' . $field, $value, $comparison, $connective, $caseInsensitive);
    }
P4Cms_Record_Filter::addFstat ( $  field,
$  value,
$  comparison = self::COMPARE_EQUAL,
$  connective = self::CONNECTIVE_AND,
$  caseInsensitive = null 
)

Add a fstat field condition to the filter.

Equivalent to parent classes 'add' function.

Parameters:
string$fieldFstat field to filter on
null | string | array$valueValue we are comparing to as string, null or array of strings. If an array is given, condition will pass if any of the values satisfy the comparison.
string$comparisonoptional - comparison operator to use, defaults to Equal
string$connectiveoptional - logical connective operator
null | boolean$caseInsensitiveoptional - case-insensitive matching preference, default to null.
Returns:
P4Cms_Record_Filter provides fluent interface. 
    {
        return parent::_add($field, $value, $comparison, $connective, $caseInsensitive);
    }
P4Cms_Record_Filter::addSearch ( $  fields,
$  query 
)

Add filters to search for keywords across the given fields.

Splits the given query string on whitespace and comma, then adds case-insensitive filters that will match any records that contain all of the keywords across the given fields

Parameters:
array | string$fieldsthe fields to match on
string$querythe user-supplied search string
Returns:
P4Cms_Record_Filter provides fluent interface. 
    {
        // normalize fields to array.
        $fields = (array) $fields;
        
        // split query into words.
        $query = preg_split('/[\s,]+/', trim($query));

        foreach ($query as $keyword) {
            $subFilter = new static();
            foreach ($fields as $field) {
                $subFilter->add(
                    $field,
                    $keyword,
                    static::COMPARE_CONTAINS,
                    static::CONNECTIVE_OR,
                    true
                );
            }
            $this->addSubFilter($subFilter, static::CONNECTIVE_AND);
        }

        return $this;
    }
P4Cms_Record_Filter::getOption ( $  name)

Retrieve a custom option by name.

Parameters:
string$namethe name of the option
Returns:
mixed $value the value(s) of the option or null if no such option. 
    {
        return isset($this->_options[$name]) ? $this->_options[$name] : null;
    }
P4Cms_Record_Filter::setOption ( $  name,
$  value 
)

Store custom filter options that don't correspond to built-in options.

Parameters:
string$namethe name of the option
mixed$valuethe value(s) of the option
Returns:
P4Cms_Record_Filter provides fluent interface. 
    {
        $this->_options[$name] = $value;

        return $this;
    }

Member Data Documentation

P4Cms_Record_Filter::$_options = array() [protected]
const P4Cms_Record_Filter::FALSE_EXPRESSION = '-'
The documentation for this class was generated from the following file: