Abstracts operations against Perforce streams. More...

Inheritance diagram for P4_Stream:

Public Member Functions
	addPath ($type, $view, $depot=null)
	Add a path to this stream.
	delete ($force=false)
	Remove this stream.
	getAccessDateTime ()
	Get the last access time for this stream.
	getDepth ()
	Returns the depth of this stream.
	getDescription ()
	Get the description for this stream.
	getName ()
	Get the name setting for this stream.
	getOptions ()
	Get options for this stream.
	getOwner ()
	Get the owner of this stream.
	getParent ()
	Get the parent setting for this stream.
	getParentObject ()
	Get the parent asociated with this stream in P4_Stream format.
	getPaths ()
	Get the paths for this stream.
	getType ()
	Get the type setting for this stream.
	getUpdateDateTime ()
	Get the last update time for this stream.
	save ()
	Save this spec to Perforce.
	setDescription ($description)
	Set a description for this stream.
	setName ($name)
	Set the name for this stream.
	setOptions ($options)
	Set the options for this stream.
	setOwner ($owner)
	Set the owner of this stream to passed value.
	setParent ($parent)
	Set the parent for this stream.
	setPaths ($paths)
	Set the paths for this stream.
	setType ($type)
	Set the type for this stream.
Static Public Member Functions
static	exists ($id, P4_Connection_Interface $connection=null)
	Determine if the given stream id exists.
static	fetchAll ($options=array(), P4_Connection_Interface $connection=null)
	Get all Streams from Perforce.
Public Attributes
const	FETCH_BY_FILTER = 'filter'
const	FETCH_BY_PATH = 'path'
const	SORT_RECURSIVE = 'sort'
Static Protected Member Functions
static	_fromSpecListEntry ($listEntry, $flags, P4_Connection_Interface $connection)
	Given a spec entry from spec list output (p4 streams), 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	_isValidId ($id)
	Check if the given id is in a valid format for this spec type.
static	_sortRecursively ($streams, $parent=null)
	This method will ensure the list of streams is in the proper order with children listed after their associated parents.
Protected Attributes
	$_cache = array()
Static Protected Attributes
static	$_accessors
static	$_idField = 'Stream'
static	$_mutators
static	$_specType = 'stream'

Detailed Description

Abstracts operations against Perforce streams.

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

Given a spec entry from spec list output (p4 streams), 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_Stream 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']);

        // move the description into place
        $listEntry['Description'] = $listEntry['desc'];
        unset($listEntry['desc']);

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

static P4_Stream::_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_FILTER])) {
            $filter = $options[static::FETCH_BY_FILTER];

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

            $flags[] = '-F';
            $flags[] = $filter;
        }

        if (isset($options[static::FETCH_BY_PATH])) {
            $flags[] = $options[static::FETCH_BY_PATH];
        }

        return $flags;
    }

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

Check if the given id is in a valid format for this spec type.

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_StreamName;
        return $validator->isValid($id);
    }

static P4_Stream::_sortRecursively	(	$	streams,
		$	parent = `null`
	)		`[static, protected]`

This method will ensure the list of streams is in the proper order with children listed after their associated parents.

Parameters:

P4_Model_Iterator	$streams	the streams to sort
string \| null	$parent	the parent id (used for recursion)

Returns:: P4_Model_Iterator The recursively sorted result

    {
        // get branches with given parent and sort them
        $children = $streams->filter('Parent', array($parent), P4_Model_Iterator::FILTER_COPY)
                            ->sortBy('Name', array(P4_Model_Iterator::SORT_NATURAL));

        // assemble list and append sorted sub-entries below their parent
        $sorted = new P4_Model_Iterator;
        foreach ($children as $stream) {
            $sorted[] = $stream;
            foreach (static::_sortRecursively($streams, $stream->getId()) as $sub) {
                $sorted[] = $sub;
            }
        }

        return $sorted;
    }

P4_Stream::addPath	(	$	type,
		$	view,
		$	depot = `null`
	)

Add a path to this stream.

Parameters:

string	$type	the path type (share/isolate/import/exclude)
string	$view	the view path
string \| null	$depot	the depot path (only used for import type)

Returns:: P4_Stream provides a fluent interface.

    {
        $paths   = $this->getPaths();
        $paths[] = array("type" => $type, "view" => $view, "depot" => $depot);

        return $this->setPaths($paths);
    }

P4_Stream::delete ( $ force = false )

Remove this stream.

Extend parent to remove all clients dedicated to this stream first.

Parameters:

boolean $force pass true to force delete this stream, additionally attempts to delete any clients using this stream by default stream will only be deleted if there are no clients current using the stream and current user is the stream owner or the stream is unlocked.

Returns:: P4_Stream provides fluent interface.

    {
        // remove clients dedicated to this stream if force is true
        if ($force) {
            P4_Client::fetchAll(
                array(P4_Client::FETCH_BY_STREAM => $this->getId())
            )->invoke('delete', array($force));
        }

        return parent::delete($force ? array('-f') : null);
    }

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

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

Reimplemented from P4_Spec_PluralAbstract.

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

        $streams = static::fetchAll(array(static::FETCH_BY_FILTER => "Stream=$id"), $connection);

        return (bool) count($streams);
    }

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

Get all Streams from Perforce.

Adds the following filter options: FETCH_BY_PATH - limits results to streams matching path (can include wildcards). FETCH_BY_FILTER - a 'jobview' style expression to limit results. SORT_RECURSIVE - optionally sort the results recusively

Parameters:

array	$options	optional - options to augment fetch behavior.
P4_Connection_Interface	$connection	optional - a specific connection to use.

Returns:: P4_Model_Iterator all records of this type matching options.

Reimplemented from P4_Spec_PluralAbstract.

    {
        // try/catch parent to deal with the exception we get on non-existend depots
        try {
            $streams = parent::fetchAll($options, $connection);

            // set the 'parent' stream on each entry if we have a copy
            foreach ($streams as $stream) {
                // skip any streams without parents
                if (!$stream->getParent()) {
                    continue;
                }

                // attempt to locate the parent object in our result set and set it
                $parent = $streams->filter('Stream', $stream->getParent(), P4_Iterator::FILTER_COPY)
                                  ->first();

                if ($parent) {
                    $stream->_cache['parentObject'] = $parent;
                }
            }

            // apply sorting if it has been requested
            if (isset($options[static::SORT_RECURSIVE]) && $options[static::SORT_RECURSIVE]) {
                $streams = static::_sortRecursively($streams);
            }

            return $streams;
        } catch (P4_Connection_CommandException $e) {
            // if the 'depot' has been interpreted as an invalid client, just return no matches
            if (preg_match("/Command failed: .+ - must refer to client/", $e->getMessage())) {
                return new P4_Model_Iterator;
            }

            // unexpected error; rethrow it
            throw $e;
        }
    }

P4_Stream::getAccessDateTime ( )

Get the last access time for this stream.

This value is read only, no setAccessDateTime 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_Stream::getDepth ( )

Returns the depth of this stream.

Assumes all parent objects are returnable.

Returns:: int the depth of this stream.

    {
        $stream = $this;
        for ($i = 0; $stream = $stream->getParentObject(); $i++);

        return $i;
    }

P4_Stream::getDescription ( )

Get the description for this stream.

Returns:: string|null description for this stream.

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

P4_Stream::getName ( )

Get the name setting for this stream.

Returns:: string|null Name set for this stream or null.

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

P4_Stream::getOptions ( )

Get options for this stream.

Returned array will contain one option per element e.g.: array ( 0 => 'allsubmit', 1 => 'toparent', 2 => 'unlocked' )

Returns:: array options which are set on this stream.

    {
        $options = $this->_getValue('Options');
        $options = explode(' ', $options);

        // Explode will set key 0 to null for empty input; clean it up.
        if (count($options) == 1 && empty($options[0])) {
            $options = array();
        }

        return $options;
    }

P4_Stream::getOwner ( )

Get the owner of this stream.

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

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

P4_Stream::getParent ( )

Get the parent setting for this stream.

Returns:: string|null Parent set for this stream.

    {
        $parent = $this->_getValue('Parent');

        return $parent == 'none' ? null : $parent;
    }

P4_Stream::getParentObject ( )

Get the parent asociated with this stream in P4_Stream format.

Returns:: P4_Stream|null this streams parent object or null if none

    {
        if (!$this->getParent()) {
            return null;
        }

        if (!isset($this->_cache['parentObject'])
            || !$this->_cache['parentObject'] instanceof P4_Stream
        ) {
            $this->_cache['parentObject'] = P4_Stream::fetch(
                $this->getParent(),
                $this->getConnection()
            );
        }

        return clone $this->_cache['parentObject'];
    }

P4_Stream::getPaths ( )

Get the paths for this stream.

Path entries will be returned as an array with 'type', 'view' and 'depot' entries, e.g.: array ( 0 => array ( 'type' => 'share', 'view' => 'src/...', 'depot' => null ) 1 => array ( 'type' => 'import', 'view' => 'src/...', 'depot' => '//over/there/src/...' ) )

Returns:: array list path entries for this stream.

    {
        // The raw path data is formatted as:
        //  array (
        //      0 => 'share ...',
        //      1 => 'import imp/ //depot/other/local/...'
        //  )

        $paths = array();
        foreach ($this->_getValue('Paths') ?: array() as $entry) {
            $entry = str_getcsv($entry, ' ');
            $paths[] = array_combine(
                array('type', 'view', 'depot'),
                $entry + array(null, null, null)
            );
        }

        return $paths;
    }

P4_Stream::getType ( )

Get the type setting for this stream.

Returns:: string|null Type set for this stream.

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

P4_Stream::getUpdateDateTime ( )

Get the last update time for this stream.

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

If this is a brand new stream, 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_Stream::save ( )

Save this spec to Perforce.

Extends parent to provide a default value of 'none' for parent.

Returns:: P4_Stream provides a fluent interface

Reimplemented from P4_SpecAbstract.

    {
        if (!$this->getValue('Parent')) {
            $this->setValue('Parent', 'none');
        }

        return parent::save();
    }

P4_Stream::setDescription ( $ description )

Set a description for this stream.

Parameters:

string | null $description description for this stream.

Returns:: P4_Stream 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_Stream::setName ( $ name )

Set the name for this stream.

Parameters:

string | null $name Name for this stream or null

Returns:: P4_Stream provides a fluent interface.

Exceptions:

InvalidArgumentException Name is incorrect type.

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

        return $this->_setValue('Name', $name);
    }

P4_Stream::setOptions ( $ options )

Set the options for this stream.

Accepts an array, format detailed in getOptions, or a single string containing a space seperated list of options.

Parameters:

array | string $options options to set on this stream in array or string.

Returns:: P4_Steam provides a fluent interface.

Exceptions:

InvalidArgumentException Options are incorrect type.

    {
        if (is_array($options)) {
            $options = implode(' ', $options);
        }

        if (!is_string($options)) {
            throw new InvalidArgumentException('Options must be an array or string');
        }

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

P4_Stream::setOwner ( $ owner )

Set the owner of this stream to passed value.

Parameters:

string | null $owner A string containing username

Returns:: P4_Stream 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_Stream::setParent ( $ parent )

Set the parent for this stream.

Parameters:

string | null $parent Parent for this stream or null

Returns:: P4_Stream provides a fluent interface.

Exceptions:

InvalidArgumentException Parent is incorrect type.

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

        // clear cache as parent may have changed
        $this->_cache = array();

        return $this->_setValue('Parent', $parent);
    }

P4_Stream::setPaths ( $ paths )

Set the paths for this stream.

Paths are passed as an array of path entries. Each patj entry can be an array with 'type', 'view' and, optionally, 'depot' entries or a raw string.

Parameters:

array | string $paths Path entries, formatted as sub-arrays or strings.

Returns:: P4_Stream provides a fluent interface.

Exceptions:

InvalidArgumentException Paths array, or a path entry, is incorrect type.

    {
        // we let the caller pass in a single path and normalize it below
        if (is_string($paths) || isset($paths['type'], $paths['view'])) {
            $paths = array($paths);
        }

        if (!is_array($paths)) {
            throw new InvalidArgumentException('Paths must be passed as array or string.');
        }

        // The Paths array contains either:
        // - Child arrays keyed on type/view/[depot] which we glue together
        // - Raw strings which we simply leave as is
        // The below foreach run will normalize the whole thing for storage
        $parsedPaths = array();
        foreach ($paths as $path) {
            if (is_array($path)
                && isset($path['type'], $path['view'])
                && is_string($path['type'])
                && is_string($path['view'])
                && (!isset($path['depot']) || is_string($path['depot']))
            ) {
                // stringify the path quoting paths to be safe
                $string = $path['type'] . ' "' . $path['view'] . '"';
                if (isset($path['depot']) && strlen($path['depot'])) {
                    $string .= ' "' . $path['depot'] . '"';
                }

                $path = $string;
            }

            if (!is_string($path)) {
                throw new InvalidArgumentException(
                   "Each path entry must be an array with type/view (and optionally depot) or a string."
                );
            }

            $validate = str_getcsv($path, ' ');
            if (count($validate) < 2 || count($validate) > 3
                || trim($validate[0]) === '' || trim($validate[1]) === ''
            ) {
                throw new InvalidArgumentException(
                   "Each path entry must contain between two and three entries."
                );
            }

            $parsedPaths[] = $path;
        };

        return $this->_setValue('Paths', $parsedPaths);
    }

P4_Stream::setType ( $ type )

Set the type for this stream.

Parameters:

string | null $type Type for this stream or null

Returns:: P4_Stream provides a fluent interface.

Exceptions:

InvalidArgumentException Type is incorrect type.

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

        return $this->_setValue('Type', $type);
    }

Member Data Documentation

P4_Stream::$_accessors [static, protected]

Initial value:

 array(
        'Update'        => 'getUpdateDateTime',
        'Access'        => 'getAccessDateTime',
        'Owner'         => 'getOwner',
        'Name'          => 'getName',
        'Parent'        => 'getParent',
        'Type'          => 'getType',
        'Description'   => 'getDescription',
        'Options'       => 'getOptions',
        'Paths'         => 'getPaths'
    )

Reimplemented from P4_SpecAbstract.

P4_Stream::$_cache = array() [protected]

P4_Stream::$_idField = 'Stream' [static, protected]

Reimplemented from P4_Spec_PluralAbstract.

P4_Stream::$_mutators [static, protected]

Initial value:

 array(
        'Owner'         => 'setOwner',
        'Name'          => 'setName',
        'Parent'        => 'setParent',
        'Type'          => 'setType',
        'Description'   => 'setDescription',
        'Options'       => 'setOptions',
        'Paths'         => 'setPaths'
    )

Reimplemented from P4_SpecAbstract.

P4_Stream::$_specType = 'stream' [static, protected]

Reimplemented from P4_SpecAbstract.

const P4_Stream::FETCH_BY_FILTER = 'filter'

const P4_Stream::FETCH_BY_PATH = 'path'

const P4_Stream::SORT_RECURSIVE = 'sort'

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

Stream.php

P4_Stream Class Reference

Public Member Functions

Static Public Member Functions

Public Attributes

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Function Documentation

Member Data Documentation