Abstracts operations against Perforce user groups. More...

Inheritance diagram for P4_Group:

Public Member Functions
	addOwner ($owner)
	Adds the passed owner to the end of the current owners.
	addSubgroup ($group)
	Adds the passed group to the end of the current sub-groups.
	addUser ($user)
	Adds the passed user to the end of the current users.
	getMaxLockTime ()
	The maximum length of time (in milliseconds) that any one operation can lock any database table when scanning data.
	getMaxResults ()
	The maximum number of results that members of this group can access from the server from a single command.
	getMaxScanRows ()
	The maximum number of rows that members of this group can scan from the server from a single command.
	getOwners ()
	Returns the owners for this group.
	getSubgroups ()
	Returns the sub-groups for this group.
	getTimeout ()
	The duration (in seconds) of the validity of a session ticket created by p4 login.
	getUsers ()
	Returns the users for this group.
	isEmpty ()
	Determines if this group is 'empty'.
	save ($owner=false)
	Save this spec to Perforce.
	setMaxLockTime ($max)
	Set the MaxLockTime for this group.
	setMaxResults ($max)
	Set the MaxResults for this group.
	setMaxScanRows ($max)
	Set the MaxScanRows for this group.
	setOwners ($owners)
	Set the owners for this group.
	setSubgroups ($subgroups)
	Set the sub-groups for this group.
	setTimeout ($timeout)
	Set the Timeout for this group.
	setUsers ($users)
	Set the users for this group.
Static Public Member Functions
static	exists ($id, P4_Connection_Interface $connection=null)
	Determine if the given group id exists.
static	fetchAll ($options=array(), P4_Connection_Interface $connection=null)
	Get all Groups from Perforce.
Public Attributes
const	FETCH_BY_MEMBER = 'member'
const	FETCH_BY_NAME = 'name'
const	FETCH_INDIRECT = 'indirect'
Protected Member Functions
	_getMaxValue ($field)
	Get the value for a 'max' style field (one of MaxResults, MaxScanRows, MaxLockTime and Timeout).
	_setMaxValue ($field, $max)
	Set the value for a 'max' style field (one of MaxResults, MaxScanRows, MaxLockTime and Timeout).
Static Protected Member Functions
static	_fromSpecListEntry ($listEntry, $flags, P4_Connection_Interface $connection)
	This function is not utilized by P4_Group as our result format is incompatible.
static	_getFetchAllFlags ($options)
	Produce set of flags for the spec list command, given fetch all options array.
static	_isValidId ($id)
	Check if the given id is in a valid format for group specs.
static	_isValidUserId ($id)
	Check if the given id is in a valid format for user specs.
Static Protected Attributes
static	$_accessors
static	$_idField = 'Group'
static	$_mutators
static	$_specType = 'group'

Detailed Description

Abstracts operations against Perforce user groups.

Abandon all hope ye who go beyond this point.

Groups is a bit of an odd duck. Identified un-expected behaviour includes:

"group -i" with no populated users/owners/subgroups will report 'created' but it isn't
"groups" output is unusually formatted; see Pural Abstract for details

Copyright:: 2011-2012 Perforce Software. All rights reserved

License:: Please see LICENSE.txt in top-level folder of this distribution.

Version:: 2012.2/486814

Member Function Documentation

static P4_Group::_fromSpecListEntry	(	$	listEntry,
		$	flags,
		P4_Connection_Interface $	connection
	)		`[static, protected]`

This function is not utilized by P4_Group as our result format is incompatible.

Any attempt to call this function results in an exception.

Parameters:

array	$listEntry	a single spec entry from spec list output.
array	$flags	the flags that were used for this 'fetchAll' run.
P4_Connection_Interface	$connection	a specific connection to use.

Returns:: P4_Spec_PluralAbstract a (partially) populated instance of this spec class.

Exceptions:

BadFunctionCallException On any use of this function in this class.

Reimplemented from P4_Spec_PluralAbstract.

    {
        throw new BadFunctionCallException(
            'From Spec List Entry is not implemented in the P4_Group class.'
        );
    }

static P4_Group::_getFetchAllFlags ( $ options ) [static, protected]

Produce set of flags for the spec list command, given fetch all options array.

Extends parent to add support for filter option.

Parameters:

array $options array of options to augment fetch behavior. see fetchAll for documented options.

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

Reimplemented from P4_Spec_PluralAbstract.

    {
        // clear FETCH_MAXIMUM if present as we handle it seperately
        unset($options[self::FETCH_MAXIMUM]);

        $flags = parent::_getFetchAllFlags($options);

        if (isset($options[static::FETCH_BY_NAME])) {
            $name = $options[static::FETCH_BY_NAME];

            if (!static::_isValidId($name) && !static::_isValidUserId($name)) {
                throw new InvalidArgumentException(
                    'Filter by Name expects a valid group id.'
                );
            }

            if (isset($options[static::FETCH_INDIRECT]) ||
                isset($options[static::FETCH_BY_MEMBER])
            ) {
                throw new InvalidArgumentException(
                    'Filter by Name is not compatible with Fetch by Member or Fetch Indirect.'
                );
            }

            $flags[] = '-v';
            $flags[] = $name;
        }

        if (isset($options[static::FETCH_INDIRECT], $options[static::FETCH_BY_MEMBER])) {
            $flags[] = '-i';
        }

        if (isset($options[static::FETCH_BY_MEMBER])) {
            $member = $options[static::FETCH_BY_MEMBER];

            if (!static::_isValidId($member) && !static::_isValidUserId($member)) {
                throw new InvalidArgumentException(
                    'Filter by Member expects a valid group or username.'
                );
            }

            $flags[] = $member;
        }


        return $flags;
    }

P4_Group::_getMaxValue ( $ field ) [protected]

Get the value for a 'max' style field (one of MaxResults, MaxScanRows, MaxLockTime and Timeout).

Parameters:

string $field Name of the field to get the value from

Returns:: null|int|string null (if 'unset'), integer >0 or 'unlimited'

    {
        $max = $this->_getValue($field);

        // translate the string 'unset' to null
        if ($max === 'unset') {
            return null;
        }

        // integers come back from perforce as strings
        // casting to an int, then back to a string screens out non-digit
        // characters and allows for a 'pure digit' check.
        if ($max == (string)(int)$max) {
            return (int)$max;
        }

        return $max;
    }

static P4_Group::_isValidId ( $ id ) [static, protected]

Check if the given id is in a valid format for group specs.

Parameters:

string $id the id to check

Returns:: bool true if id is valid, false otherwise

Reimplemented from P4_Spec_PluralAbstract.

    {
        $validator = new P4_Validate_GroupName;
        return $validator->isValid($id);
    }

static P4_Group::_isValidUserId ( $ id ) [static, protected]

Check if the given id is in a valid format for user specs.

Parameters:

string $id the id to check

Returns:: bool true if id is valid, false otherwise

    {
        $validator = new P4_Validate_UserName;
        return $validator->isValid($id);
    }

P4_Group::_setMaxValue	(	$	field,
		$	max
	)		`[protected]`

Set the value for a 'max' style field (one of MaxResults, MaxScanRows, MaxLockTime and Timeout).

Valid 'max' inputs are: -null, gets converted to 'unset' -the string 'unset' -an integer greater than 0 -the string 'unlimited'

Parameters:

string	$field	Name of the field to set value on
null \| int \| string	$max	null (or 'unset'), integer >0 or 'unlimited'

Returns:: P4_Group provides a fluent interface

Exceptions:

InvalidArgumentException If input is of incorrect type of format

    {
        // ensure input is in the ballpark
        if (!is_null($max) && !is_int($max) && !is_string($max)) {
            throw new InvalidArgumentException(
                "Type of input must be one of: null, int, string"
            );
        }

        // convert null to 'unset'
        if ($max === null) {
            $max = 'unset';
        }

        // verify string format input matches expected value
        if (is_string($max) && $max !== 'unlimited' && $max !== 'unset') {
            throw new InvalidArgumentException(
                "For string input, only the values 'unlimited' and 'unset' are valid."
            );
        }

        // ensure integer input is greater than zero
        if (is_int($max) && $max <= 0) {
            throw new InvalidArgumentException(
                "For integer input, only values greater than zero are valid."
            );
        }

        return $this->_setValue($field, $max);
    }

P4_Group::addOwner ( $ owner )

Adds the passed owner to the end of the current owners.

Parameters:

string | P4_User $owner new owner to add

Returns:: P4_Group provides fluent interface.

    {
        $owners   = $this->getOwners();
        $owners[] = $owner;

        return $this->setOwners($owners);
    }

P4_Group::addSubgroup ( $ group )

Adds the passed group to the end of the current sub-groups.

Parameters:

string | P4_Group $group new group to add

Returns:: P4_Group provides fluent interface.

    {
        $subgroups = $this->getSubgroups();
        $subgroups[] = $group;

        return $this->setSubgroups($subgroups);
    }

P4_Group::addUser ( $ user )

Adds the passed user to the end of the current users.

Parameters:

string | P4_User $user new user to add

Returns:: P4_Group provides fluent interface.

    {
        $users   = $this->getUsers();
        $users[] = $user;

        return $this->setUsers($users);
    }

static P4_Group::exists	(	$	id,
		P4_Connection_Interface $	connection = `null`
	)		`[static]`

Determine if the given group id exists.

Parameters:

string	$id	the id to check for.
P4_Connection_Interface	$connection	optional - a specific connection to use.

Returns:: bool true if the given id matches an existing group.

Reimplemented from P4_Spec_PluralAbstract.

    {
        // check id for valid format
        if (!static::_isValidId($id)) {
            return false;
        }

        $groups = static::fetchAll(
            array(
                static::FETCH_BY_NAME => $id,
                static::FETCH_MAXIMUM => 1
            ),
            $connection
        );

        return (bool) count($groups);
    }

static P4_Group::fetchAll	(	$	options = `array()`,
		P4_Connection_Interface $	connection = `null`
	)		`[static]`

Get all Groups from Perforce.

Adds filtering options.

Parameters:

array	$options	optional - array of options to augment fetch behavior. supported options are: FETCH_MAXIMUM - set to integer value to limit to the first 'max' number of entries. Note: Limits imposed client side. FETCH_BY_MEMBER - get groups containing passed group or user (no wildcards). FETCH_INDIRECT - used with FETCH_BY_MEMBER to also list indirect matches. FETCH_BY_NAME - get the named group. esstentially a 'fetch' but performed differently (no wildcards). Note: not compatible with FETCH_BY_MEMBER or FETCH_INDIRECT
P4_Connection_Interface	$connection	optional - a specific connection to use.

Returns:: P4_Model_Iterator all records of this type.

Reimplemented from P4_Spec_PluralAbstract.

    {
        // the 'groups' command produces very unique output; we have taken over the parent
        // function to handle it here.

        // if no connection given, use default.
        $connection = $connection ?: static::getDefaultConnection();

        // get command to use
        $command = static::_getFetchAllCommand();

        // get fstat flags for given fetch options.
        $flags = static::_getFetchAllFlags($options);

        // fetch all specs.
        $result = $connection->run($command, $flags);

        // we manually implement FETCH_MAXIMUM for base class compatibility
        // pull out the passed value if present for later use.
        if (isset($options[self::FETCH_MAXIMUM])) {
            $max = (int) $options[self::FETCH_MAXIMUM];
        }


        // 'groups' produces the below data-block for each owner/user/sub-group
        //   array (
        //      'user'          => 'tester',
        //      'group'         => 'test',
        //      'isSubGroup'    => '0',
        //      'isOwner'       => '0',
        //      'isUser'        => '1',
        //      'maxResults'    => '0',
        //      'maxScanRows'   => '0',
        //      'maxLockTime'   => '0',
        //      'timeout'       => '43200',
        //      'isValidUser'   => '1',
        //   )

        // convert result data to spec objects.
        $specs = new P4_Model_Iterator;
        $data  = $result->getData();

        // keep outer loop running so long as we have data (and haven't hit max results)
        while (current($data) !== false) {
            $element    = current($data);
            $id         = $element['group'];
            $values     = array(
                'Group'         => $id,
                'MaxResults'    => $element['maxResults'],
                'MaxScanRows'   => $element['maxScanRows'],
                'MaxLockTime'   => $element['maxLockTime'],
                'Timeout'       => $element['timeout'],
                'Subgroups'     => array(),
                'Owners'        => array(),
                'Users'         => array()
            );

            // loop-de-loop
            // collect all data blocks for a given group
            while ($element !== false && $element['group'] == $id) {

                // defer to lazy load if FETCH_BY_MEMBER option was used
                // as result data doesn't contain all the values
                if (isset($options[self::FETCH_BY_MEMBER])) {
                    $values = array('Group' => $id);
                } else {
                    if ($element['isSubGroup'] == 1) {
                        $values['Subgroups'][]  = $element['user'];
                    }

                    if ($element['isOwner'] == 1) {
                        $values['Owners'][]     = $element['user'];
                    }

                    if ($element['isUser'] == 1) {
                        $values['Users'][]      = $element['user'];
                    }
                }

                $element = next($data);
            }

            // at this point we have all of the groups details
            // populate a spec and add it to the iterator
            $spec = new static($connection);
            $spec->_setValues($values)
                 ->_deferPopulate();

            $specs[] = $spec;

            // stop looping if we reach 'FETCH_MAXIMUM'
            if (isset($max) && count($specs) == $max) {
                break;
            }
        }

        return $specs;
    }

P4_Group::getMaxLockTime ( )

The maximum length of time (in milliseconds) that any one operation can lock any database table when scanning data.

The default value is null.

Will be an integer >0, null (if 'unset') or the string 'unlimited'

Returns:: null|int|string Null if unset, integer >0 or 'unlimited'

    {
        return $this->_getMaxValue('MaxLockTime');
    }

P4_Group::getMaxResults ( )

The maximum number of results that members of this group can access from the server from a single command.

The default value is null.

Will be an integer >0, null (if 'unset') or the string 'unlimited'

Returns:: null|int|string Null if unset, integer >0 or 'unlimited'

    {
        return $this->_getMaxValue('MaxResults');
    }

P4_Group::getMaxScanRows ( )

The maximum number of rows that members of this group can scan from the server from a single command.

The default value is null.

Will be an integer >0, null (if 'unset') or the string 'unlimited'

Returns:: null|int|string Null if unset, integer >0 or 'unlimited'

    {
        return $this->_getMaxValue('MaxScanRows');
    }

P4_Group::getOwners ( )

Returns the owners for this group.

Returns:: array owners belonging to this group

    {
        return $this->_getValue('Owners') ?: array();
    }

P4_Group::getSubgroups ( )

Returns the sub-groups for this group.

Returns:: array subgroups belonging to this group

    {
        return $this->_getValue('Subgroups') ?: array();
    }

P4_Group::getTimeout ( )

The duration (in seconds) of the validity of a session ticket created by p4 login.

The default value is 43200 seconds (12 hours). For tickets that do not expire, will return 'unlimited'.

Will be an integer >0, null (if 'unset') or the string 'unlimited'

Returns:: null|int|string Null if unset, integer >0 or 'unlimited'

    {
        return $this->_getMaxValue('Timeout');
    }

P4_Group::getUsers ( )

Returns the users for this group.

Returns:: array users belonging to this group

    {
        return $this->_getValue('Users') ?: array();
    }

P4_Group::isEmpty ( )

Determines if this group is 'empty'.

A group is considered empty if no entries are present in: -SubGroups -Owners -Users

Values in Group (id), MaxResults, MaxScanRows, MaxLockTime do not count towards 'emptiness'.

Returns:: bool True if group is empty, False otherwise

    {
        $entries =  count($this->getValue('Subgroups')) +
                    count($this->getValue('Owners')) +
                    count($this->getValue('Users'));

        return !(bool) $entries;
    }

P4_Group::save ( $ owner = false )

Save this spec to Perforce.

Extend parent to throw if group is 'empty'

Parameters:

bool $owner save the group as a group owner

Returns:: P4_SpecAbstract provides a fluent interface

Exceptions:

P4_Spec_Exception if group is empty

    {
        if ($this->isEmpty()) {
            throw new P4_Spec_Exception("Cannot save. Group is empty.");
        }

        // ensure all required fields have values.
        $this->_validateRequiredFields();

        $flags = array('-i');
        if ($owner) {
            $flags[] = '-a';
        }

        $this->getConnection()->run(
            static::_getSpecType(),
            $flags,
            $this->_getValues()
        );

        // should re-populate (server may change values).
        $this->_deferPopulate(true);

        return $this;
    }

P4_Group::setMaxLockTime ( $ max )

Set the MaxLockTime for this group.

See getMaxLockTime for more info.

The string 'unset' may be passed in place of null for convienence.

Parameters:

null | int | string $max null (or 'unset'), integer >0 or 'unlimited'

Returns:: P4_Group provides fluent interface.

    {
        return $this->_setMaxValue('MaxLockTime', $max);
    }

P4_Group::setMaxResults ( $ max )

Set the MaxResults for this group.

See getMaxResults for more info.

The string 'unset' may be passed in place of null for convienence.

Parameters:

null | int | string $max null (or 'unset'), integer >0 or 'unlimited'

Returns:: P4_Group provides fluent interface.

    {
        return $this->_setMaxValue('MaxResults', $max);
    }

P4_Group::setMaxScanRows ( $ max )

Set the MaxScanRows for this group.

See getMaxScanRows for more info.

The string 'unset' may be passed in place of null for convienence.

Parameters:

null | int | string $max null (or 'unset'), integer >0 or 'unlimited'

Returns:: P4_Group provides fluent interface.

    {
        return $this->_setMaxValue('MaxScanRows', $max);
    }

P4_Group::setOwners ( $ owners )

Set the owners for this group.

Expects an array containing user names or P4_User objects.

Parameters:

array $owners array of user names or P4_User objects

Returns:: P4_Group provides fluent interface.

    {
        if (!is_array($owners)) {
            throw new InvalidArgumentException(
                'Owners must be specified as an array.'
            );
        }

        foreach ($owners as &$owner) {
            // normalize to strings
            if ($owner instanceof P4_User) {
                $owner = $owner->getId();
            }

            if (!static::_isValidUserId($owner)) {
                throw new InvalidArgumentException(
                    'Individual owners must be a valid ID in either string or P4_User format.'
                );
            }
        }

        return $this->_setValue('Owners', $owners);
    }

P4_Group::setSubgroups ( $ subgroups )

Set the sub-groups for this group.

Expects an array containing group names or P4_Group objects.

Parameters:

array $subgroups array of group names or P4_Group objects

Returns:: P4_Group provides fluent interface.

    {
        if (!is_array($subgroups)) {
            throw new InvalidArgumentException(
                'Subgroups must be specified as an array.'
            );
        }

        foreach ($subgroups as &$group) {
            // normalize to strings
            if ($group instanceof P4_Group) {
                $group = $group->getId();
            }

            if (!static::_isValidId($group)) {
                throw new InvalidArgumentException(
                    'Individual sub-groups must be a valid ID in either string or P4_Group format.'
                );
            }
        }

        return $this->_setValue('Subgroups', $subgroups);
    }

P4_Group::setTimeout ( $ timeout )

Set the Timeout for this group.

See getTimeout for more info.

The string 'unset' may be passed in place of null for convienence.

Parameters:

null | int | string $timeout null (or 'unset'), integer >0 or 'unlimited'

Returns:: P4_Group provides fluent interface.

    {
        return $this->_setMaxValue('Timeout', $timeout);
    }

P4_Group::setUsers ( $ users )

Set the users for this group.

Expects an array containing user names or P4_User objects.

Parameters:

array $users array of user names or P4_User objects

Returns:: P4_Group provides fluent interface.

    {
        if (!is_array($users)) {
            throw new InvalidArgumentException(
                'Users must be specified as an array.'
            );
        }

        foreach ($users as &$user) {
            // normalize to strings
            if ($user instanceof P4_User) {
                $user = $user->getId();
            }

            if (!static::_isValidUserId($user)) {
                throw new InvalidArgumentException(
                    'Individual users must be a valid ID in either string or P4_User format.'
                );
            }
        }

        return $this->_setValue('Users', $users);
    }

Member Data Documentation

P4_Group::$_accessors [static, protected]

Initial value:

 array(
        'MaxResults'    => 'getMaxResults',
        'MaxScanRows'   => 'getMaxScanRows',
        'MaxLockTime'   => 'getMaxLockTime',
        'Timeout'       => 'getTimeout',
        'Subgroups'     => 'getSubgroups',
        'Owners'        => 'getOwners',
        'Users'         => 'getUsers',
    )

Reimplemented from P4_SpecAbstract.

P4_Group::$_idField = 'Group' [static, protected]

Reimplemented from P4_Spec_PluralAbstract.

P4_Group::$_mutators [static, protected]

Initial value:

 array(
        'MaxResults'    => 'setMaxResults',
        'MaxScanRows'   => 'setMaxScanRows',
        'MaxLockTime'   => 'setMaxLockTime',
        'Timeout'       => 'setTimeout',
        'Subgroups'     => 'setSubgroups',
        'Owners'        => 'setOwners',
        'Users'         => 'setUsers',
    )

Reimplemented from P4_SpecAbstract.

P4_Group::$_specType = 'group' [static, protected]

Reimplemented from P4_SpecAbstract.

const P4_Group::FETCH_BY_MEMBER = 'member'

const P4_Group::FETCH_BY_NAME = 'name'

const P4_Group::FETCH_INDIRECT = 'indirect'

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

Group.php

P4_Group Class Reference

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Static Protected Attributes

Detailed Description

Member Function Documentation

Member Data Documentation