Abstracts operations against Perforce labels. More...

Inheritance diagram for P4_Label:

Public Member Functions
	addView ($path)
	Add a view entry to this Label.
	getAccessDateTime ()
	Get the last access time for this label spec.
	getDescription ()
	Get the description for this label.
	getOptions ()
	Get options for this label.
	getOwner ()
	Get the owner of this label.
	getRevision ()
	Get the revision setting for this label.
	getUpdateDateTime ()
	Get the last update time for this label spec.
	getView ()
	Get the view for this label.
	setDescription ($description)
	Set a description for this label.
	setOptions ($options)
	Set the options for this label.
	setOwner ($owner)
	Set the owner of this label to passed value.
	setRevision ($revision)
	Set the revision setting for this label.
	setView ($view)
	Set the view for this label.
	tag ($filespecs)
	Adds the specified filespecs to this label.
Static Public Member Functions
static	exists ($id, P4_Connection_Interface $connection=null)
	Determine if the given label id exists.
static	fetchAll ($options=array(), P4_Connection_Interface $connection=null)
	Get all Labels 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 labels), produce an instance of this spec with field values set where possible.
static	_getFetchAllFlags ($options)
	Produce set of flags for the spec list command, given fetch all options array.
Static Protected Attributes
static	$_accessors
static	$_idField = 'Label'
static	$_mutators
static	$_specType = 'label'

Detailed Description

Abstracts operations against Perforce labels.

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

Given a spec entry from spec list output (p4 labels), 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_Label a (partially) populated instance of this spec class.

Reimplemented from P4_Spec_PluralAbstract.

    {
        // convert unixtimes to date string format.
        $listEntry['Access'] = date("Y/m/d G:i:s", $listEntry['Access']);
        $listEntry['Update'] = date("Y/m/d G:i:s", $listEntry['Update']);

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

static P4_Label::_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 labels 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_Label::addView ( $ path )

Add a view entry to this Label.

Parameters:

string $path the depot path to add.

Returns:: P4_Label provides a fluent interface.

    {
        $entries   = $this->getView();
        $entries[] = $path;

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

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

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

Reimplemented from P4_Spec_PluralAbstract.

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

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

        return (bool) count($labels);
    }

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

Get all Labels 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 label name pattern (e.g. 'labe*'). 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_Label::getAccessDateTime ( )

Get the last access time for this label 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_Label::getDescription ( )

Get the description for this label.

Returns:: string|null description for this label.

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

P4_Label::getOptions ( )

Get options for this label.

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

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

P4_Label::getOwner ( )

Get the owner of this label.

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

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

P4_Label::getRevision ( )

Get the revision setting for this label.

Returns:: string|null Revision setting for this label.

    {
        $revision = $this->_getValue('Revision');

        // strip quotes if needed
        if (is_string($revision) &&
            substr($revision, 0, 1) === '"' &&
            substr($revision, -1) === '"') {
            return substr($revision, 1, -1);
        }

        return $revision;
    }

P4_Label::getUpdateDateTime ( )

Get the last update time for this label 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_Label::getView ( )

Get the view for this label.

View entries will be returned as an array of strings e.g.: array ( 0 => '//depot/example/with space/...', 1 => '//depot/alternate/example/*' ) Labels view is fairly unique as each entry is only one depot path.

Returns:: array list view entries for this label, empty array if none.

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

P4_Label::setDescription ( $ description )

Set a description for this label.

Parameters:

string | null $description description for this label.

Returns:: P4_Label 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_Label::setOptions ( $ options )

Set the options for this label.

See getOptions for expected values.

Parameters:

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

Returns:: P4_Label 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_Label::setOwner ( $ owner )

Set the owner of this label to passed value.

Parameters:

string | P4_User | null $owner A string containing username

Returns:: P4_Label provides a fluent interface.

Exceptions:

InvalidArgumentException Owner is incorrect type.

    {
        if ($owner instanceof P4_User) {
            $owner = $owner->getId();
        }

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

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

P4_Label::setRevision ( $ revision )

Set the revision setting for this label.

Parameters:

string | null $revision Revision setting for this label.

Returns:: P4_Label provides a fluent interface.

Exceptions:

InvalidArgumentException revision is incorrect type.

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

        // quote string values; leaves null values alone
        if (is_string($revision)) {
            $revision = '"' . $revision . '"';
        }

        return $this->_setValue('Revision', $revision);
    }

P4_Label::setView ( $ view )

Set the view for this label.

See getView for format details.

Parameters:

array $view Array of view strings, empty array for none.

Returns:: P4_Label 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.');
        }

        foreach ($view as $entry) {
            if (!is_string($entry) || trim($entry) === "") {
                throw new InvalidArgumentException(
                   "Each view entry must be a non-empty string."
                );
            }
        }

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

P4_Label::tag ( $ filespecs )

Adds the specified filespecs to this label.

The update is completed synchronously, no need to call save.

Parameters:

array $filespecs The filespecs to add to this label, can include rev-specs

Returns:: P4_Label provides a fluent interface.

    {
        if (!is_array($filespecs) || in_array(false, array_map('is_string', $filespecs))) {
            throw new InvalidArgumentException(
                'Tag requires an array of string values for input'
            );
        }

        // there is a potential to exceed the arg-max limit;
        // run tag command as few times as possible
        $connection = $this->getConnection();
        $batches    = $connection->batchArgs($filespecs, array('-l', $this->getId()));
        foreach ($batches as $batch) {
            $connection->run('tag', $batch);
        }

        return $this;
    }

Member Data Documentation

P4_Label::$_accessors [static, protected]

Initial value:

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

Reimplemented from P4_SpecAbstract.

P4_Label::$_idField = 'Label' [static, protected]

Reimplemented from P4_Spec_PluralAbstract.

P4_Label::$_mutators [static, protected]

Initial value:

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

Reimplemented from P4_SpecAbstract.

P4_Label::$_specType = 'label' [static, protected]

Reimplemented from P4_SpecAbstract.

const P4_Label::FETCH_BY_NAME = 'name'

const P4_Label::FETCH_BY_OWNER = 'owner'

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

Label.php

P4_Label 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