Abstracts operations against Perforce branch specs. More...

Inheritance diagram for P4_Branch:

Public Member Functions
	addView ($source, $target)
	Add a view mapping to this Branch.
	getAccessDateTime ()
	Get the last access time for this branch spec.
	getDescription ()
	Get the description for this branch.
	getOptions ()
	Get options for this branch.
	getOwner ()
	Get the owner of this branch.
	getUpdateDateTime ()
	Get the last update time for this branch spec.
	getView ()
	Get the view for this branch.
	setDescription ($description)
	Set a description for this branch.
	setOptions ($options)
	Set the options for this branch.
	setOwner ($owner)
	Set the owner of this branch to passed value.
	setView ($view)
	Set the view for this branch.
Static Public Member Functions
static	exists ($id, P4_Connection_Interface $connection=null)
	Determine if the given branch id exists.
static	fetchAll ($options=array(), P4_Connection_Interface $connection=null)
	Get all Branches from Perforce.
Public Attributes
const	FETCH_BY_NAME = 'name'
const	FETCH_BY_OWNER = 'owner'
Static Protected Member Functions
static	_fromSpecListEntry ($listEntry, $flags, P4_Connection_Interface $connection)
	Given a spec entry from spec list output (p4 branches), produce an instance of this spec with field values set where possible.
static	_getFetchAllCommand ()
	Get the fetch all command, generally a plural version of the spec type.
static	_getFetchAllFlags ($options)
	Produce set of flags for the spec list command, given fetch all options array.
Static Protected Attributes
static	$_accessors
static	$_idField = 'Branch'
static	$_mutators
static	$_specType = 'branch'

Detailed Description

Abstracts operations against Perforce branch specs.

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_Branch::_fromSpecListEntry	(	$	listEntry,
		$	flags,
		P4_Connection_Interface $	connection
	)		`[static, protected]`

Given a spec entry from spec list output (p4 branches), produce an instance of this spec with field values set where possible.

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_Branch a (partially) populated instance of this spec class.

Reimplemented from P4_Spec_PluralAbstract.

    {
        // update/access time are return as longs. Unset to avoid figuring out timezone
        // for a proper conversion.
        unset($listEntry['update']);
        unset($listEntry['access']);

        return parent::_fromSpecListEntry($listEntry, $flags, $connection);
    }

static P4_Branch::_getFetchAllCommand ( ) [static, protected]

Get the fetch all command, generally a plural version of the spec type.

Returns:: string Perforce command to use for fetchAll

Reimplemented from P4_Spec_PluralAbstract.

    {
        // Branch is a special case; over-ridden to add 'es' instead of 's' to spec type.
        return static::_getSpecType() . "es";
    }

static P4_Branch::_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.

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

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

            if (!is_string($name) || trim($name) === "") {
                throw new InvalidArgumentException(
                    'Filter by Name expects a non-empty string as input'
                );
            }

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

        if (isset($options[static::FETCH_BY_OWNER])) {
            $owner = $options[static::FETCH_BY_OWNER];

            // We allow empty values as this returns branches with no owner
            if (!is_string($owner) || trim($owner) === "") {
                throw new InvalidArgumentException(
                    'Filter by Owner expects a non-empty string as input'
                );
            }

            $flags[] = '-u';
            $flags[] = $owner;
        }

        return $flags;
    }

P4_Branch::addView	(	$	source,
		$	target
	)

Add a view mapping to this Branch.

Parameters:

string	$source	the source half of the view mapping.
string	$target	the target half of the view mapping.

Returns:: P4_Branch provides a fluent interface.

    {
        $mappings   = $this->getView();
        $mappings[] = array("source" => $source, "target" => $target);

        return $this->setView($mappings);
    }

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

Determine if the given branch 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 branch.

Reimplemented from P4_Spec_PluralAbstract.

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

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

        return (bool) count($branches);
    }

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

Get all Branches 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. FETCH_BY_NAME - set to branch name pattern (e.g. 'bran*'). FETCH_BY_OWNER - set to owner's username (e.g. 'jdoe').

Parameters:

P4_Connection_Interface $connection optional - a specific connection to use.

Returns:: P4_Model_Iterator all records of this type.

Reimplemented from P4_Spec_PluralAbstract.

    {
        // simply return parent - method exists to document options.
        return parent::fetchAll($options, $connection);
    }

P4_Branch::getAccessDateTime ( )

Get the last access time for this branch spec.

This value is read only, no setAccessTime function is provided.

If this is a brand new spec, null will be returned in lieu of a time.

Returns:: string|null Date/Time of last access, formatted "2009/11/23 12:57:06" or null

    {
        return $this->_getValue('Access');
    }

P4_Branch::getDescription ( )

Get the description for this branch.

Returns:: string description for this branch.

    {
        return $this->_getValue('Description');
    }

P4_Branch::getOptions ( )

Get options for this branch.

Returns:: string options which are set on this branch ('locked' or 'unlocked').

    {
        return $this->_getValue('Options');
    }

P4_Branch::getOwner ( )

Get the owner of this branch.

Returns:: string|null User who owns this record.

    {
        return $this->_getValue('Owner');
    }

P4_Branch::getUpdateDateTime ( )

Get the last update time for this branch spec.

This value is read only, no setUpdateTime function is provided.

If this is a brand new spec, null will be returned in lieu of a time.

Returns:: string|null Date/Time of last update, formatted "2009/11/23 12:57:06" or null

    {
        return $this->_getValue('Update');
    }

P4_Branch::getView ( )

Get the view for this branch.

View entries will be returned as an array with 'source' and 'target' entries, e.g.: array ( 0 => array ( 'source' => '//depot/branchA/with space/...', 'target' => '//depot/branchB/with space/...' ) )

Returns:: array list view entries for this branch.

    {
        // The raw view data is formatted as:
        //  array (
        //      0 => '"//depot/example/with space/..." //depot/example/nospace/...',
        //  )
        //
        // We split this into 'source' and 'target' components via the str_getcsv function
        // and key the two resulting entries as 'source' and 'target'
        $view = array();
        // The ?: translates empty views into an empty array
        foreach ($this->_getValue('View') ?: array() as $entry) {
            $entry = str_getcsv($entry, ' ');
            $view[] = array_combine(array('source','target'), $entry);
        }

        return $view;
    }

P4_Branch::setDescription ( $ description )

Set a description for this branch.

Parameters:

string | null $description description for this branch.

Returns:: P4_Branch provides a fluent interface.

Exceptions:

InvalidArgumentException Description is incorrect type.

    {
        if (!is_string($description) && !is_null($description)) {
            throw new InvalidArgumentException('Description must be a string or null.');
        }

        return $this->_setValue('Description', $description);
    }

P4_Branch::setOptions ( $ options )

Set the options for this branch.

See getOptions for expected values.

Parameters:

string | null $options options to set on this branch.

Returns:: P4_Branch provides a fluent interface.

Exceptions:

InvalidArgumentException Options are incorrect type.

    {
        if (!is_string($options) && !is_null($options)) {
            throw new InvalidArgumentException('Options must be a string or null.');
        }

        return $this->_setValue('Options', $options);
    }

P4_Branch::setOwner ( $ owner )

Set the owner of this branch to passed value.

Parameters:

string | null $owner A string containing username or null for none

Returns:: P4_Branch provides a fluent interface.

Exceptions:

InvalidArgumentException Owner is incorrect type.

    {
        if (!is_string($owner) && !is_null($owner)) {
            throw new InvalidArgumentException('Owner must be a string or null.');
        }

        return $this->_setValue('Owner', $owner);
    }

P4_Branch::setView ( $ view )

Set the view for this branch.

View is passed as an array of view entries. Each view entry can be an array with 'source' and 'target' entries or a raw string.

Parameters:

array $view View entries, formatted into source/target sub-arrays.

Returns:: P4_Branch provides a fluent interface.

Exceptions:

InvalidArgumentException View array, or a view entry, is incorrect type.

    {
        if (!is_array($view)) {
            throw new InvalidArgumentException('View must be passed as array.');
        }

        // The View array contains either:
        // - Child arrays keyed on source/target which we glue together
        // - Raw strings which we simply leave as is
        // The below foreach run will normalize the whole thing for storage
        $parsedView = array();
        foreach ($view as $entry) {
            if (is_array($entry) &&
                isset($entry['source'], $entry['target']) &&
                is_string($entry['source']) &&
                is_string($entry['target'])) {
                $entry = '"'. $entry['source'] .'" "'. $entry['target'] .'"';
            }

            if (!is_string($entry)) {
                throw new InvalidArgumentException(
                   "Each view entry must be a 'source' and 'target' array or a string."
                );
            }

            $validate = str_getcsv($entry, ' ');
            if (count($validate) != 2 || trim($validate[0]) === '' || trim($validate[1]) === '') {
                throw new InvalidArgumentException(
                   "Each view entry must contain two depot paths, no more, no less."
                );
            }

            $parsedView[] = $entry;
        };

        return $this->_setValue('View', $parsedView);
    }

Member Data Documentation

P4_Branch::$_accessors [static, protected]

Initial value:

 array(
        'Update'        => 'getUpdateDateTime',
        'Access'        => 'getAccessDateTime',
        'Owner'         => 'getOwner',
        'Description'   => 'getDescription',
        'Options'       => 'getOptions',
        'View'          => 'getView'
    )

Reimplemented from P4_SpecAbstract.

P4_Branch::$_idField = 'Branch' [static, protected]

Reimplemented from P4_Spec_PluralAbstract.

P4_Branch::$_mutators [static, protected]

Initial value:

 array(
        'Owner'         => 'setOwner',
        'Description'   => 'setDescription',
        'Options'       => 'setOptions',
        'View'          => 'setView'
    )

Reimplemented from P4_SpecAbstract.

P4_Branch::$_specType = 'branch' [static, protected]

Reimplemented from P4_SpecAbstract.

const P4_Branch::FETCH_BY_NAME = 'name'

const P4_Branch::FETCH_BY_OWNER = 'owner'

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

library/P4/Branch.php

P4_Branch Class Reference

Public Member Functions

Static Public Member Functions

Public Attributes

Static Protected Member Functions

Static Protected Attributes

Detailed Description

Member Function Documentation

Member Data Documentation