Provides a container for query options suitable for passing to fetchAll. More...

Public Member Functions
	__construct ($options=array())
	Constructor that accepts an array of options for immediate population.
	addFilespec ($filespec)
	Add a single filespec to be fetched.
	addFilespecs ($filespecs=array())
	Add a list of filespecs to be fetched.
	getFilespecs ()
	Retrieve the list of filespecs to fetch.
	getFilter ()
	Retrieve the current filter object.
	getFstatFlags ()
	Produce set of flags for the fstat command based on current options.
	getLimitFields ()
	Retrieve the list of file fields to return in server responses.
	getLimitToChangelist ()
	Retrieve the changelist with which to limit returned files.
	getLimitToNeedsResolve ()
	Retrieve the needs resolve flag.
	getLimitToOpened ()
	Retrieve the opened files flag.
	getMaxFiles ()
	Retrieve the maximum number of files to include in results.
	getReverseOrder ()
	Retrieve the current reverse order flag setting.
	getSortBy ()
	Get the current sort field.
	getSortClauseCount ()
	Retrieve the field count available for sort clauses, which is server dependent.
	getStartRow ()
	Return the starting row for matching files.
	reset ()
	Reset the current query object to its default state.
	setFilespecs ($filespecs=null)
	Set the list of filespecs to be fetched, or null to empty the array.
	setFilter ($filter=null)
	Set the filter to limit the returned set of files.
	setLimitFields ($fields=array())
	Set the list of fields to include in the response from the server.
	setLimitToChangelist ($changelist=null)
	Set to a valid changelist to limit returned files, or null to remove the limit.
	setLimitToNeedsResolve ($limit=false)
	Sets the flag that will limit files to those that need resolve.
	setLimitToOpened ($limit=false)
	Sets the flag that will limit files to those that are opened.
	setMaxFiles ($max=null)
	Set to limit the number of matching files returned, or null to return all matching files.
	setReverseOrder ($reverse=false)
	Set the flag indicating whether the results will be returned in reverse order.
	setSortBy ($sortBy=null, $options=null)
	Set the file field(s) which will be used to sort results.
	setStartRow ($row=null)
	Set the starting row to return from matching files, or null to return all matching files.
	toArray ()
	Provide all of the current options as an array.
Static Public Member Functions
static	create ($options=array())
	Creates and returns a new Query class.
Public Attributes
const	ADD_MODE_AND = 'add'
const	ADD_MODE_OR = 'or'
const	QUERY_FILESPECS = 'filespecs'
const	QUERY_FILTER = 'filter'
const	QUERY_LIMIT_FIELDS = 'limitFields'
const	QUERY_LIMIT_TO_CHANGELIST = 'limitToChangelist'
const	QUERY_LIMIT_TO_NEEDS_RESOLVE = 'limitToNeedsResolve'
const	QUERY_LIMIT_TO_OPENED = 'limitToOpened'
const	QUERY_MAX_FILES = 'maxFiles'
const	QUERY_SORT_BY = 'sortBy'
const	QUERY_SORT_REVERSE = 'reverseOrder'
const	QUERY_START_ROW = 'startRow'
const	SORT_ASCENDING = 'a'
const	SORT_CLAUSE_COUNT_2010_2 = 2
const	SORT_DATE = '#REdate'
const	SORT_DESCENDING = 'd'
const	SORT_FILE_SIZE = '#REsize'
const	SORT_FILE_TYPE = '#NEtype'
const	SORT_HAVE_REV = '#NEhrev'
const	SORT_HEAD_REV = '#RErev'
Protected Member Functions
	_isInternalSortField ($field)
	Determine whether the field provided is a server-specific sort field.
	_isValidSortField ($field)
	Validate fort field name.
	_isValidSortOptions ($options)
	Validate sort options.
Protected Attributes
	$_options = null
	$_validFieldNames = null

Detailed Description

Provides a container for query options suitable for passing to 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

P4_File_Query::__construct ( $ options = array() )

Constructor that accepts an array of options for immediate population.

Note that options are validated and can throw exceptions.

Parameters:

array $options query options

    {
        $this->reset();
        if (isset($options) && is_array($options)) {
            foreach ($options as $key => $value) {
                if (array_key_exists($key, $this->_options)) {
                    $method = 'set'. ucfirst($key);
                    $this->$method($value);
                }
            }
        }
    }

Member Function Documentation

P4_File_Query::_isInternalSortField ( $ field ) [protected]

Determine whether the field provided is a server-specific sort field.

Parameters:

string $field The field name to check against list of internal fields.

Returns:: boolean true if the supplied field name is an internal field.

    {
        return (array_key_exists($field, $this->_validFieldNames)) ? true : false;
    }

P4_File_Query::_isValidSortField ( $ field ) [protected]

Validate fort field name.

Parameters:

string $field Field name to validate.

Returns:: boolean true if field name is valid, false otherwise.

    {
        if (!isset($field) || !is_string($field) || !strlen($field)) {
            return false;
        }

        if ($this->_isInternalSortField($field)) {
            return true;
        }

        $validator = new P4_Validate_AttributeName();
        if ($validator->isValid($field)) {
            return true;
        }

        return false;
    }

P4_File_Query::_isValidSortOptions ( $ options ) [protected]

Validate sort options.

Parameters:

array | null $options Options to validate.

Returns:: boolean true if options are valid, false otherwise.

    {
        // null is valid; we'll apply a default later.
        if (!isset($options)) {
            return true;
        }

        if (!is_array($options)) {
            return false;
        }

        // validate each option
        $seenDirection = false;
        foreach ($options as $option) {
            if ($option === static::SORT_ASCENDING
                || $option === static::SORT_DESCENDING
            ) {
                if ($seenDirection) {
                    return false;
                }
                $seenDirection = true;
                continue;
            }
            return false;
        }

        return true;
    }

P4_File_Query::addFilespec ( $ filespec )

Add a single filespec to be fetched.

The filespec may be in any one of depot, client or local file syntax with wildcards (e.g. '//depot/...'). Note: perforce applies options such as maxFiles and sortBy to each filespec individually.

Parameters:

string $filespec The filespec to add.

Returns:: P4_File_Query provide a fluent interface.

    {
        if (!isset($filespec) || !is_string($filespec)) {
            throw new InvalidArgumentException('Cannot add filespec; argument must be a string.');
        }

        return $this->addFilespecs(array($filespec));
    }

P4_File_Query::addFilespecs ( $ filespecs = array() )

Add a list of filespecs to be fetched.

The filespecs may be in any one of depot, client or local file syntax with wildcards (e.g. '//depot/...'). Note: perforce applies options such as maxFiles and sortBy to each filespec individually.

Parameters:

array $filespecs The array of filespecs to add.

Returns:: P4_File_Query provide a fluent interface.

    {
        if (!isset($filespecs) || !is_array($filespecs)) {
            throw new InvalidArgumentException('Cannot add filespecs; argument must be an array.');
        }

        $this->_options[static::QUERY_FILESPECS] = (isset($this->_options[static::QUERY_FILESPECS]))
            ? array_merge($this->_options[static::QUERY_FILESPECS], array_values($filespecs))
            : $filespecs;

        return $this;
    }

static P4_File_Query::create ( $ options = array() ) [static]

Creates and returns a new Query class.

Useful for working around PHP's lack of new chaining.

Parameters:

array $options query options

Returns:: P4_File_Query

    {
        return new static($options);
    }

P4_File_Query::getFilespecs ( )

Retrieve the list of filespecs to fetch.

Null means no filespecs will be fetched; aka query cannot run.

Returns:: array The list of filespecs.

    {
        return $this->_options[static::QUERY_FILESPECS];
    }

P4_File_Query::getFilter ( )

Retrieve the current filter object.

Null means no filtering will take place.

Returns:: string The current filter expression.

    {
        return $this->_options[static::QUERY_FILTER];
    }

P4_File_Query::getFstatFlags ( )

Produce set of flags for the fstat command based on current options.

Returns:: array set of flags suitable for passing to fstat command.

    {
        $flags = array();
        
        $filter = $this->getFilter();
        $filter = is_null($filter) ? '' : $filter->getExpression();

        // if start row set, apply rowNumber filter.
        if ($this->getStartRow()) {
            $filter = $filter ? '(' . $filter . ') & ' : '';
            $filter = $filter . 'rowNumber > ' . $this->getStartRow();
        }

        // filter option.
        if ($filter) {
            $flags[] = '-F';
            $flags[] = $filter;
        }

        // subset of fields option.
        if (count($this->getLimitFields())) {
            $flags[] = '-T';
            $flags[] = implode(' ', $this->getLimitFields());
        }

        // maximum results option.
        if ($this->getMaxFiles() !== null) {
            $flags[] = '-m';
            $flags[] = $this->getMaxFiles();
        }

        // files in change option.
        if ($this->getLimitToChangelist() !== null) {
            $flags[] = '-e';
            $flags[] = $this->getLimitToChangelist();

            // for the default change, we want to fetch opened files
            if ($this->getLimitToChangelist() === P4_Change::DEFAULT_CHANGE) {
                $this->setLimitToOpened(true);
            }
        }

        // only opened files option.
        if ($this->getLimitToOpened()) {
            $flags[] = '-Ro';
        }

        // only files that need resolve option.
        if ($this->getLimitToNeedsResolve()) {
            $flags[] = "-Ru";
        }

        // sort options.
        if ($this->getSortBy() !== null) {
            $handled = false;
            $clauses = $this->getSortBy();
            if (count($clauses) == 1) {
                list ($field, $options) = each($clauses);
                if ($this->_isInternalSortField($field) && !isset($options)) {
                    $handled = true;
                    switch ($field) {
                        case static::SORT_DATE:
                            $flags[] = '-Sd';
                            break;
                        case static::SORT_HEAD_REV:
                            $flags[] = '-Sr';
                            break;
                        case static::SORT_HAVE_REV:
                            $flags[] = '-Sh';
                            break;
                        case static::SORT_FILE_TYPE:
                            $flags[] = '-St';
                            break;
                        case static::SORT_FILE_SIZE:
                            $flags[] = '-Ss';
                            break;
                    }
                }
            }

            if (!$handled) {
                $expressions = array();
                foreach ($clauses as $field => $options) {
                    if (strpos($field, '#') !== false) {
                        $field = preg_replace('/#/', '', $field);
                    } else {
                        $field = "attr-$field";
                    }
                    if (!isset($options)) {
                        $options = array(static::SORT_ASCENDING);
                    }
                    $expressions[] = "$field=". join('', $options);
                }
                $flags[] = '-S';
                $flags[] = join(',', $expressions);
            }

        }

        // reverse sort option.
        if ($this->getReverseOrder()) {
            $flags[] = '-r';
        }

        // standard options.
        $flags[] = '-Oal';

        return $flags;
    }

P4_File_Query::getLimitFields ( )

Retrieve the list of file fields to return in server responses.

Null means all fields will be returned.

Returns:: array|null The current list of file fields.

    {
        return $this->_options[static::QUERY_LIMIT_FIELDS];
    }

P4_File_Query::getLimitToChangelist ( )

Retrieve the changelist with which to limit returned files.

Null means all restriction to changelist is not in effect.

Returns:: string|int The current limiting changelist.

    {
        return $this->_options[static::QUERY_LIMIT_TO_CHANGELIST];
    }

P4_File_Query::getLimitToNeedsResolve ( )

Retrieve the needs resolve flag.

True if only files needing resolve should be returned.

Returns:: boolean True if only files needing resolve should be returned.

    {
        return $this->_options[static::QUERY_LIMIT_TO_NEEDS_RESOLVE];
    }

P4_File_Query::getLimitToOpened ( )

Retrieve the opened files flag.

True if only opened files should be returned.

Returns:: boolean True if only opened files should be returned.

    {
        return $this->_options[static::QUERY_LIMIT_TO_OPENED];
    }

P4_File_Query::getMaxFiles ( )

Retrieve the maximum number of files to include in results.

0 or null means unlimited.

Returns:: integer The maximum number of files to include in results.

    {
        return $this->_options[static::QUERY_MAX_FILES];
    }

P4_File_Query::getReverseOrder ( )

Retrieve the current reverse order flag setting.

True means that the sort order will be reversed.

Returns:: boolean true if the sort order will be reversed.

    {
        return $this->_options[static::QUERY_SORT_REVERSE];
    }

P4_File_Query::getSortBy ( )

Get the current sort field.

Null means default sorting will take place.

Returns:: array|null The current list of sort options, or null if not set.

    {
        return $this->_options[static::QUERY_SORT_BY];
    }

P4_File_Query::getSortClauseCount ( )

Retrieve the field count available for sort clauses, which is server dependent.

In the future, this method may return different values depending on the server version in use.

Returns:: int The number of sort clauses the server supports.

    {
        return static::SORT_CLAUSE_COUNT_2010_2;
    }

P4_File_Query::getStartRow ( )

Return the starting row for matching files.

Null means all matching files will be returned.

Returns:: int|null The starting row.

    {
        return $this->_options[static::QUERY_START_ROW];
    }

P4_File_Query::reset ( )

Reset the current query object to its default state.

Returns:: P4_File_Query provide a fluent interface.

    {
        $this->_options = array(
            static::QUERY_FILTER                  => null,
            static::QUERY_SORT_BY                 => null,
            static::QUERY_SORT_REVERSE            => false,
            static::QUERY_LIMIT_FIELDS            => null,
            static::QUERY_LIMIT_TO_CHANGELIST     => null,
            static::QUERY_LIMIT_TO_NEEDS_RESOLVE  => false,
            static::QUERY_LIMIT_TO_OPENED         => false,
            static::QUERY_MAX_FILES               => null,
            static::QUERY_START_ROW               => null,
            static::QUERY_FILESPECS               => null,
        );

        $this->_validFieldNames = array(
            static::SORT_DATE       => true,
            static::SORT_HEAD_REV   => true,
            static::SORT_HAVE_REV   => true,
            static::SORT_FILE_TYPE  => true,
            static::SORT_FILE_SIZE  => true,
        );

        return $this;
    }

P4_File_Query::setFilespecs ( $ filespecs = null )

Set the list of filespecs to be fetched, or null to empty the array.

The filespecs may be in any one of depot, client or local file syntax with wildcards (e.g. '//depot/...'). Note: perforce applies options such as maxFiles and sortBy to each filespec individually.

Parameters:

array | null $filespecs The filespecs to fetch.

Returns:: P4_File_Query provide a fluent interface.

    {
        // accept a string for a single filespec, for convenience.
        if (is_string($filespecs)) {
            $filespecs = array($filespecs);
        }
        if (isset($filespecs) && !is_array($filespecs)) {
            throw new InvalidArgumentException('Cannot set filespecs; argument must be a string, an array, or null.');
        }

        $this->_options[static::QUERY_FILESPECS] = isset($filespecs) ? array_values($filespecs) : null;
        return $this;
    }

P4_File_Query::setFilter ( $ filter = null )

Set the filter to limit the returned set of files.

See 'p4 help fstat' and 'p4 help jobview' for more information on the filter format. Accepts a P4_File_Filter or string for input, or null to remove any filter.

Parameters:

string | P4_File_Filter | null $filter The desired filter.

Returns:: P4_File_Query provide a fluent interface.

    {
        if (is_string($filter)) {
            $filter = new P4_File_Filter($filter);
        }
        
        if (!$filter instanceof P4_File_Filter && !is_null($filter)) {
            throw new InvalidArgumentException(
                'Cannot set filter; argument must be a P4_File_Filter, a string, or null.'
            );
        }

        $this->_options[static::QUERY_FILTER] = $filter;
        return $this;
    }

P4_File_Query::setLimitFields ( $ fields = array() )

Set the list of fields to include in the response from the server.

Parameters:

string | array | null $fields The list of desired fields. Supply a string to specify one field, or supply a null to retrieve all fields.

Returns:: P4_File_Query provide a fluent interface.

    {
        // accept strings for a single filespec, for convenience.
        if (is_string($fields)) {
            $fields = array($fields);
        }
        if (isset($fields) && !is_array($fields)) {
            throw new InvalidArgumentException(
                'Cannot set limiting fields; argument must be a string, an array, or null.'
            );
        }

        $this->_options[static::QUERY_LIMIT_FIELDS] = $fields;
        return $this;
    }

P4_File_Query::setLimitToChangelist ( $ changelist = null )

Set to a valid changelist to limit returned files, or null to remove the limit.

Parameters:

boolean $changelist A valid changelist.

Returns:: P4_File_Query provide a fluent interface.

    {
        // accept numeric string values, for convenience.
        if (is_string($changelist)) {
            if ($changelist !== P4_Change::DEFAULT_CHANGE) {
                $changelist = (int) $changelist;
            }
        }
        if ($changelist instanceof P4_Change) {
            $changelist = $changelist->getId();
        }
        $validator = new P4_Validate_ChangeNumber;
        if (isset($changelist) && !$validator->isValid($changelist)) {
            throw new InvalidArgumentException(
                'Cannot set limit to changelist; argument must be a changelist id, a P4_Change object, or null.'
            );
        }

        $this->_options[static::QUERY_LIMIT_TO_CHANGELIST] = $changelist;
        return $this;
    }

P4_File_Query::setLimitToNeedsResolve ( $ limit = false )

Sets the flag that will limit files to those that need resolve.

True means only files that need resolve will be included.

Parameters:

boolean $limit Set to true if only files needing resolve should be returned.

Returns:: P4_File_Query provide a fluent interface.

    {
        // accept numbers or numeric string values, for convenience.
        if (is_numeric($limit) || is_string($limit)) {
            $limit = (bool) (int) $limit;
        }
        if (!is_bool($limit)) {
            throw new InvalidArgumentException('Cannot set limit to needs resolve; argument must be a boolean.');
        }

        $this->_options[static::QUERY_LIMIT_TO_NEEDS_RESOLVE] = $limit;
        return $this;
    }

P4_File_Query::setLimitToOpened ( $ limit = false )

Sets the flag that will limit files to those that are opened.

True means only files that are opened will be included.

Parameters:

boolean $limit Set to true if only opened files should be returned.

Returns:: P4_File_Query provide a fluent interface.

    {
        // accept numbers or numeric string values, for convenience.
        if (is_numeric($limit) || is_string($limit)) {
            $limit = (bool) (int) $limit;
        }
        if (!is_bool($limit)) {
            throw new InvalidArgumentException('Cannot set limit to opened files; argument must be a boolean.');
        }

        $this->_options[static::QUERY_LIMIT_TO_OPENED] = $limit;
        return $this;
    }

P4_File_Query::setMaxFiles ( $ max = null )

Set to limit the number of matching files returned, or null to return all matching files.

Parameters:

int | null $max The maximum number of files to return.

Returns:: P4_File_Query provide a fluent interface.

    {
        // accept numeric string values, for convenience.
        if (is_string($max)) {
            $max = (int) $max;
        }
        if (isset($max) && (!is_integer($max) || $max < 0)) {
            throw new InvalidArgumentException('Cannot set max files; argument must be a positive integer or null.');
        }
        if ($max === 0) {
            $max = null;
        }

        $this->_options[static::QUERY_MAX_FILES] = $max;
        return $this;
    }

P4_File_Query::setReverseOrder ( $ reverse = false )

Set the flag indicating whether the results will be returned in reverse order.

Parameters:

boolean $reverse Set to true to reverse sort order.

Returns:: P4_File_Query provide a fluent interface.

    {
        $this->_options[static::QUERY_SORT_REVERSE] = (bool) $reverse;
        return $this;
    }

P4_File_Query::setSortBy	(	$	sortBy = `null`,
		$	options = `null`
	)

Set the file field(s) which will be used to sort results.

$sortBy can be an array containing, either strings for the field name to sort (where the default option will be SORT_ASCENDING), or the field name as a key with an options array as value.

For convenience, setSortBy() can accept $sortBy as a string for the field name and an options array.

Valid sort fields are any valid attribute name, or one of the constants: SORT_DATE, SORT_HEAD_REV, SORT_HAVE_REV, SORT_FILE_TYPE, SORT_FILE_SIZE

The available sorting options include: SORT_ASCENDING and SORT_DESCENDING. Future server versions may provide other alternatives.

Specify null to receive files in the default order.

Parameters:

array \| string \| null	$sortBy	An array of fields or field => options, a string field, or default null.
array \| null	$options	Sorting options, only used when sortBy is a string.

Returns:: P4_File_Query provide a fluent interface.

    {
        // handle variations of parameter passing
        $clauses = array();
        if (is_array($sortBy)) {
            $maxClauses = $this->getSortClauseCount();
            if (count($sortBy) > $maxClauses) {
                throw new InvalidArgumentException(
                    "Cannot set sort by; argument contains more than $maxClauses clauses."
                );
            }

            // normalize sortBy clauses
            foreach ($sortBy as $field => $options) {
                if (is_integer($field) && is_string($options)) {
                    $field   = $options;
                    $options = null;
                }

                if (!is_string($field)) {
                    throw new InvalidArgumentException('Cannot set sort by; invalid sort clause provided.');
                }

                $clauses[$field] = $options;
            }
        } elseif (is_string($sortBy)) {
            $clauses = array($sortBy => $options);
        } elseif (isset($sortBy)) {
            throw new InvalidArgumentException('Cannot set sort by; argument must be an array, string, or null.');
        }

        // validate clauses
        if (isset($clauses)) {
            $counter = 0;
            foreach ($clauses as $field => $options) {
                $counter++;
                if (!$this->_isValidSortField($field)) {
                    throw new InvalidArgumentException("Cannot set sort by; invalid field name in clause #$counter.");
                }
                if (!$this->_isValidSortOptions($options)) {
                    throw new InvalidArgumentException("Cannot set sort by; invalid sort options in clause #$counter.");
                }
            }
        }

        $this->_options[static::QUERY_SORT_BY] = !empty($clauses) ? $clauses : null;
        return $this;
    }

P4_File_Query::setStartRow ( $ row = null )

Set the starting row to return from matching files, or null to return all matching files.

Parameters:

int | null $row The starting row.

Returns:: P4_File_Query provide a fluent interface.

    {
        // accept numeric string values, for convenience.
        if (is_string($row)) {
            $row = (int) $row;
        }
        if (isset($row) && (!is_integer($row) || $row < 0)) {
            throw new InvalidArgumentException('Cannot set start row; argument must be a positive integer or null.');
        }
        if ($row === 0) {
            $row = null;
        }

        $this->_options[static::QUERY_START_ROW] = $row;
        return $this;
    }

P4_File_Query::toArray ( )

Provide all of the current options as an array.

Returns:: array The current query options as an array.

    {
        return $this->_options;
    }

Member Data Documentation

P4_File_Query::$_options = null [protected]

P4_File_Query::$_validFieldNames = null [protected]

const P4_File_Query::ADD_MODE_AND = 'add'

const P4_File_Query::ADD_MODE_OR = 'or'

const P4_File_Query::QUERY_FILESPECS = 'filespecs'

const P4_File_Query::QUERY_FILTER = 'filter'

const P4_File_Query::QUERY_LIMIT_FIELDS = 'limitFields'

const P4_File_Query::QUERY_LIMIT_TO_CHANGELIST = 'limitToChangelist'

const P4_File_Query::QUERY_LIMIT_TO_NEEDS_RESOLVE = 'limitToNeedsResolve'

const P4_File_Query::QUERY_LIMIT_TO_OPENED = 'limitToOpened'

const P4_File_Query::QUERY_MAX_FILES = 'maxFiles'

const P4_File_Query::QUERY_SORT_BY = 'sortBy'

const P4_File_Query::QUERY_SORT_REVERSE = 'reverseOrder'

const P4_File_Query::QUERY_START_ROW = 'startRow'

const P4_File_Query::SORT_ASCENDING = 'a'

const P4_File_Query::SORT_CLAUSE_COUNT_2010_2 = 2

const P4_File_Query::SORT_DATE = '#REdate'

const P4_File_Query::SORT_DESCENDING = 'd'

const P4_File_Query::SORT_FILE_SIZE = '#REsize'

const P4_File_Query::SORT_FILE_TYPE = '#NEtype'

const P4_File_Query::SORT_HAVE_REV = '#NEhrev'

const P4_File_Query::SORT_HEAD_REV = '#RErev'

The documentation for this class was generated from the following file:

File/Query.php

P4_File_Query Class Reference

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation